Atmospheric Spectroscopy Lab UMBC

ASL Git Flow

Thu, Oct 15, 2015 L. Larrabee Strow

Introduction

This document outlines how to use git for ASL packages, especially those with multiple authors. I want to start using the github machinery more since it helps provide documentation, and interaction.

Please note that it is very easy to browse source code on github, see differences, etc.

Suggested Flow

I have tested this flow by myself, and it seems relatively straightforward, but it is not absolutely trivial. I also finally learned how to do conflict merges, which is far easier than I realized in terms of the mechanics of handling the files.

Branching

Our plan is to have shared ASL packages to all be stored in github.com:strow. When I set one up, I give collaboration permissions to everyone, which pretty much gives you permission to do anything but delete the repo. But, in general, you should work on a branch (maybe named with your name). Here are the basic steps you should follow:

  1. Clone the repo from gihub.com, git clone github.com:strow/repo into your work area.
  2. Create a new branch that you will use for your changes, git checkout -b sergio
  3. You edit the repo, etc etc. (git add, git commit) etc.
  4. Push your branch back to github.com:strow/repo. (git push origin sergio).
  5. Got to github.com:strow/repo, select your new branch.
  6. Execute a Pull request on this new branch so it can be reviewed and merged into master. In theory you can do the merges yourself and skip this step. For now, for most of you, let’s do this using Pull Request.

Detailed Implementation

Most of you know the basics of using git, so that is not covered here. What I emphasize here is how to merge your changes into your fork of the the repo using the rebase command instead of merge, and how to fix conflicts, which none of us has done at all, or very often.

The basic problem is that the master branch of the repo may well change while you are working on your edits to the repo. This can be handled with a proper pull of the repo master and subsequent merging (or rebasing).

Clone the repo to your workspace. Checkout a branch for you to work in (new or old). I’m showing the command to create a new one named sergio.

git checkout -b sergio

Now start making your changes. This will involve a series of git add filename and git commit commands. I prefer more commits rather than fewer.

At any time you can git push origin sergio to your github account so we can all look at it. At some point while you are doing the previous steps, files in the master branch in github.com:strow/repo may change. Before you do your final commit of your branch (the one you want merged onto master) to github, you need to pull the master version, add that into your version, and fix any conflicts. The follow steps outline the process.

Rebasing Your Changes onto Master

Sitch to the master branch (won’t have new changes)

git checkout master

Update master from the repo, this should always work…

git pull --rebase

Go back to your branch, and flow your changes on top of master. This is the hard part since you will possibly get conflicts you must fix by hand.

git checkout sergio (Back to your branch)

git rebase master

This is the big one, this puts your commits “on top of” or after the new master changes. The above command will fail if there are conflicts. At this point you edit the files it complains about and fix the conflicts and do a git add. More on this later. After you edit the conflicted files you need to add them.

git add file1 file1

Finish the rebase.

git rebase --continue

until all is done (if requested by git, generally you should be done at this point). This now puts puts your commits after the latest commits to the strow master.

You have to force git to push a rebase, but since this was your private branch it is OK. Now send it to github.

git push origin sergio --force

Once this is done, go to branch sergio of this repo on github:strow hit Pull request so someone (maybe even you) can look at the changes and merge them into master. This can sometimes be done on github, sometimes whoever merges them might have to pull and merge locally and thenn re-push.

Fixing Conflicts during Merging or Rebasing

Fixing conflicts just involves editing the conflict file that git creates. Git will say to you (after asking for a merge or rebase) that “You must edit all merge conflicts and then mark them as resolved using git add.” You will see (in red on my terminal) a list of files that are labelled “both modified: filename”. Just edit filename, and follow the instructions in GitHub Help for Conflicts.

The basic idea is that this file has markers to show the conflicts, and you just edit the file (and remove the markers git added) until it looks the way you want. Very easy.

Squashing Commits

I prefer you to make commits fairly often, just to be sure you don’t stop working sometime and not commit your work and then forget what you did, or lose your work. However, it is hard to quantify this, you need to use your judgement.

If you made too many commits, or you think it makes sense to compact them into a single commit, git makes that very easy. But, you never do this on commits that are already in a public repo. You only do this on one of your local branches before you have pushed these commits to github (or the repo, in general).

Git makes this very easy to accomplish, see the fourth link in the section below for details.

Some URL’s with More Info