git-svn-helpers

git-svn-helpers is a collection of command line tools that greatly simplifies using git for svn repositories.

git-svn-helpers's main goal is to make setting up a local git repository following an existing svn checkout a 'no-brainer'.

It also addresses using a single git-svn repository for working on multiple checkouts of (usually) different branches and switching between them.

Basic usage (Example)

Executive summary:

> cd path/to/svn/repo
> gitify

Here's a sample session:

> cd /tmp
> svn co https://svn.plone.org/svn/plone/plone.app.form/branches/1.1 plone.app.form
A 1.1/setup.py
...
Checked out revision 27228.
> cd plone.app.form
> gitify
No git repository found in /Users/tomster/.gitcache/.
Initiating cloning into cache.
Analyzing svn log...
Cloning https://svn.plone.org/svn/plone/plone.app.form/ from r10593:27155 into /Users/tomster/.gitcache/
Initialized empty Git repository in /Users/tomster/.gitcache/plone.app.form/.git/
...
Git branch 'local/1.1' is now following svn branch '1.1':
# On branch local/1.1
nothing to commit (working directory clean)
> git branch
* local/1.1
 master

Points to note:

 * gitify limited the cloning to the revisions found in the svn log of the package root (here https://svn.plone.org/svn/plone/plone.app.form/). A big time saver, especially on large repositories (such as plone.collective)
 * gitify created the git repository at ~/.gitcache not in place
 * gitify created a local branch local/1.1 that follows the (remote) svn branch 1.1 and switched to it

Multiple check-outs

In practice you will often work with different local copies of a given repository, i.e. on trunk and on a feature branch. That's when the .gitcache directory created above comes in handy. Let's move our previous checkout out of the way and create a maintenance checkout that follows trunk:

> cd ..
> mkdir feature-branch
> mv plone.app.form feature-branch/
> mkdir maintenance
> cd maintenance/
> svn co https://svn.plone.org/svn/plone/plone.app.form/trunk plone.app.form
A plone.app.form/setup.py
...
 U plone.app.form
Checked out revision 27228.

What happens if we run gitify here?:

> cd plone.app.form/
> gitify
Git branch 'local/trunk' is now following svn branch 'trunk':
# On branch local/trunk
nothing to commit (working directory clean)

Notice, that this operation went much faster, as we now have used the existing git repository in the cache directory. This can be further evidenced by looking at the available local branches now:

> git branch
 local/1.1
* local/trunk
 master

Caveats

'Recycling' .git in this manner works (perhaps surprisingly) well in practice, but you need to keep the following in mind:

All checkouts share the same index!

Let's take a look at what this means by switching back to our feature branch:

> cd ../../feature-branch/plone.app.form/
> git status
# On branch local/trunk
# Changed but not updated:
# (use "git add/rm ..." to update what will be committed)
# (use "git checkout -- ..." to discard changes in working directory)
#
# modified: docs/HISTORY.txt
...
# deleted: plone/app/form/kss/tests/test_kss.py
...
#
# Untracked files:
# (use "git add ..." to include in what will be committed)
#
# plone/app/form/tests/test_kss.py

Wohah! What happened is that .git now points to trunk and thus the status command shows the difference between that and our branch as local modifications, since that is what the filesystem represents. We can verify this by using subversions status command:

> svn st
< BLANKLINE >

Phew! All in order! But what to do with git? We've finished working on trunk and want to get back to our feature branch, but the git index is all wrong?! Simple: just re-run gitify:

> gitify
Git branch 'local/1.1' is now following svn branch '1.1':
# On branch local/1.1
nothing to commit (working directory clean)

Basically, that's all you need to remember when working with multiple check-outs of the same package: Always run gitify when switching between check-outs!

What is new in this release:

• The cannonical repository is now in https://github.com/collective. [rossp]
• Fix the handling when switching to a svn branch that git already has a local branch for. [rossp]

What is new in version 0.8:

• Make the init command follow along if the svn repository has been switched to another branch. Thanks to Calvin Hendryx-Parker for reporting the issue. [tomster]

What is new in version 0.7:

• Use full copies instead of symlinks to create working copies. This avoids the issue of having the git and svn repository out of sync when working with multiple copies of the same repository and greatly reduces the risk of conflicts.
• This also means, that the fetch command now only operates on the cache without modifying the working copy (making it safe to run via crontab, for example)
• Running gitify against an old-style working copy will produce an error. Simply deleting the symlink and re-running gitify remedies that, however.
• Another effect, is that the init command is now only needed once for each working copy (it is no longer necessary to re-run the command after switching between different working copies of the same repository).
• gitify therefore no longer defaults to the init command (just as neither git nor svn do anything w/o supplying an explicit action). Also, it has been renamed from gitify (back) to init. [tomster]
• Allow the help, --version and fetch commands to run outside .svn directories [tomster]

What is new in version 0.5:

• Added gitify update command, which performs a git-svn rebase operation for the current svn checkout but also handles uncommitted local changes gracelully (unlike git svn but like svn does)
• No longer use the logging module for user feedback. That idea was rather misguided

What is new in version 0.4:

• Refactored the entry points to just use gitify. All other commands are now sub-commands of gitify:
• gs-commit has been replaced with gitify push
• gs-fetch has been replaced with gitify fetch
• Added usage and help output for each command.
• Removed the gs-clone entry point as it was only ever used together with the main gitify command anyway.
• Use proper logging instead of just printing to stdout
• Added comprehensive tests, including functional tests that cover the entire update/commit cycle of cloning an svn repository and commiting back to it.

What is new in version 0.3.1:

• BUGFIX: Don't use custom aliases, as they might not be installed. This resolves http://github.com/tomster/git-svn-helpers/issues#issue/2
• BUGFIX: Explicitly list elementtree as dependency This resolves http://github.com/tomster/git-svn-helpers/issues#issue/1)

What is new in version 0.3 Beta:

• Added the gs-commit command which helps committing back to svn and keeping git and svn in sync

What is new in version 0.2 Beta:

• Added the gs-fetch command which helps keeping the cache up-to-date

Requirements:

• Python