Github Notes

This gets pretty deep in the weeds. This page is a collection of tings that tripped us up on Github and some documentation for common procedures like branch promotion, etc.

TinyG Github Notes

If you are unfamiliar with git it's useful to start here:

• http://learn.github.com/p/intro.html
• http://gitref.org
• http://learn.github.com/p/tagging.html

Setting up TinyG in Github

Do a complete pull

git clone [email protected]: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 "alden.hart"
git config --global user.email "[email protected]"

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)

Normal Operations

Before getting started coding always make sure you are in sync with the github central repository.

cd your-working-directory
git status
git pull origin your-current-branch

Status tells you what branch you have open and what files are not committed. The pull gets you up-to-date with the centrol repo and ensures you are not going to clobber something later.

From here it depends on what you want to work on. I assume you want to go to dev to push your new changes you made.

Changing Branches

Before changing branches make sure you have all the work on the current branch committed. Otherwise git won't let you change. If you don't want the work in the current branch just reset git reset --hard. You will lose the work.

git checkout dev

This now switches your files for you. If you encounter difficulties and cannot switch to dev it's usually because some files in the dev branch have changed and will be clobbered if you switch. In general you need to move these files out of the way (e.g. to the desktop), do the checkout, then replace the checked out files with the ones you moved aside. Or not, if you don't want the changes. We are still working out the .gitignore as some of these files are irrelevant to the source.

You can also change branches to an earlier push by:

git checkout  

To recover just change branch back to dev or whatever. Use the git Commits link to find the commit you want, then copy the hash into your clipboard and use it during the checkout. ALl cautions about checking out branches still apply in this case.

Now edit or move files around. If you edit files things work as usual. If you have files edited elsewhere just copy them over the existing ones.

Once you are done issue a git status... Its optional but informative. Show's what's changed etc...

git status

If you need to get rid of any files do it through git, not the OS or finder/explorer. Some examples:

git rm filename.ext
git rm file*
git rm -r dirname

Note: git's gotten better about this. I routinely remove files from the OS now and git manages it OK

Pushing Code to Github

Our conventions for pushing to github are described here. Use whatever your build number is instead of 337.07 in the example;

cd <current dir>
git status 
(add any new files you might want. See the bottom of the status display)
git commit -a -m"367.04 A message that is informative to someone looking for a branch blah blah blah"
git push origin dev

If you want to tag the push add the following lines. We've found tags to be redundant if you provide good enough messages. Tags are useful for release candidates and other things like that, however.

git tag -a 337.07 -m"build 367.04 Release candidate for version 0.95"
git push origin dev --tags 

NOTICE THE ORIGIN KEYWORD IN THE PUSH

The pull should have been done before you made any changes, but at least this will tell you if you are going to have a problem in your push.

Merging

This is a bit tricky but not hard. Just need to use a nice GUI merge tool if there are conflicts.

The command is:

git checkout master
(This sets your master branch active... This is where you are going to PULL another branch into merge with) git merge branch-to-merge-with 

First make sure everything is up to date - synchronize the lowest branch to github:

• If the IDE is open close it and save whatever you need to
• Add and Commit anything that's been changed
• run git status to confirm there's nothing hanging out there
• git push origin <branch>

Example of merging master with edge:

git checkout master
git merge edge

That should do it.
But it usually doesn't. Usually you find merge conflicts on readme.md, tinyg.aws or other files. Do this:

• Make a temp directory on the desktop or somewhere else outside the git directory
• Put copies of all the files in conflict into this directory
• git rm all the conflicted files. Remember to do git rm, not just rm!
• See if the files that were pulled in from the pull branch (e.g. from edge merging into master) are the ones you want. If so keep them,. If not, overwrite them from the temp directory
• Add any new files to git - e.g git add .
• Commit all changes - e.g. commit -m"339.09 added files from edge into master as part of a merge"
• Do the merge again (e.g. git merge edge) Finish the merge by running git

Checklist for Promoting Branches

Steps to promote dev to edge and edge to master are listed here. There's probably an easier way to do this for someone that really knows how to use github, but this is what I do. Comments and suggestions for improvement are welcome. Derision and sneers are amusing.

Start in the dev branch

• Make sure all dirs are where you want them
• firmware - all code changes are in place and pushed to github as dev. Make sure the project is set to -Os optimization and all debug defines are disabled. Compile under both 4 and 6 and verify
• Move the fresh project files into the support directory
• hardware - look for changes to any schematics or other HW artifacts
• gcode_samples - add any new files or rearrangements of existing files
• Get the support directory up to date. This includes
• edit the readme files. If you mad any changes to the dev file copy it into the main dir and rename it to readme.md to replace the one that's in there.
• bring in the current studio 4 and studio 6 project files for tinyg and xboot. Overwrite any old ones that are there.
• are there any drivers or other artifacts to add?
• Update xboot if needed
• Make sure dev is fully pushed to github
• Stash copies of all the directories in a stash directory

Now do the edge branch

• Change branches to edge
• Replace the edge directories with the ones you stashed from dev
• Run git status to see what you've got. Look for any untracked files and add them if needed
• Replace the readme.md file in the main directory with the readme_edge.md (renamed to readme.md)
• When you are satisfied that tings look right - git push origin edge

Promoting edge to master is similar

Tags

Tags support getting back to earlier builds. See here: https://github.com/synthetos/TinyG/tags

To list local tags type

git tag

Once you are ready to commit (or push your changes) create a tag using this format:

git tag -a 337.06 -m "build 326.06 - <some note as to what this build is about>"

Then push the tag to the public repo. By default, the ‘git push’ command will not transfer tags to remote servers. To do so, you have to explicitly add a –tags to the ‘git push’ command:

git push origin dev --tags

You can delete a remote tag the same way that you delete a remote branch.

 git push origin :326.06

And delete your local tag with:

git tag -d 326.06

from http://stackoverflow.com/questions/6151970/how-do-you-remove-a-tag-from-a-remote-repository

.gitignore

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/