Potlatch 2/Developer Documentation/git

In Feb 2011 RichardF announced that we'd be moving to git, and that Gravitystorm would write some introductory documentation. So here it is.

Background

Git is a distributed source control system, so unlike svn there's no need for a central server. It also means you can work offline and save multiple commits (even to multiple branches) and then share your code when you get the chance.

Since we're moving from svn it's usual to provide a list of git equivalents of svn commands to ease everyone into things. I'm not going to do that since doing so is considered harmful. I started learning git by finding the equivalents of svn commands and it makes everything massively confusing and unhelpful.

Getting Started

(Install git. There's a million guides on how to do it, I'm not writing any here.)

First you need to get a copy of the potlatch2 repository from somewhere. It doesn't really matter where it comes from, but it's worth getting one that's reasonably up-to-date and full of sensible patches. So let's take the OSMF-hosted copy and "clone" it.

 git clone https://github.com/openstreetmap/potlatch2.git

That's done a number of things, namely

• Created a .git folder. This contains everything needed for git to work.
• Copied all the potlatch2 code into that .git folder, including all the revisions and branches
• Added a 'remote' called 'origin'. A 'remote' is another copy of the repository somewhere else, it's just convention to call the first one 'origin', but it could be called anything you like. It's normal to have a few different remotes, corresponding to different servers and people - there's an OSMF one, Gravitystorm has a copy on github and so on.
• Created a local copy of the 'master' branch from the 'origin' server (and called it 'master')
• Checked out the local 'master' branch. More on this below.

At any point in the future, you can remind yourself where you cloned from with:

 git remote show origin

Branches

We're in an unusual position since we're starting with a number of branches. RichardF asked for r25368 (aka 7d4f68 now) to be the basis for the stable copy of p2, and so work committed after that in svn was separated out into different topics. You can see which commits went into which branches at https://gist.github.com/860288

 git status

This is most important command. Let's you know which branch you are on (master), and that nothing has been edited since. It's worth using it lots! Here's another useful one:

 git log

Shows all the different commits up until now for you to scroll through. Have a look at which ones they are - it's not the same list as in svn

 git checkout i18n
 git status
 git log

Switches to the i18n branch. Think of the .git folder as a bag full of rabbits, and you've just pulled out the one called i18n. By default, git notices there's a branch on origin already called i18n, so sets up your local i18n branch pre-populated with origin/i18n. That's not terribly important right now, but it's worth knowing.

The log now shows different patches, but if you scroll down far enough (currently 14 commits) you'll see that it shows all the other commits from 7d4f68 on backwards.

 git checkout master
 git status
 git log

Gets you back to where you started.

 git branch
 git branch -a

The first shows you all your local branches, the second adds in the ones from origin that we haven't touched yet. Feel free to have a look at the rest of the branches by calling "git checkout whatever" and having a look through their logs.

It's very likely that most of these branches will be polished up and folded back into the 'master' branch over the next week or two.

Making changes

Pick the branch you want to work on, or make a new branch if you feel like it. It's quite normal to create a branch for a new topic rather than doing everything in master. But lets start with what code is already in master and go from there.

 git checkout master
 git checkout -b bananas

That creates a new branch called bananas. Now edit two files. It doesn't matter which. When you've made your changes, we do two things - a) build up a commit by choosing which files and/or parts of files we want, then b) commit it with a message.

git status

# On branch bananas
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   README.txt
#	modified:   TODO.txt
#
no changes added to commit (use "git add" and/or "git commit -a")

To see the differences between your working copy and what git knows about, do

 git diff

I want to build my commit with the changes to the README file but not to the TODO file. So I only add that file to the staging

 git add README.txt
 git status
# On branch bananas
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	modified:   README.txt
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   TODO.txt
#

The "changes to be committed" are what we're about to commit, the "changed but not updated" are what we're leaving on the table, for now. At this point we need to learn the intricacies of git diff, namely

 git diff

This will show you what you've got "changed but not updated" (i.e. what hasn't been staged for committing - in this case that's TODO.txt)

 git diff --cached

This will show you what you've got in "changes to be committed" (i.e. README.txt)

Get used to these two, you'll need them a lot.

When you're happy with what you got on your "changes to be committed" list

 git commit

and write a suitable message.

Just as a little warning, git add is not the same as svn add. They do subtly different things and if you start off thinking "oh, git add is like svn add" you'll confuse yourself pretty quickly. git add is for building up a commit, and nobody cares about svn add since we don't use svn any more. So there. Also, git add -i lets you pick and choose which parts of files you want to add, if you've realised that you want to commit things in stages. It's pretty cool.

Publishing your changes

There's many different ways to share your changes with the rest of the world.

The most common way is to publish to a public repository, for example:

git push origin master

Currently there are a few public repositories of note:

• github.com/gravitystorm/potlatch2 - Gravitystorm's copy of the repository
• github.com/systemed/potlatch2 - Richard's copy
• git.openstreetmap.org/potlatch2.git - the OSMF sysadmins' copy of the repository. It's policy to keep a copy of code the sysadmins are deploying separate from changes that are currently in progress and not ready to be deployed.

Footnotes

There's a million things more to ask about git and how we're going to be using it for potlatch2 development, and Gravitystorm is happy to answer any of your questions. I expect in a couple of months time I'll remove this wiki page since by then it'll be utterly irrelevant.