Development/Tutorials/Git/git-svn

More and more KDE developers are using git-svn to contribute to KDE's SVN repository. Git-svn allows you to create a local git repository based on an existing svn repository. This allows you to use some (but not all) of git's useful features. It's very useful if you want to commit code on an airplane. ;)

Important notes:

Please make sure to use Git 1.5.4 or better when you are interfacing with SVN. Older versions of git-svn have many issues you might run into otherwise.
git-svn is not able to track most of the svn:properties yet. So, svn:externals are not fetched.

This page explains how to fetch kdeedu trunk from and import it into Git. It will then demonstrate how to make use of Git's features and sync with SVN again.

If terms like "rebase" and "branch" do not mean anything to you, you should read a tutorial on general Git usage and workflows first, e.g. the Git Basics page on this wiki.

Checking out

The "svn checkout" command becomes:

# Anonymous access (if you do not have a KDE SVN account)
git svn init svn://anonsvn.kde.org/home/kde/trunk/KDE/kdeedu
# For those using HTTPS authentication:
git svn init https://svn.kde.org/home/kde/trunk/KDE/kdeedu
# For those using SSH authentication:
git svn init svn+ssh://[email protected]/home/kde/trunk/KDE/kdeedu
# Further steps which are common to all methods
git svn fetch -r 1000000
git svn fetch

Note that, unlike "svn checkout", "git svn init" does not create the directory that contains the checkout. Instead, it behaves similar to "git init": It expects you to create this base directory yourself and call "git svn init" inside this directory.

The number given to "git svn fetch" on the second-to-last line is the first revision that will be fetched. At this point, the differences between SVN and Git become apparent. While "svn checkout" only reads the current state of the repository, Git wants to read the whole history. But KDE's repository is big. Very big. In fact, it's exorbitantly huge.

To reduce unnecessary load on KDE's server infrastructure, we instruct git-svn to fetch only those revisions that are older than revision no. 1000000, which is a sensible default at the time of this writing (December 2009, current revision ~1060000). The current SVN revision can be found at http://websvn.kde.org (take a look at the line "Directory revision" just below the header). You can also choose exactly the current SVN revision if you're absolutely sure that you will not be needing any history ("git log", "git blame" and Co. might then not behave as expected). If you're using an older version of git-svn, you may need to specify a revision number that was a commit to the code you're checking out.

Updating

The equivalent to "svn update" becomes:

git svn rebase

You'll usually do this on the master branch. If you're using multiple branches, you might want to rebase them on the master after the update.

Commiting

After sending your commits to the svn server, git-svn will download all new commits (essentially running 'git svn rebase'). This rebase won't work if you have local, uncommitted changes. If that becomes inconvenient, you should use git stash.

Usually, you will be working in feature branches. When you want to commit them to SVN, you will rebase them onto master or merge them into master, and then do the following from the master branch:

git svn dcommit

Git will create one SVN commit for each commit in your Git repository. To create just one commit for the whole merge of a branch into the master branch use the "--squash" feature like this:

git merge --squash mybranch

[TODO: apparently --no-ff is better than squash but it has.. quirks]

See Development/Tutorials/Git/BestPractices for guidelines on when to squash.

Now that you've got a git-svn repository set up, you can read about Git Basics if you haven't already.