GitMajorWorkflow

Introduction

This workflow should be used for almost all code development. It describes how to create your own branch and commit work to that branch. When you believe the code on the branch is ready to go, you can email a "pull request" to the Offline heads, who will merge your branch into the head, when they agree it is ready.

If you are new to git, please read the git intro and the minor revision workflow, which is very useful for concepts.

Overview

The logical steps are as follows.

1. checkout or create a work branch
2. make revisions and commit them
3. as needed, push this branch to the repo
4. as needed, merge the master branch into your working branch
5. when the changes are final, request to merge your branch into the master branch

This workflow may span weeks, so steps 3 and 4 may need to be done several times. It is fine to save your work this way. It may be needed to tag the branch at various times, to pause for testing, for example, or to pass a given state to another worker.

We have agreed that branches can be temporary or may be very long-lived. In the case of temporary, the branch name would correspond to a specific project. Once the project is finished and the work incorporated back into the main branch, then the branch is left alone at the merge point. In the long-lived case, there may be a more generic branch, such as "geometryDev", which is merged into and out of the main branch for many projects over years.

Cheat Sheet

Begin with a clone

git clone ssh://p-mu2eofflinesoftwaremu2eoffline@cdcvs.fnal.gov/cvs/projects/mu2eofflinesoftwaremu2eoffline/Offline.git

If the branch you want to work on already exists

# make sure you have the current branch commits
git fetch
git checkout -b <branchName>

or if you are creating it from the head:

# make sure you have the current head
git fetch
git checkout -b <branchName>

or if you are creating it, and want to start the branch at commit <tagOrCommit>:

git checkout -b <branchName> <tagOrCommit>

If you get a "detached HEAD" warning here, you have done something wrong - do not continue or your commits may get lost.

Make your revisions and commit them. It is important to stay on this branch while committing.

git status
On branch branchName

Typically, you will be the only person working on the branch, but if the branch already exists in the repository, here is how to check if there were any other commits to this branch.

git fetch
git diff <branchName> origin/<branchName>

If there were commits, you can merge them into your branch

git checkout <branchName>
git pull

To push your current branch:

git push

Assuming this is a long-term development project, others may have made commits to the head of the master branch, and now you want to make sure your branch will still work with those changes. The procedure is to merge the head of the master branch into your branch. Note that this applies the master branch commits to your branch, but it does not rebase. The repository will show the merge, but the history of your commits to your branch is still visible. (In a rebase, the work along the master branch up to the rebase is applied, but the record is dropped so it appears the branch starts at the point of the rebase. See GitMinorWorkflow.)

# make sure you have the latest of the remote repo
git fetch
# update your local master to the remote head
git checkout master
git pull
# merge master to your branch
git checkout <branchName>
git merge master

This procedure syncs your local master from origin/master before merging your local master into your branch. Note the possible difference between master and origin/master. can you merge origin/master? will the result look the same?

Conflicts may need to be fixed.

If you need to tag the branch, create tag name and while the branch is checked out,

git tag -a -m "comment" <tagName>
git push origin <tagName>

Naming the tag to push prevents accidentally pushing any other tags, though our default is set so that push only pushes current branch.

Once all development and validation is complete, and you have merged the latest head of master into your branch, you can email a pull request to the Offline heads. They will make a judgment on whether the pull can happen immediately or if there needs to be more documentation or testing.

Once there is agreement to proceed with the merge, the heads may do the merge itself, or ask you to do the merge. If you need to the do the merge,

If you were told to do the merge, checkout the master branch, merge your branch into it, then push it back.

git fetch
git checkout master
git merge --ff-only <branchName>
git push origin master

The "ff-only" switch will abort the merge if you have not merged the latest of master branch into your branch.

Naming branches and tags

We suggest branch names made up of 3 parts

1. the starting point. Thsi is relevant if the starting point is a tagged release or other significant commit. If the start of the branch is the current head, and has no significance, it can be left off.
2. the nemonic name. The string which tells any casual viewer the purpose of the work
3. the word "branch"

A branch name might look like:

v5_7_9-cosmic_target5-branch       # branch

If you need to tag the branch to label a particular commit, perhaps for testing, replace the "branch" with the version of the tag. The version will start at zero for each new branch and advance

v5_7_9-cosmic_target5-v0   # tag