DokuWiki Git Repository

The DokuWiki sources are managed through the Git version control system. Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Git is NOT offered as optional version control backend for `DokuWiki` itself. Refer to closed (and not completed nor started) bounties.

Instead of repeating things that were said elsewhere I just want to give some pointers:

• Download Git
• Git Community
• Git User Manual

There are also some good books about Git:

• Scott Chacon - Pro Git (ISBN 978-1-43021-833-3) – You can read it online for free (CC licensed). Translations are also available (e.g. German).
• Ben Lynn - Git Magic (ISBN 978-1-45152-334-8) – You can read it online for free (GPL licensed). Translations are also available (e.g. Spanish).
• Travis Swicegood - Pragmatic Version Control Using Git (ISBN 978-1-93435-615-9)
• Jon Loeliger - Version Control with Git (ISBN 978-0-59652-012-0)

Before you start using git, you should configure it with your name and email address:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

And optionally setup colors and few helpful aliases:

git config --global color.ui auto
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.up pull --rebase

To fetch the current development version of DokuWiki use the following command (This creates the directory dokuwiki for you):

git clone git://github.com/splitbrain/dokuwiki.git

To update an existing checkout use this command from within the DokuWiki directory:

git pull

When you create a new source file, use this command to add it to the git repository:

git add somenewfile

When you changed some already tracked files, you need to tell git about it:

git add --patch

The --patch will interactively ask you what parts you want to check in (very much like darcs behaved)

When you're finished with your changes use:

git commit

This will scan your local git 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:

git format-patch origin/master

This creates one (or more) numbered patch files that can be mailed manually to the mailinglist.

• Always pull before starting to work on new patches, to make sure you don't create conflicts.
• Make sure your editor does not change line endings (from Unix LF to DOS CRLF), this would result in a complete file replace, instead of a small patch because each line was changed.
• Make a patch for a single feature. When you worked on two different features (eg, a language fix and a function update), add and commit two patches, with one for each feature. Using the –patch option for add makes that easy for you by asking what to include in the patch.
• Patches should be sent to the mailinglist and you should explain what they do and why.
• A web interface to the git repository is available at http://github.com/splitbrain/dokuwiki

explain branches

Git 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 do so you need to clone the repository but work in the stable branch:

git clone git://github.com/splitbrain/dokuwiki.git
cd dokuwiki
git checkout -b stable origin/stable

Now you can pull all needed updates whenever a new release is made:

git pull

The reasons for a distributed RCS are well explained at Why Darcs. So why did we switch from darcs to git?

While darcs is somewhat more intuitive to use, the differences between both systems aren't very big. Except that git is now much more often used than darcs. In addition, darcs doesn't work very well for larger projects. DokuWiki isn't shrinking and the quirks and slowness of darcs is quite a burden sometimes.

Also using a more popular revision control system makes it possible to outsource the hosting to services like github, which means less stuff to administer for us and less traffic on the DokuWiki server.

A more popular revision control system also makes it easier for new developers and other contributors to participate in the project. If they have to learn a new RCS just to start working on the code, that's a barrier to entry that they may not overcome. (It's amazing how little it takes to keep people from participating!) Smoothing the path a bit for new contributors can improve the quality of the code significantly.

You may also have a look at the following talks/videos to estimate why Git is a really useful tool:

• Google Tech Talk: Linus Torvalds on git (2007-05-03)
• Git - a Talk by Randal Schwartz (2007-10-12)