Revision as of 10:48, 10 February 2010

This page is work-in-progress. It may change quite a little over the next few weeks. I'm just documenting my personal progress here. Everybody is free to add/change, though.

Understand where you are

To see all branches that are currently in your repository:

git branch -a

To see which branch you are in and what files have been staged to be committed and/or modified

git status

To get a graphical overview of your branches

gitk --all

In gitk you can add additional customized gitk views that show you a selection of commit nodes.

Mac OS X users may try using "GitX". There are a variety of other software solutions on other operating systems that will help you visualize your Git branches.

Working on BugZilla Bugs

Start working on a BugZilla bug

Go to your development branch and update it:

git checkout dev
git pull
cd lib/pkp
git checkout dev
git pull
cd ../..

Start making your changes

...hack, hack, hack...

Work on a second BugZilla bug in parallel

The following approach is not based on topic branches. The reason is that I assume that, although belonging to different BugZilla entries, the changes are interrelated and depend on each other.

Commit what you've done on the other bug so far

cd lib/pkp
git add -A
git commit -m '#4918# citation grid editor - wip'
cd ../..
git add -A
git commit -m '#4918# citation grid editor - wip'

Start working on the other bug

...hack, hack, hack...

If you have completely unrelated changes then you should

cd lib/pkp
git fetch official
git checkout -b topic-branch official/master
cd ../..
git fetch official
git checkout -b topic-branch official/master
... hack, hack, hack...

Once you're done commit to the topic branch (see above).

Switch back to the previous BugZilla bug

Commit again

cd lib/pkp
git add -A
git commit -m '#5106# filter refactoring - wip'
cd ../..
git add -A
git commit -m '#5106# filter refactoring - wip'

Continue working on the previous bug, then commit

...hack, hack, hack...

Finally you can use 'git rebase --interactive' to re-order the mixed up commits, join commits belonging to one bug into a single commit, change the commit messages, etc.

Distributing non-commited changes onto distinct commits

If you have worked on several bugs at the same time without committing changes to distinct bugs or you want to distribute a big change into several commits, then interactive add comes in handy:

git add -i

This allows you to mark changes hunk by hunk or file by file for commit. You select the changes you wish to group together, add them to the staging area (index) and commit them. You repeat this until you have committed all changes.

Please have a look at the section about interactive add in 'man git-add' for detailed explanations of the interface.

Update your working copy with changes from master

If you think that the remote changes do not interfere with what you did:

cd lib/pkp
git pull
cd ../..
git pull

If that doesn't work because you get merge conflicts then it's often better to abort (do this only if you have no uncommitted changes in your working tree) and rebase as this applies your changes on top of the master which is easier to merge:

cd lib/pkp
git reset --hard                 # use git reset --merge ORIG_HEAD if you had a dirty working directory
git rebase official/master
... handle merge conflicts ...
cd ../..
git reset --hard
git rebase official/master
... handle merge conflicts ...

Warning: Never rebase a branch that contains commits that have already been pushed to a public repository. You'll break things for other developers who rely on your code!

Make quick fixes to the master copy without interrupting your workflow

git stash
git checkout master
... make a change ...
git add -A
git commit -m '...'
git checkout dev
git pull
git stash pop

Amending the last commit with additional changes

If you want to change the commit message

git commit --amend

If you want to maintain the commit message

git commit -C HEAD --amend

Closing a BugZilla bug

Preparing commits to push to master

After you have committed everything in your development branch you can issue (while still in the development branch):

git rebase -i official/master

to organize and reorder your changes.

You order the changes in a way that what you want to commit starts directly off the official/master branch. Once you have prepared everything in your dev branch you execute:

git checkout master
git pull
git merge dev

You may also merge up to a certain commit if you don't want to publish everything that's in your dev branch, e.g.

git merge dev^^

You can also cherry-pick single commits and apply them to the master branch. You should only do this if you'll throw away your development branch afterwards as cherry-picked commits will not usually be recognized as being the "same" in both branches. See 'man git-cherry-pick' for more details.

Now check everything thoroughly. You are close to the point of no return which is:

Attach a patch to the BugZilla bug

Use 'git diff' or 'git format-patch' within the prepared master branch to create patches then submit the patches to BugZilla.

Create a patch based on the start of a single commit comment:

git diff-tree -u --pretty :/#4867 >patch-lib-pkp.diff

Create a patch based on the last commit:

git diff-tree -u --pretty HEAD >patch-lib-pkp.diff

Create a patch based on what's staged:

git diff -u --pretty --cached >patch-lib-pkp.diff

etc.

Commit changes to the master branch

Once you are sure that what's in your master branch is really what you want to commit issue:

git push

Push directly from the dev branch

When you've worked a while with git you'll probably find it annoying that you have to move to the master branch all the time, even if you're committing only very small changes.

If you think that you've fully understood the git versioning logic you can also directly push changes from your dev branch to the official repository's master branch. To do so you first have to rebase your changes onto the the official repository's master branch. While in your dev branch issue the following commands:

git fetch official
git rebase -i official/master # You can leave out the -i if you don't need to edit the commits
git push official dev:master

You can replace dev with a specific commit point if you wish to commit only up to a given point, e.g.

git push official dev^^:master

Use aliases to become more efficient

Once you've found your routine you'll realize that you'll type the same commands over and over again. Git has a mechanism that helps you to avoid unnecessary typing. Please have a look at

man git-config

and search for the 'alias' section there. You can configure aliases in ~/.gitconfig like this:

[alias]
        st = status
        ci = commit -m
        co = checkout
        ai = add -i