GitMajorWorkflow

Introduction

This is intended for development which will take more than a day, perhaps up to months, and may involve multiple contributors and validators, or should be documented in the git repository for some time. They may also mark breaking changes, need to be coordinated with product changes, other branches, or tags. Currently we plan to leave these branches visible in the repository until they are no longer of interest, at which time they may be archived so as to not clutter the repo forever.

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 head into your working branch
5. when the changes are final, merge your branch into the head.

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.

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>

advice on what to do if you end up on detached head here?

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, the branch needs to be merged into the head. what do we want for requests here?

Checkout the master, then merge your branch into it, and push it back.

git fetch
git checkout master
git merge <branchName>
git push origin master

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