Table of Contents
gitbacked Plugin
Compatible with DokuWiki
- 2024-02-06 "Kaos" unknown
- 2023-04-04 "Jack Jackrum" yes
- 2022-07-31 "Igor" yes
- 2020-07-29 "Hogfather" yes
Sync/store DokuWiki pages and media in a git repository. On saving page edits or on media file uploads DokuWiki will commit these changes to a git repository. If configured, commits will be pushed to a remote repo.
Similar to git
Installation
Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually. For all releases and release notes look at gitbacked releases.
Suggested Directories / Structure
To avoid conflicts with the git repository and the DokuWiki files/directories we suggest to use a different directory structure.
For example, add the following setting values to your local.php in the global conf directory of your DokuWiki Installation.
$conf['datadir'] = './data/gitrepo/wiki/pages';$conf['mediadir'] = './data/gitrepo/wiki/media';
Attention: Do not forget to move the original pages and media folders (./data/pages and ./data/media) to the new location (./data/gitrepo/wiki/), otherwise DokuWiki will not find any pages and media files.
If you use this structure, you have to setup the corresponding paths for this plugin as well (in the Admin-Area of DokuWiki in the section gitbacked). Set:
repoPathto./data/gitrepo(relative to thedokuwikiroot folder or absolute path)
This means, that all wiki related files are located in the directory wiki in your git repository.
repoWorkDir had to be configured in the past. This is now empty by default (since 2023-03-07). repoWorkDir is passed to git as –work-tree option only if it is configured. You should configure this only if you are aware about the impact. repoPath and repoWorkDir can be configured as absolute path names also since release 2023-03-07.
The plugin creates a new repository in the specified repoPath, if needed. If you want to use an existing git repository, clone the repository to e.g. /tmp/yourrepo. Subsequently, copy all data (don't forget the .git folder) from /tmp/yourrepo to ./data/gitrepo.
Congrats! You are finished and every page edit is committed to the git repository.
Push to Remote Repo
If you want to push all changes to the remote origin, enable the pushAfterCommit setting in the next section.
Make sure you have properly configured your local repo with a remote origin and that the git credentials for the remote access are configured for git appropriately. The remote credentials are not configured by gitbacked.
In case of a https URL access to the remote repo you can simply configure the remote URL with the credentials e.g. for GitHub by
git add remote origin https://user@accessToken@github.com/user/repo.git
Configuration and Settings
pushAfterCommit | If activated, every commit (page edit) is pushed to the remote repository. Activate this flag if you already cloned from a remote location and the git environment is configured correctly (It has to be configured for the webserver/php user) The push will be performed within the http POST roundtrip of the page save. If this leads to insufficient user experience since of remote git server communcation delays, you should not activate this config and consider a CRON job as an alternative to perform the pushes periodically and independent of DokuWiki sessions. |
periodicPull | If activated, the system executes a pull request and updates the local git repository. Thus, external commits on page files are merged from the remote. |
periodicMinutes | Defines the period (in minutes) for the periodic pull request executions. |
commitMsgcommitMsgDelcommitMediaMsgcommitMediaMsgDel | The template strings which are used for the different commit messages (page edits, media edits, page deletion, media deletion). The placeholders %page%,%media%, %summary% and %user% can be used and are replaced by the corresponding values during the commit process. |
repoPath | The path to your git repository (root) – set to the savedir by default (./data).This must be configured either as a relative path (relative to the savedir) or as an absolute path. Absolute path configuration is supported since release 2023-03-07. |
repoWorkDir | This path is passed to the git command as the –work-tree commandline option if it is configured.It can be configured as relative path (relative to the savedir) or as an absolute path. Since release 2023-03-07 you should configure this only if you are aware about the impact. default=Empty string |
ignorePaths | Paths or files (comma separated) that will be ignored and not added by git (currently simple wildcard string matching of paths is performed). |
gitPath | Path to the git binary (if empty, the default “/usr/bin/git” will be used). |
addParams | Specify additional parameters for the git binary. For example, if you cannot set default git configuration values for the webserver's system user you can add some basic information by specifying additional parameters. For example -c http.sslVerify=false -c user.email="<%mail%>" -c user.name="%user%" deactivates the SSL certificate check and specifies the user's email and name which are used as commit author.The value in addParams is placed directly after the git binary for the git command executed by gitbacked.The variables %mail% and %user% can be used as placeholders and are replaced by the corresponding properties configured for the DokuWiki user being logged in. default=-c user.name="%user%" -c user.email="<%mail%>" |
emailAddressOnError | If defined, in case of a git error an eMail will be sent to this address rather than confusing the end user by the Exception raised. Multiple mail addresses can be configured comma separated. |
notifyByMailOnSuccess | If set, an eMail will be sent on any git commit. This is supposed to be used for eMail notification test purposes only. |
updateIndexOnPull | If set, the page(s) updated by a periodic pull will be indexed. |
Cloning your Git repo
If your DokuWiki is deployed on a webhost and you wish to clone the repo over http onto your local machine or onto a different remote, then you may discover that the ./data/.git directory is forbidden. so you won't be able to clone that way, and You will have to clone over ssh instead. If you wish to configure the .htaccess to enable read permissions in your ./data/.git, here's how to do it:
please answer this question if you know, thanks.
Known Bugs and Issues
Please, use Github GitBacked Issues