set up a working git repository

1. In your private repo, move to the branch you wish you branch off of,
   • git checkout parent_branch_name
2. create a new branch off this parent, using one of the following sequences:
   1. if on the parent branch, create the branch then switch to it:
      • git branch new_branch_name
      • git checkout new_branch_name
   2. same as above, but done in a single command
      • git checkout -b new_branch_name
   3. same as above, but done on a non-parent branch
      • git checkout -b new_branch_name parent_branch_name
3. on your new branch in your private repo, you can
   1. add, delete file that git should track
      • git add . (to tell git to track all newly added files)
      • git add file_name (to tell git to track a specific file)
      • git rm file_name (to tell git to stop tracking a file, does NOT delete the file from the system, but may have to be called after a file has been deleted from the system, so git doesn't continue tracking a non-existant file)
   2. commit your file changes, creating a new local checkpoint
      • git commit (brings you to an editor screen, where you need to type at least a title, and potentially a description separated by a linkbreak)
      • git commit -a (same as above, but equivalent to calling git add . before committing)
   3. undo file changes and return to previous checkpoints
      • git checkout -- file_name (to replace with the copy last saved at a checkpoint)
   4. pushed to the public repo for backup and sharing
      • git push origin branch_name (note that origin is the name of your public repo)
4. once the branch is stable, merge the branch with the main dev trunk
   1. make sure that your local copy of dev is up to date
      • git checkout dev
      • git pull
   2. apply the changes present in dev (i.e. by others) to your own branch
      • git rebase dev (call this while on your own branch)
      • git rebase dev your_branch (or this while on another branch)
   3. move to the dev branch
      • git checkout dev
   4. apply your _stable _changes to the dev branch
      • git merge your_branch (due to the rebase above, you shouldn't run into any merging issues)
   5. sync the newly updated dev with the main repo
      • git push dev

The main repository then, will have two main branches

• dev where contributors branch new features, and merge stable features
• master, controlled by Chris, has the main working copy

In addition, many branches off of dev will exist from pushes, which can serve as backup and also used when seeking help.

• Note that other developers should not branch off these non-=dev= branches

Here is a sample session for working on a trivial bugfix:

# ensure your dev branch is up-to-date
> git checkout dev
> git pull

# decide to work on a new feature or bug-fix
> ti sync
> ti new

# add a succinct, descriptive title and a longer description
> ti show <ticket_id_just_created>

,----
| Title: remove erroneous whitespace from tools/ngsa_align/ngsa_align.cc
| TicId: 5aeacb3db5bb147c68472f42084a0d6a573eca9d
| 
| Assigned: cthachuk
| Opened: Tue May 04 09:29:42 -0700 2010 (0 days)
| State: OPEN
| Points: no estimate
| Tags: bug
| 
| Comments (1):
| 
|   * Added 05/04 09:29 by cthachuk@cs.ubc.ca
|    
|    In general, we should be careful of unecessary whitespace at the end
|    of lines.  It can play havoc on diff algorithms and git in general.
`----

# create a new topic branch off of your updated dev branch
> git checkout -b bugfix-5aeacb

# make changes, and create logical commits as necessary
> emacs tools/ngsa_align/ngsa_align.cc
> git add tools/ngsa_align/ngsa_align.cc
> git commit
> git log -1

,----
| commit cdafc93fb15d049265b2c6bea82219257b70fadf
| Author: Chris Thachuk <cthachuk@cs.ubc.ca>
| Date:   Tue May 4 09:32:27 2010 -0700
| 
|     Fixes ticket 5aeacb
|     
|     Removes erroneous whitespace from ngsa_align.cc file.
`----

# ensure your dev is still up-to-date
> git checkout dev
> git pull

# rebase your topic branch so that it will cleanly apply on top of dev
> git checkout bugfix-5aeacb
> git rebase dev

# finally, you can merge your topic branch into dev, and delete it
> git checkout dev
> git merge bugfix-5aeacb
> git branch -d bugfix-5aeacb

# note that after your rebase operation, your commit-id(s) may have changed
> git log -1

,----
| commit cdafc93fb15d049265b2c6bea82219257b70fadf
| Author: Chris Thachuk <cthachuk@cs.ubc.ca>
| Date:   Tue May 4 09:32:27 2010 -0700
| 
|     Fixes ticket 5aeacb
|     
|     Removes erroneous whitespace from ngsa_align.cc file.
`----

# push the changes upstream
> git push

# close the ticket and sync upstream
> ti checkout <your_ticket_id>
> ti state resolved
> ti sync