|
|
| (19 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| Here are quick and easy steps to use git to track your changes to an open-source project that uses svn.
| | == Purpose == |
|
| |
|
| 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. This guide will help you get past the first few hurdles.
| | Here are some of the projects on which I have overlaid my code, with the help of git: |
|
| |
|
| == Requirements ==
| | *[http://www.mythtv.org/ mythtv] |
| | *[http://ampache.org/ ampache] |
| | *[http://mu.wordpress.org/ wordpressmu] (now integrated into [http://codex.wordpress.org/Create_A_Network wordpress]) |
| | *[http://recessframework.org/ recess] |
| | *a proprietary project hosted privately behind an openvpn connection |
|
| |
|
| | All of these currently use subversion, which git can read from and write to. Some of them (read: "mythtv") are insanely active. Git can help you remain sane while you try to overlay your changes on top of a moving target. |
|
| |
|
| Getting git on gentoo:
| | == Overview == |
| emacs /etc/portage/package.keywords
| |
| dev-util/git
| |
| dev-util/tig
| |
| dev-util/qgit
| |
| emacs /etc/portage/package.use
| |
| dev-util/git tk
| |
| emerge -Davu git tig qgit
| |
|
| |
|
| 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.
| | Historically, source control always kept your code in a central location, and each developer checked out file(s) when they wanted to do modifications. Sometimes you could not get access to a file because someone else had checked it out with exclusive access. |
|
| |
|
| The next set of requirements is pretty simple:
| | Open-source culture has no tolerance for this. Typical source control for open-source projects does not rely on checking out files. Anyone can grab the files and modify them at any time. Then conflicts are dealt with when you want to commit your files back into the central repository. The headaches are left for when you merge changes back into the project that has completely changed from under you. |
| * I need my own branch off of the svn branch.
| |
| * I need the ability to merge the latest svn changes, over time, with the 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 <strong>need</strong> 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.
| | git was made to ease life within this environment. But you have to step back and adjust your way of thinking. Code flows in every direction, and every developer is her own central repository. |
| *ability to work from several locations, pushing/pulling my changes to a central repo
| |
| Another basic source control requirement, and we're done.
| |
|
| |
|
| But <strong>try</strong> to meet this set of requirements with cvs or svn. No longer simple. Enter git. It can manage repos and branches like nothing else. If you're with me so far, and it sounds like we're on the right track, this guide is for you. Let's get to it.
| | == Implementation == |
|
| |
|
| == Setting up your own branch off svn ==
| | I have used three approaches, in reverse chronological order: |
|
| |
|
| NOTE: I'm going to use mythtv in this example, because that's what I wanted to work on.
| | #[[Managed publishing of your personal git repository]] - this is how I currently work, publishing my code in a clean controlled way to a gitorious repo. |
| | | #[[Work on an open-source project from anywhere]] - this was a popular approach for a while, using an SVN-based master repo. |
| 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!
| | #[[Setting up your own public repo on top of an open-source project]] - this is a technique useful with an SVN-based master repo but probably overly complex. |
| ssh client1
| |
| cd my_git_repos/mythtv_svn
| |
| git svn clone http://svn.mythtv.org/svn/trunk trunk
| |
| 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 trunk
| |
| 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
| |
| Note that you don't want to change anything in the master branch. It will remain 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 branch 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. You won't get any svn conflicts, because the latest svn changes were applied directly to the original svn base. You get to concentrate on what's important: overlaying your modifications on top of the latest svn changes. 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.
| |
| | |
| == 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/mythtv_svn
| |
| If the first repo was created on a client, not the publicly-accessible server:
| |
| git clone --bare ssh://client1/path/to/git/trunk trunk
| |
| 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/trunk trunk
| |
| Now you have a public shared repository. You can now change mybranch and push to and pull from your public repo to your heart's content.
| |
| | |
| == Sharing changes on a public repo ==
| |
| | |
| We're now sharing two branches on the public repo. Do we need to share the svn branch? We could, but things will get complicated fast. It is a big step to get the latest svn code and rebase your changes to it. We really don't want to have to go through that on every repo we have. The more efficient way is to perform the rebase on one repo, and force-push it through to every other repo. Note: if you're not convinced, check out [[How (not) to retrofit a repo connection to svn|some of the difficulties I had]] trying to sync the svn branch.
| |
| | |
| So we can kill the master branch in the public repo (yes, sounds scary, but master is just another branch). You'll need to pull off a little trick to do this. You can't just switch from the master branch in the bare public repo, because it doesn't have a working set. Instead, just directly edit .git's HEAD.
| |
| ssh server
| |
| cd git_public/mythtv_svn/trunk
| |
| Now edit HEAD, changing from:
| |
| ref: refs/heads/master
| |
| to:
| |
| ref: refs/heads/mybranch
| |
| You've just manually changed the active branch on a 'bare' repository. Now you can delete master.
| |
| git branch # to verify that mybranch is active
| |
| git branch -d master
| |
| | |
| Let's set up a repo on a second client that uses the public repo. We start out by setting up client2 just like we did with client1:
| |
| ssh client2
| |
| cd my_git_repos/mythtv_svn
| |
| git svn clone -r15502 http://svn.mythtv.org/svn/trunk trunk
| |
| git svn rebase
| |
| git checkout -b mybranch
| |
| Now we connect it to the public repo. We retrofit the dependency on the public repo by editing the .git/config file (don't worry, you're supposed to! and it's easy...). It should look something like this:
| |
| [core]
| |
| repositoryformatversion = 0
| |
| filemode = true
| |
| bare = false
| |
| logallrefupdates = true
| |
| [svn-remote "svn"]
| |
| url = http://svn.mythtv.org/svn/trunk
| |
| fetch = :refs/remotes/git-svn
| |
| Add this to the bottom:
| |
| [remote "origin"]
| |
| url = ssh://server/git_public/mythtv_svn/trunk
| |
| fetch = +refs/heads/*:refs/remotes/origin/*
| |
| [branch "mybranch"]
| |
| remote = origin
| |
| merge = refs/heads/mybranch
| |
| We're all set now. Pull the latest changes from the public repo if you like:
| |
| git pull
| |
| | |
| == Rebasing from SVN across your repos ==
| |
| | |
| When you're ready to grab the latest SVN changes and rebase your code on top, make sure your working repos are all committed and updated. Then sync each of them to the same SVN revision:
| |
| ssh client1
| |
| git checkout master
| |
| git svn rebase
| |
| ssh client2
| |
| git checkout master
| |
| git svn rebase
| |
| Now you're ready to rebase. Note that you will have to work through any conflicts during the last step.
| |
| ssh client1
| |
| git checkout mybranch
| |
| git rebase --interactive master
| |
| Once you're happy with the rebase, force-push the result to the public repository. We have to do this because our branch has a new SVN head!
| |
| git commit -a
| |
| git push -f
| |
| Now pull to the other working repositories. First, we flush our changes in mybranch, since we'll be repulling them. This is essential or git will try to preserve two sets of the same changes, yuck.
| |
| ssh client2
| |
| git checkout mybranch
| |
| git reset --hard
| |
| Now just pull!
| |
| git pull
| |
| If you broke the rule about keeping your repos in sync before attempting this, it will leave you with a mess of conflicts. It happens. But it's easy enough to reset. Make sure client2 doesn't have any new changes, we're going to force it to match client1 now. We'll back up the config file to preserve our branch connections:
| |
| cp .git/config .git/config_backup
| |
| git checkout mybranch
| |
| git reset --hard
| |
| git checkout master
| |
| git branch -D mybranch
| |
| git branch mybranch
| |
| cp .git/config_backup .git/config
| |
| git checkout mybranch
| |
| git pull
| |
| | |
| == Result ==
| |
| | |
| You're now a git pro. You're ready to script all those steps and get up to top speed. Finally, as the reward for slogging through all this, here's a diagram of what you've got - seriously cool! :>
| |
| | |
| repo1
| |
| mybranch<->master
| |
| / \
| |
| public repo svn repo
| |
| \ /
| |
| mybranch<->master
| |
| repo2
| |