Mirroring sipXecs subversion repository with git
From SIPfoundry sipx, The Open Source SIP PBX for Linux - Calivia
Contents |
Advantages of creating your git sipXecs mirror
You can keep entire history of ecs project accessible off-line. Your git repo will contain the entire history of sipx project. You will be able to grep any given revision of any file. You'll be able to generate the diffs against any revision, grep the content of any revision or run blame command off-line. All this operations will be a magnitude faster than their subversion counterparts.
You will save disk space: git repository is smaller than subversion working copy and you need only a single repository to keep all your branches.
You can develop a new feature in a separate branch without write access to subversion repository. Git allows to create those branches in a very efficient manner; you can switch between the branches, commit partial work, update the previous commit.
You will be able to easily generate patches to be reviewed and included in sipx official repository. With git it's easy to split your contribution into series of patches: showing history of your changes might make it easier on the reviewer and consequently your patch might be accepted faster. You can maintain and rebase a patch or series of patches against sipXecs mainline.
Installing git
Since git is used by Linux kernel developers it's easyly available on most modern distros. If you use Fedora run this (as root):
yum install git\*
How to create a "read-only" SVN mirror in git
You can skip this part if you have access to sipx git repository published by someone else. At the moment sipx project does not publish git repository mirroring subversion manline. However everybody can create a git mirror of the official sipx mainline.
The initial clone operation can take several minutes as it imports the entire history of sipXecs repository:
git svn clone http://sipxecs.sipfoundry.org/rep/sipXecs/main ecs
Now you can change to ecs directory and check the status:
cd ecs git status
Git should tell you that you are on 'master' branch
Developing in git repository
Making and committing changes
Let's develop a new 'super' features. You should never write new code in master branch. In your mirror repo, 'master' is used only to track subversion mainline. To write new code create a new branch and check it out.
git checkout -b super-feature
Option -b means that you are creating a new branch and checking it out. If you later want to switch to this branch, run the same command without a -b option. 'git checkout' is similar to 'svn switch' (*not* to 'svn checkout').
You can make some changes now
... using your favorite editor
Once you happy with yout changes commit them. You'll be only checking in to your local git repository.
git commit -a
Option -a means that you want to add all changed files to the commit, alternatively you can run git add and add the files one by one or directory by directory. Differently than in subversion, when using git you have to tell it explicitly which files you are committing.
Git is more liberal and forgiving than subversion. You can amend your commit later if you forgot about something. You can even rewrite the history several commits back, as long as you did not share your changes with anyone.
Generating patches
If you do not have write access to subversion sipXecs repository you need to generate patch and ask sipx committers to check it in for you.
Before you generate a patch against master it's a good idea to rebase master against subversion mainline and then rebase your branch againts master.
git checkout master # switch to master branch git svn rebase # retrieve the latest commits from subversion repo git checkout super-feature # switch to your feature branch git rebase master # rebase your branch against the master
Git is quite efficient at mergin your changes during rebase. Check here about how to resolve conflicts if you have any. Now you're ready to generate the patches.
git format-patches master
Or you can redirect your patches to another directory:
git format-patches master -o ~/patches
Git will generate one patch file for every commit on the branch. Since git let's you to modify the history of the commits you can generate a series of patches that can show the logical developement of your feature. Alternatively you can choose to generate a single patch like this:
git diff master > super-feature.patch
You can attach patches to JIRA issues or send them on the list for discussion.
Accepting patches sent by other developers
Quite often people will comment on your patches. Sometime developers will generate patches on top of your patch. You can commit them to your git repository.
If someone sends you a patch generated with git
git checkout super-feature # make sure you are in the proper branch git am 0005-some-fixes.patch
That will commit the patch to super-feature branch - it will preserve the name of the patch author and their comments. You can make your changes on top of the patch and commit them separately. Or you can amend the previous commit with your changes.
... hack ... hack ...hack git commit -a --amend # -a means add all changes, --amend means fix previous commit
You can also easily accept/review pathes generated with svn diff, gendiff etc.
git apply -p0 0005-some-fixes.patch
That will apply the patch but not commit it (if patch was not generated by git it does not have enough information to create commit). It's slightly more convenient than using patch command since it'll behave in an atomic way (the apply will succeed or fail - it won't leave your workspace partially patched)
How to commit your changes back to SVN repository
If you have subversion commit writes you can use git to send your changes back to subversion repository. All additions, renames and deletes will be recorder properly. Subversion commits will not be different from commits made directly with svn client.
Let's say the you have changes in 'super-feature' branch that you want to commit back to subversion repository.
git checkout master # switch to master branch git svn rebase # retrieve the latest commits from subversion repo git rebase master super-feature # makes sure that your branch is rebased against latest version of svn tree git rebase super-feature master # fast-forwards master to include super-feature changes git svn dcommit -n # Check to see what git is about to commit. You can use giggle to look at the changes. git svn dcommit # Actually sends your changes to subversion repo
More tips
- If you know subversion pretty well check this out: http://git.or.cz/course/svn.html
- There are a few tech talks with helpful information about git:
There is several git GUIs - if you use Gnome giggle is a good choice
yum install giggle giggle &
Older patches might not apply cleanly against the latest sources. In such cases it's better to create a branch rooted in the revision against the patch was created, apply and commit the patch and then rebase it to master's HEAD. To find a git commit from SVN revision number:
git svn find-rev r10645 # make sure that 'r' is here
If you encounter problems when rebasing or merging 'git mergetool' command can be used to launch graphical 3-way merging tool. Make sure that you run it from the root of your git repository.
git rebase master # ... reports merge conflicts git mergetool # launches your favorite merge tool (meld in my case) # after you merge all conflicting changes git rebase --continue
'checkout' and 'status' are probably 2 most commonly used commands. To add svn-like aliases for them:
git config --global alias.co checkout git config --global alias.st status
And now you can use 'st' and 'co' instead:
git st # instead of git status git co master # instead of git checkout master
Enable colorized output for various commands:
git config --global color.branch auto git config --global color.diff auto git config --global color.interactive auto git config --global color.status auto
Mirroring all branches of subversion repository
To create a mirror of entire sipXecs repository (not just a mainline but also all the branches)
git svn clone http://sipxecs.sipfoundry.org/rep/sipXecs -T main -b branches ecs
It does require git to get all the revision from subversion. It might take several hours so do it overnight. Use https instead of http if you have commit access. To see the list of all remote branches (branches mirroring subversion repository)
git branch -r
If you want to develop a feature that should be checked in to specific subversion branch create a topic branch based on a specific remote branch (instead of creating branch based on master). For example to develop in 3.8 branch
git checkout -b my-feature 3.8
To rebase current branch against subversion branch.
git svn rebase
To fetch all remote branches.
git svn fetch --all
