Learn about DokuWiki
Learn about DokuWiki
Until January 2010, the DokuWiki sources were managed through Darcs1). We now use git and you should refer to the git page on how to contribute to DokuWiki. Because some DokuWiki plugins are still maintained in darcs, this page remains here for reference purposes.
Darcs is a replacement for CVS. Darcs is simple to learn and use, with a powerful new approach to meet the needs of today's distributed software projects. Darcs is decentralized, based on a “theory of patches” with roots in quantum mechanics. Darcs is free software, licensed under the GPL.
Instead of repeating things that were said elsewhere I just want to give some pointers:
To fetch the current development version of DokuWiki use the following command (This creates the directory dokuwiki for you):
darcs get --partial http://dev.splitbrain.org/darcs/dokuwiki
To update an existing checkout use this command from within the DokuWiki directory:
When you create a new source file, use this command to add it to the darcs repository:
darcs add somenewfile
When you're finished with your changes use:
This will scan your local darcs repository to find the changes that have occurred and will locally “commit” your changes so that they are not overwritten by a
pull. Unlike CVS it doesn't actually send the files anywhere at this point though. It's more like a “local tag” for your own copy of the code.
To get your changes included in the official tree, create a patchfile:
darcs send -o my_doku_patch_file
This creates a patch file that can be mailed manually to the mailinglist.
amend-recordcommand after you sent a patch with
darcs sendthis will most likely create conflicts! Instead just create another patch which fixes the first one.
recordtwo patches, with one for each feature. darcs makes that easy for you by asking what to include in the patch.
Because each checkout is its own repository people can keep their own modifications as patchsets and can still update from the “master repository”.
So how does this work in practice? Darcs can't do magic, if you change something in your local repository and the same is changed in the “master repository” you'll get a conflict - there is nothing any RCS can do about this.
However if you make minor changes that aren't touched in the upstream version you should get no problem when updating from the official repository. This is because darcs just applies patches. As long as darcs finds enough context to apply the patch it should work.
For example if you add some HTML to one of the functions in
html.php you still should be able to apply the official patches to
html.php by doing a simple
Darcs isn't only for DokuWiki developers, it can be used to get the latest stable version and to update to the next stable version when it is released.
To get a particular release of DokuWiki (replace yyyy-mm-dd with the date of the release, e.g. 2006-11-06):
darcs get --partial --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki
Unfortunately darcs contains a bug that causes problems when
–tag are used together. Until the bug is fixed, it is better to leave out the
partial and just use:
darcs get --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki
To update to a specific release, a release candidate or the latest release (stable):
darcs pull --tags "release yyyy-mm-dd" --all --quiet darcs pull --tags "release candidate yyyy-mm-dd" --all --quiet darcs pull --tags "release stable" --all --quiet
–all –quiet ensures all patches are applied and darcs gets on and does its stuff without reams and reams of messages.
If you have made your own changes to DokuWiki's core codebase, it may be better to leave off the
–all –quiet switches and accept each patch interactively, e.g.:
darcs pull --tags "release yyyy-mm-dd" darcs pull --tags "release candidate yyyy-mm-dd" darcs pull --tags "release stable"
At the end of the patching process Darcs will let you know if there were any conflicts between your changes and the patches applied to make the new version. You can then examine the files in question and make any necessary changes.
You can use the following command to keep track of the changes you have made to DokuWiki:
When run interactively the revert command will do something similar and give you the opportunity to remove your changes if they are no longer required.
Darcs has, in my opinion, several advantages:
There are some disadvantages though:
What I like most are the patchsets. Because each checkout is its own repository people can keep their own modifications as patchsets and can still update from my “master repository”, see the above section for a short explanation.