Join GitHub today
This gets pretty deep in the weeds. This page is a collection of common practices we use on Github. It's a way to document the things that have tripped us up on Github and to provide some documentation for common procedures like branch promotion, etc.
If you are unfamiliar with git it's useful to start here:
- http://sethrobertson.github.io/GitBestPractices/ -- Read this. We try not to repeat what's already here.
At Last - Gitx
If you are working on the Mac, Gitx is a really nice UI for Github. It's not perfect, but it really helps. Some things still need to be done from the command line, and it can hang up occasionally on large push and pull operations and need to be killed from the Activity Monitor. But on balance it makes managing the git tasks much easier.
The examples on this page are written assuming Gitx. Some command line operations are also provided as git command line commands, e.g.
user& git status, or [
user& git status] for the command line version of the gitx command just mentioned.
Github Standard Practices
A few rules to live by. Many git problems start from working in some "place" you don't think you are in or on some set of files in an indeterminate state. These practices help reduce those possibilities.
When you sit down to work always do this
- Check Branches and Stage area [
user& git status] to see what branch you are on and if you have any uncommitted files in your local repository
- Commit or stash any uncommitted files before doing the pull. You should generally avoid leaving uncommitted files at the end of a session, but it's not always possible.
- Pull origin and update current branch [
user& git pull origin CURRENT_BRANCH] to make sure you are synced with origin.
- You might need to do a manual merge at this point.
When you are ready to end the session leave the work area clean. Commit everything - unless you are sure you don't want to. Decide if you want to push or not.
- Commit from Stage dialog
- Command line for above:
git status] to see what you've got
git add] any new files you might have created
git commit -a -m"XXX.YY Build number and notes that are understandable by someone other than you"]
git push origin CURRENT_BRANCH]
- Push if decided
If you want to change branches do this:
- Commit and push everything in the current branch as above
git checkout NEW_BRANCH
git pull origin NEW_BRANCH
Setting up TinyG in Github
Do a complete pull
git clone email@example.com:synthetos/TinyG.git
You will have all 3 branches:
- master - stable production branch
- edge - relative stable development branch
- dev - current build. No guarantees.
Also at the command line it looks like you need to configure your git globals
git config --global user.name "yourname" git config --global user.email "firstname.lastname@example.org"
This will make it so when you push updates, your name will be "blue" for tracking purposes on github. (blue meaning it will link to your profile on github)
Using Tracking Branches
If you are going to a do a major new feature it can be useful to create a separate tracking branch. This isolates your changes from the parent branch until you merge in later, and makes removing those changes easier should you need to do that later. Setting up a tracking branch (Gitx):
- From the REMOTES/Origin area right click the parent branch (e.g. dev) and select
Create a branch that tracks origin/dev...
- Name the branch
feature-MMM.mm-name-of-feature- where MMM.nnn is the major and minor build number for the branch
- Later you can push the branch to origin, or not, depending on how you want to run it.
Do the development. When you are ready to merge the branch back into the parent:
- Select the parent branch (e.g. dev)
- Merge feature branch into main. It will likely have collisions and the merge will fail
- Got to gitx Staging and and edit the unstaged files to remove conflicts. Compile and verify operation
- Now from the command line (terminal)
git commit -a -m"merging feature-MMM.mm-name-of-feature
git statusto confirm that the dir is clean
- Back to gitx, push dev to origin.
To resolve conflicts you can just edit the conflicted files and remove the <<<<<<<< sections. When committing be sure the add these files with a git commit -a or a git add command.
This is a bit tricky but not hard. Just need to use a nice GUI merge tool if there are conflicts.
If you have not already set up a graphical merge tool run this:
git config merge.tool (response is silent as you have no merge tool) git config --global merge.tool opendiff git config merge.tool (response should now say opendiff) opendiff (run the command just to see of you have it. Response is "too few arguments...)
Now do the pull and get one or more conflicts. Git status will show Unmerged Paths. Something like:
# Unmerged paths: # (use "git add ..." to mark resolution) # # both modified: TinyG2/tinyg2.h
git mergetool and hit return at the prompt. Filemerge will open. There is a dot at the bottom of Opendiff that you can drag up to show the resulting file in a new pane (default position does not show the bottom pane). When done, "save" and then quit opendiff completely. It should take you back to the terminal. If there are more files to merge hit return again and repeat.
When done run
git commit. (from command line - does not work from gitx). It may throw you into vi. Save / Quit using
:x. If you are in vim the command is
You might end up with one or more xxxx.orig files. Run
git clean -n to list these. You can then run
git clean -f to remove them
Note that when you change .gitignore you must explicitly remove it from the cache by issuing:
git rm --cached .gitignore
Here's what we have in .gitignore right now:
*.elf *.pyc *.o *.map *.lss *.map *.d tinyg.aws tinyg.aps tinyg.atsln tinyg.atsuo tinyg.cproj tinyg.eep .DS_Store
See here for details: http://help.github.com/ignore-files/
Replacing working branch with a recover branch
Here's the scenario this is useful for:
- You find your main branch (presumably dev) has some killer error, and it's already been pushed
- You go back and find the last commit that worked OK by checking it out as a detached head
- You create a new branch (called "recovery") from there
- You work on the recovery branch and make a bunch of changes and commits
- Now you want to merge recovery into the main branch, but have the main branch "become" what's in recovery, discarding all the changes you made in the main branch
Here's how to do this:
git checkout recovery git merge --strategy=ours dev git status (just checking) git checkout dev git merge recovery git push
You can then delete the recovery branch. If you want it to garbage collect right away type
Brute force promotion of dev to edge or edge to master
THis is not the recommended way to do things. Better to do a merge. But in some cases this may be necessary.
- Final check compile in both AS4 and AS6 (ensure project files are OK)
- Double check:
- Build number is correct (and check all other Revisions and Compile-time settings)
- Settings to settings_default.h
- Comment out test99
- __SIMULATION is off
#first make sure both dev and edge are clean (no uncommitted files) git checkout dev git merge -s ours edge (edit commit message, exit with ":x") git status (just checking) git diff HEAD^ (should show no changes) #now go merge git checkout edge git merge dev #verify it worked git diff dev (should show no changes) git push origin edge
- Merge using
--no-ffThat's two dashes
- To set --no-ff as the default for that repo:
git config --add merge.ff false