The Git work environment.

Working with Git is quite different to using Subversion. The actual contents of the project directory change to reflect the currently active branch: the directory contains a whole repository, not a checked out copy. Don’t get alarmed when files start disappearing only to reappear again when you switch branch.

I also noticed that I interacted with the version control less frequently when editing, delete, and create files. The interaction is saved until you’re ready to commit, making the process feel more seamless. I occasionally used to get into trouble by deleting files via the OS, rather that using the Subversion command.

For the majority of the time, I’ll use the Git commands, as I’m working in a Git repository. The git svn functionality is only needed as a Git interface with Subversion.

Getting ready to work.

I like the master branch to always reflects the current trunk until I choose to update it, so all my commits are made from other working branches.

I start by checking out a branch based on master to use as a base from which to work. I’ve imaginatively called it basework in this example, and as a branch of master it is linked to the same remote branch: trunk.

git branch -a

should display all your branches in the repository.

jkw@mac> git branch -a * basework master svn/trunk jkw@mac>

I work in increments based on stories, that’s another post, so I actually create a story branch from basework, that can be merge back into this parent upon completing the story. This helps cope with changes in the remote codebase.

Creating my working branches.

It’s a good idea to check that basework is up to date with the remote Subversion trunk before branching:

git svn rebase

This will either update the local repository with the remote changes, or tell you that the current branch is already up to date.

I’m now in a position to create my story branch:

git checkout -b inwork

The -b option is used to create a new branch and then switch to it. Without this option the same command is used to move between branches.

This same process was used to create basework.

I have my working repository structure, and I’m currently working on my story branch, see the asterisk.

jkw@mac> git branch -a basework * inwork master svn/trunk jkw@mac>

The local commit.

You can see details of the changes to the local working branch using the git status command:

jkw@mac> git status

On branch inwork

nothing to commit (working directory clean) james@cybermac1> git st

On branch inwork

Changed but not updated:

(use “git add/rm …” to update what will be committed)

(use “git checkout — …” to discard changes in working directory)

#

modified: footer.php

deleted: images/feed-icon-64.png

modified: style.css

#

Untracked files:

(use “git add …” to include in what will be committed)

#

includes/category-1.inc.php

no changes added to commit (use “git add” and/or “git commit -a”) jkw@mac>

To add the new file show in the example to those being tracked:

git add includes/category-1.inc.php

If I wanted to add all of the untracked files, I could use the -A option instead of individually naming them.

Now all the files are staged, the time comes to commit them to the local Git repository:

git commit -a -m "A message to describe the changes."

Leaving the -m option off will cause Git to request comments using whichever editor is defined in your configuration files.

I now the story is complete, and all the changes committed to the inwork branch, it’s time to commit them to Subversion.

The remote commit.

I start the remote commit process by switching to the basework branch:

git checkout basework

Next I check that the remote codebase hasn’t changed, or update the changes:

git svn rebase

I’ll merge inwork into basework:

git merge inwork

I use my text editor to manually fix conflicts that arise. Git tells you where to find them by marking up the code. This is followed by another local commit, at which point the merge is complete.

Now I can try a dry run of the remote commit:

git svn dcommit -n

It’s the -n option that makes this a dry run: nothing has been committed yet. It shows you the local versions to be bulk committed if you choose to go ahead. To actually perform the commit, remove the -n, and re-run the command, it may take a while if you’ve been busy.

Verifying the remote commit.

This is where leaving the master branch untouched pays off. basework has been committed to the remote trunk, whilst master still reflects the pre-commit trunk.

I switch to master, which should contain none of my new work, and update it from the remote trunk:

git svn rebase

It should have changed to match basework, and if so the previous commit worked.

Cleaning up.

I’ve verified the commit: I have master and basework branches that are identical, so inwork is no longer needed, I’ll delete it:

git branch -d inwork

Deleting a child branch of a different parent is a little dangerous, so if you’re not in basework you’ll get a warning. Either switch to basework and try again, or re-running the command with the -D option.

If I’ve finished work on this project, I’d delete the basework branch too, but if I’m going to continue, I’d use it to create another working branch, and I’ve gone full circle.

mkdir myproject cd myproject

The initialisation itself is pretty simple, just remember to point Git at the correct url for your Subversion repository, and watch the communication protocols.

git svn init -s --prefix=svn/ svn+ssh://svn.repository.com/svn/myproject

The -s option tells the repository to expect the typical trunk, branches and tags structure of a Subversion project. You can specify the location of your trunk, branches and tags using the -T, -b, and -t respectively.

Using the --prefix option is handy, ensuring that the remote directories will be prefixed with svn/. This makes it clear which are Subversion and which git branches later.

All that remains is to checkout all of the information relating to your project from the Subversion repository.

git svn fetch

Depending on the size of the project, this could take a while, it’s downloading the entire project history from the remote repository.

I word of warning you about the strangeness that can ensue if the remote repository contains any tags. They will be imported as git branches, and you may find the local master branch pointing to something other that the remote trunk.

These git svn commands, and all the others, are pretty well documented. Now I’ve got a Git repository, in the next post I’ll to describe my normal workflow.

Branching and merging is quick and simple, and as a result I find I do this far more often than when using Subversion alone. I also commit changes more frequently: it’s far quicker than using a remote repository, even when not off-line.

This sort of functionality is vital to successful version control, and I think it promotes better practice, as long as you’re only committing working software. All the local Git commits will later be bulk committed to the remote repository. However they all retain their identity as separate versions, so discipline is important, we wouldn’t want anyone finding broken code.

I could get all this from Git alone, but the combination retains Subversion vendor branching and the deployment advantages of my existing Subversion / Capistrano set up. I’m going to try GitHub, or my own remote Git repository, and exploiting the Capistrano support for Git, but at the moment why reinvent the wheel?

I prefer to work on the command line, and that’s the approach this series will take, but GUIs are available for Git, try typing git gui to check out the one bundled.

I use this approach for anything I need version controlled, including my Curriculum vitae/Resume, but before try this out for yourself you’re going to need to check out a local copy of that remote Subversion repository… I’ll cover that next time.

There’s a good TextMate bundle to support Git, but to be honest I’ve mostly used the command-line.

Weaknesses.

Vendor branching is possible, but awkward. I frequently use vendor drops of WordPress, SimpleTest and a number of other libraries. There may be a good way of doing this, but I haven’t found it online… yet.

I miss the svn:externals functionality, especially in applications that use a lot of plugins: WordPress in particular. Subversion allows me to define particular tagged versions of these to be pulled from their repositories during deployment without needing to bother controlling them myself.

Strengths.

Branch merging when trying out new ideas is a dream. I created a new branch, refactored huge sections of the codebase, and merged it all back together flawlessly. With Subversion this would have been a lot slower and more problematic. Git’s simply great for those investigatory spikes.

The verdict for Git.

I’ve yet to seriously try Git to interface with my remote Subversion repositories, using the ‘git svn’ series of commands. Having local copies of these, whilst still being able to use remote Subversion would be very useful. I’ve found using remote Subversion repositories easy, but trying to push a Git repository to Subversion is not so easy. I’m also going to try deploying from a Git repository using Capistrano in the near future.

It strikes me that Git is best at programmer related activities and weakest in those of interest to administrators deploying applications. I shall certainly continue to use it, but alongside Subversion.