Track your changes to an open-source project with git

From Bitpost wiki
Revision as of 17:07, 29 January 2008 by M (talk | contribs)

Here are quick and easy steps to track your changes to an open-source project.

Once you get a handle on git, you'll find it very powerful. But getting started can be the biggest challenge. Distributed source control requires a different way of thinking than using a central repository. git's terminology is a little bent from what you're used to. Use this guide to get past the first hurdles.

Requirements

Before you can start making changes to a project, you should get the code and make sure you can compile and run it. In this guide, we assume that the project is currently under subversion(svn) control. Check out a copy and get it up and running.

The next set of requirements is pretty simple:

  • I need my own branch off of the svn branch.
  • I need the ability to overlay the latest svn changes, over time, on top of changes in my branch.

Notice how simple this is - we're not even asking to commit anything yet. These are fundamental requirements that any developer on a non-trivial open-source project would have. You need to do this if you are going to bang on an open-source project.

Now let's add one more requirement. I'm going to have this code on at least three different machines, so I need to be able to have a common repository for my changes.

  • ability to work from several locations, pushing/pulling my changes to a central repo

Another basic source control requirement, and we're done.

But try to meet this set of requirements with cvs or svn. No longer simple. Enter git. It was born to do this job. If you're with me so far, and it sounds like we're on the right track, I promise you: step through the rest of this guide and you'll be happy you did. Let's get to it.

Setting up your own branch off svn

NOTE: I'm going to use mythtv in this example, because that's what I wanted to work on.

Create a local git repository of the project's subversion repository, using git-svn. There are two ways to do this. If you do not specify a svn revision number, git will grab the entire history of the project as it is available in the svn repo. WARNING: this may be HUGE for older bigger projects! 

cd my_git_repos
git svn clone http://svn.mythtv.org/svn/trunk/mythtv mythtv

If you specify a revision number, git will grab just that version, and then we can grab all changes after that version, too. It's probably worth digging into the project history to find a reasonable revision number. 

git svn clone -r15502 http://svn.mythtv.org/svn/trunk/mythtv mythtv

We now have a repo of the project under git control. Simple, eh? git uses branches, and named our svn grab the "master" branch in this repo. See the list of branches: 

git branch

Don't change anything in the master branch, it will be a "clean" copy of what's in svn. Now we can easily update our master branch with the latest svn commits at any time. Do this now to make sure you're completely up-to-date: 

git svn rebase

Now we create a branch of our own, derived from the svn base. git loves branches! 

git checkout -b mybranch
git branch

Now that you have your branch checked out, you can bang away and change anything you want to (except the top-level .git directory).

Eventually you'll want to commit your changes. Time for some terminology (I swear I'll be brief - on a "need to know" basis). As you edit, you're only changing local files. git refers to the locally modified files as your "working set". git doesn't track anything about your working set - you're free to abuse it as you see fit. If you want to keep changes you've made, you need to add each file you've changed or added to the git "index" (also called the "cache"). Then, when you're ready, you commit all the indexed changes to the repository in one single commit. So git provides the "index" as a space in which you can manage your next commit.

Let's say you've changed the configure script. Here's how to commit the change to your git branch: 

git add configure
git commit -m "I updated the configure script."

The index is an extra layer that you don't usually have with cvs/svn. It's totally a benefit, and you can ignore it by doing the add and commit in one step. This will add every file that is in the repo and has been modified to the index, then commit, in one step ("cvs/svn style"): 

git commit -a -m "I changed this to that."

So over time, you'll have a series of commits to your branch. Later, you'll want to get the latest svn changes and incorporate them. We're going to use rebase again. Previously, we used it to update from svn, let's do that again. Make sure you switch to the svn branch first. 

git checkout master
git svn rebase

Now it gets interesting. We're going to switch back to our branch, and once again use rebase. To be more specific, rebase means to take your current set of commits all the way back to the last rebase, REMOVE them from the branch, "rebase" the branch as specified, and reapply all our commits. This is good stuff! 

git checkout mybranch
git rebase master

git has now reapplied your changes on top of the latest svn. I told you it was cool!

We've now handled our first set of requirements. Next, we'll tackle setting up a public git repo. If you don't need that, you might want to skip to Managing your next commit with git, or Submitting your commits with git.

Making a public repo

git wants you to share. You can share your repo using ssh, http or the git protocol (most efficient but requires port 9418 to be available). We'll keep it simple and secure here and use ssh. Assuming you can access your public server with ssh, you can use it for your git public repo.

Next, we take our current repo, with the "master" svn-based branch and the "mybranch" derivative, and clone it into a special repo marked as public. The --bare option tells git that this repo will just track changes from others, but not have its own working set. 

ssh server
cd git_public

If the first repo was created on a client, not the publicly-accessible server: 

git clone --bare ssh://client1/path/to/git/mythtv mythtv

If the first repo was on the server already, you can just use a local path instead of the ssh url: 

git clone --bare /path/to/repo1/mythtv mythtv

Now you have a public shared repository!

Sharing changes on a public repo

How (not) to retrofit a repo connection to svn Let's set up a repo on a second client that uses the public repo. There are two ways to go: set up just like we did the first client, by starting with a grab of the svn repo and branching it, then connecting it to the public repo; or set it up using the public repo, then connect it to svn. Let's be nice and try to set things up without having to hit the svn repository again. 

ssh client2
cd my_git_repos
git clone ssh://server/git_public/mythtv mythtv

Now you've created a clone of what was checked into the public repo from client1. The master branch is automatically created and associated with the master branch in the public repo. We need to create and associate mybranch with the one in the public repo. First, create it: 

git checkout -b mybranch

Next, we associate it to the public mybranch by editing the .git/config file (don't worry, you're supposed to! and it's easy...). Here's what associates the master branch to the public repo (it's already in the config file): 

[branch "master"]
       remote = origin
       merge = refs/heads/master

Add a similar entry for mybranch: 

[branch "mybranch"]
       remote = origin
       merge = refs/heads/mybranch

Now when you pull from or push to the public repo, both branches will automatically get synched. Try it now if you like (although you're already up-to-date): 

git pull

Note that the connection to svn has not been carried over from repo1. That is, your repo2 is only associated with your public repo so far. That's fine if you're just going to pull svn changes from repo1 and push to your public repo, then pull to repo2. But that's no fun! We can set up all of your repos to be able to sync with the public repo and svn. Let's edit the .git/config file again, re-adding the svn connection: 

[svn-remote "svn"]
       url = http://svn.mythtv.org/svn/trunk/mythtv
       fetch = :refs/remotes/git-svn

Now try a refresh from svn! 

git checkout master
git svn rebase

Whoops, it doesn't work! Bummer.  :<


tbc...

Retrieved from "https://bitpost.com/w/index.php?title=Track_your_changes_to_an_open-source_project_with_git&oldid=1859"