3.2.2 Git for the impatient

Advanced note: The intent of this subsection is to get you working on lilypond as soon as possible. If you want to learn about git, go read Other Git documentation.
Also, these instructions are designed to eliminate the most common problems we have found in using git. If you already know git and have a different way of working, great! Feel free to ignore the advice in this subsection.

Ok, so you’ve been using lily-git.tcl for a while, but it’s time to take the next step. Since our review process delays patches by 60-120 hours, and you want to be able to work on other stuff while your previous work is getting reviewed, you’re going to use branches.

You can think of a branch as being a separate copy of the source code. But don’t worry about it.

Start work: make a new branch

Let’s pretend you want to add a section to the Contributor’s Guide about using branches.

Start by updating the repository, then making a new branch. Call the branch anything you want as long as the name starts with dev/. Branch names that don’t begin with dev/ are reserved for special things in lilypond.

git checkout master
git pull -r origin master
git branch dev/cg

Switch to that branch

Nothing has happened to the files yet. Let’s change into the new branch. You can think of this as “loading a file”, although in this case it’s really “loading a directory and subdirectories full of files”.

git checkout dev/cg

Your prompt now shows you that you’re on the other branch:

gperciva@LilyDev:~/lilypond-git (dev/cg)$

To be able to manage multiple lilypond issues at once, you’ll need to switch branches. You should have each lilypond issue on a separate branch. Switching branches is easy:

git checkout master
git checkout origin/staging
git checkout origin/release/unstable
git checkout dev/cg

Branches that begin with origin/ are part of the remote repository, rather than your local repository, so when you check them out you get a temporary local branch. You should never make changes directly on a branch beginning with origin/. You get changes into the remote repository by making them in local branches, and then pushing them to origin/staging as described below.

Make your changes

Edit files, then commit them.

git commit -a

Remember how I said that switching to a branch was like “loading a directory”? Well, you’ve just “saved a directory”, so that you can “load” it later.

Advanced note: If you have used cvs or svn, you may be very confused: those programs use “commit” to mean “upload my changes to the shared source repository”. Unfortunately, just to be different, git commit means “save my changes to the files”.

When you create a new file, you need to add it to git, then commit it:

git add input/regression/avoid-crash-on-condition.ly
git commit -a

Edit more files. Commit them again. Edit yet more files, commit them again. Go eat dinner. Switch to master so you can play with the latest changes from other developers. Switch back to your branch and edit some more. Commit those changes.

At this stage, don’t worry about how many commits you have.

Save commits to external files

Branches are nerve-wracking until you get used to them. You can save your hard work as individual ‘.patch’ files. Be sure to commit your changes first.

git commit -a
git format-patch master

I personally have between 4 and 20 of those files saved in a special folder at any point in time. Git experts might laugh as that behavior, but I feel a lot better knowing that I’ve got those backups.

Prepare your branch for review

After committing, you can update your branch with the latest master:

git commit -a
git checkout master
git pull -r origin master
git checkout dev/cg
git rebase master

Due to the speed of lilypond development, sometimes master has changed so much that your branch can no longer be applied to it. In that happens, you will have a merge conflict. Stop for a moment to either cry or have a stiff drink, then proceed to Merge conflicts.

Upload your branch

Finally, you’re finished your changes. Time to upload for review. Make sure that you’re on your branch, then upload:

git checkout dev/cg
git-cl upload master

Wait for reviews

While you’re waiting for a countdown and reviews, go back to master, make a dev/doc-beams branch, and start adding doc suggestions from issue 12345 from the tracker. Or make a dev/page-breaks and fix bug in page breaking. Or whatever. Don’t worry, your dev/cg is safe.

Combining commits (optional unless you have broken commits)

Does the history of your branch look good?

gitk

If you have a lot of commits on your branch, you might want to combine some of them. Alternately, you may like your commits, but want to edit the commit messages.

git rebase -i master

Follow instructions on the screen.

Note: This step gives you the power to completely lose your work. Make a backup of your commits by saving them to ‘.patch’ files before playing with this. If you do lose your work, don’t despair. You can get it back by using git reflog. The use of git reflog is not covered here.

Note: If any of the commits on your branch represent partial work that will not pass make && make doc, you must squash these commits into a working commit. Otherwise, your push will break staging and will not be able to be merged to master. In general, you will be safer to have one commit per push.

Push to staging

When you’ve got the coveted Patch-push status, time to prepare your upload:

git fetch
git rebase origin/staging dev/cg~0
gitk HEAD 

Note: Do not skip the gitk step; a quick 5-second check of the visual history can save a great deal of frustration later on. You should see a set of your commits that are ahead of origin/staging, with no label for the top commit – only a SHA1 id.

Note: If origin/staging and origin/master are the same commit, your branch (dev/cg in the example) will also be at the top of the gitk tree. This is normal.

If everything looks good, push it:

git push origin HEAD:staging

Then change back to your working branch:

git checkout dev/cg

Note: It is a best practice to avoid rebasing any of your branches to origin/staging. If origin/staging is broken, it will be deleted and rebuilt. If you have rebased one of your branches to origin/staging, the broken commits can end up in your branch. The commands given above do the rebase on a temporary branch, and avoid changing your working branch.

Delete your branch (safe)

After a few hours, if there’s nothing wrong with your branch, it should be automatically moved to origin/master. Update, then try removing your branch:

git checkout master
git pull -r origin master
git branch -d dev/cg

The last command will fail if the contents of dev/cg are not present in origin/master.

Delete your branch (UNSAFE)

Sometimes everything goes wrong. If you want to remove a branch even though it will cause your work to be lost (that is, if the contents of dev/cg are not present in master), follow the instructions in “Delete your branch (safe)”, but replace the -d on the final line with a -D.


LilyPond — Contributor’s Guide v2.19.5 (development-branch).