Git, WTF?

Git is a Distributed Version Control System (DVCS). What does this mean? Basically a Version Control System (VCS) is a system that keeps track of all the changes you have made to one or several files. This is often used by software developers to keep their projects organized, to be able to revert to former revisions and to avoid editing conflicts when multiple people are editing the same file at the same time (yes, that happens often, especially in large projects). If you didn't use a VCS and someone else is editing the file, that person who uploads his changes last, will overwrite the changes of all the others because he hasn't refreshed his working copy (and wasn't aware of the other people having edited the file as well).

However, if you use a VCS, it will warn you if there is already a newer version of the file. If you haven't edited the same part of the file as the other person, the VCS might be able to auto-merge both revisions together. If not, you have to to the merging manually since no software can know how to do this.

Afraid? You don't have to. Also wikis have simple VCS functionality. Normally they keep track of all the changes ever made to a page and they warn you when someone else has just edited the same page. But unlike a real VCS, the Version Control System of most wikis is very rudimentary.

Okay, I got the point. But what is a “Distributed” Version Control System?

Conventional VCS are built on a server-client model. That means you have one big upstream repository from which everyone gets his copy and from which everyone can update his copy. This upstream repository is also the one all changes will finally be committed to.

On the other hand, a DVCS doesn't have a real upstream repo. You might call the main repo here on GitHub the upstream repo, but actually it is exactly the same as the copy you have. Therefore getting a copy isn't called checkout as it is in conventional VCS (such as CVS or SVN) but clone. When you get your copy, you clone the repository. Your clone is a complete copy of the the upstream repository. You can edit your changes but you don't commit them directly to the upstream repo. Instead you commit them to your own copy. Eventually if you like (and only then) you can push all the commits to another repository, which may be your fork on GitHub, but it doesn't have to.

Basically, what all this means is that once you have forked the project, you have a completely independent copy of the whole documentation sources. You can edit them as much as you like, you can mess up all the stuff without affecting the upstream documentation. Once you think, your changes should be merged into the official repo, send a pull request and we'll review the changes you made.

So, how exactly does this work?

In general, there a five steps to be done.

1. Fork the main repository. You can do that by clicking the Fork button here on GitHub. This will create a copy of the repo and assign it to your account.

2. Clone your copied/forked repository to your computer. See? You have cloned the official repository and created a copy. Now you clone your copy again to your local hard drive where you can edit it. That means you have two copies now. Each independent of each other and of course also of the official main repo. Note: you have to clone your fork repo only once. If you want to update your existing local working copy, all you have to do is to pull in the latest revision from either your GitHub repo, the official one or any other Git repository on the world. Of course you can also create as many clones of your local working copy as you like and pull changes from each other.

3. Edit the files. Make all the changes to the docs you want.

4. Commit the changes. Committing means that you tell your local repository that you have finished editing and want the changes to be tracked. You can commit as many times as you like, be it after changing a single word or after writing a whole new article (or several ones). Committing more often is recommended, though (as each revision is a kind of snapshot of your work in progress and can be used as a backup).

5. Push all the local revisions upstream. This publishes all your commits (see step 4) to your GitHub copy of the docs. Changes which have not been committed yet will not be pushed.

That's it. A sixth step would be to send a pull request so that we can merge the changes from your GitHub copy.

Normally, you repeat the steps 2 to 5 for editing and publishing. Step 1 has to be done only once.

I'm not convinced. This sounds so complicated

It might sound complicated, but once you get used to it, you'll see that it's pretty easy. Also note that all I told you is very theoretical. It might become clearer once you read the step-by-step HOWTOs for working with Git.

Right, but you still haven't told me why you use Git.

The reason why we don't use a normal wiki is that Git is simply much more powerful. It is a very mighty DVCS and can do many more things than a wiki. It is very easy to keep track of all the changes we and you have made and it has very smart editing conflict controls. We can also maintain the docs for all different versions in separate branches. Imagine a branch like a branch of a tree: you have one trunk (i.e. the master/main branch) and many branches, which are part of the same tree but otherwise independent of each other.

These are the technical reasons. But there are also other reasons, of course.

Advantages for us

• We don't have to fight spam. A publicly editable wiki (and be it with manually activated user accounts) is always a target for spam.

• We don't have to keep the wiki software up-to-date. This is something many users underestimate. The effort of keeping a software up-to-date is very huge and costs us a lot of time. We have to make sure bugs and security holes are fixed quickly but the wiki should be always available without downtime. It's a lot of work for us.

Advantages for you (and of course for us as well)

• You can edit the files locally in the editor of your choice. You don't have to write into an ugly textarea in your browser. That means you can take advantage of all the features your editor has (e.g. syntax highlighting, auto-indentation, auto-save etc.)

• Not doing the editing in a textarea also means that you can save your changes to your local hard disk without copying all the stuff into the clipboard and writing it into some temporary file. So when your browser crashes, not everything you've done is gone (happens often enough). A wiki might also have the problem, that the server is currently down or you hit the wrong button so you send your changes to nowhere or discard them accidentally (both means they're lost as well).

• GitHub is an excellent platform for discussion. It offers an issue tracker and pull requests so we can discuss all the changes, you can make suggestions without really editing anything, we can review changes very easily and everyone's happy. Documentation is about communication so this is the ideal platform. Most wikis only offer a dumb discussion page. Once this grows bigger, it becomes a mess (for you and for us).