Simple Git

Steve Pieper

Topics

• Git considerations and Slicer• Git as if it were svn• Git the way it is meant to be

Why Git?

• Slicer "upstream" projects use git:o VTK, CMake, Qt, CTK.  (Soon, probably, ITK too)o It is critical to have a common language for describing our

development processes• Git is designed to help coordinate large, distributed group

projectso e.g. linux kernel (for which it was purpose-built)

• Git provides a modern toolseto fast command line utilitieso highly interactive graphical tools (gitk, GitX, tortoisegit...)o web viewerso dedicated hosting sites (github, gitorious...)

Git considerations

• With more power comes more complexityo terminology is obscure (at first)

• Git is evolvingo useful new functionality came with 1.7 (4 months ago)o documentation and examples are plentiful, but more is

added all the time• There is a 'git way of doing things'

o don't venture too far from the beaten path

Slicer and Git

• Slicer3.6.X and Slicer4alpha still use svn.slicer.org • Slicer4 will use git

o repository not yet set upo will probably use slicer account on githubo want to set up the correct workflow from the starto when we migrate, all history will be brought forwardo some large binary data will be removed

• Repository will be created later this summero We are still in the learning and planning phase

Using git as if it were svn: checkout

svn checkout http://svn.slicer.org/trunk Slicer3   becomes git clone http://github.com/commontk/CTK.git CTK Notes:• svn downloads only one view, while git downloads a copy of

the full repository (including all history and branches)• all repository info is at the top level in a .git directory• you can operate on a local repository the way you would

with a remoteo This is a great equalizer: you can experiment and learn

without needing to set up a server

Using git as if it were svn: update

svn update   becomes git pull --rebase Notes:• in this mode, svn and git operate similarly, merging new

code from the repository into your local version (assuming you have made no changes)

Using git as if it were svn: commits

svn commit -m "message" file.h   becomes git add file.hgit commit -m "message"git push Notes:• git add: puts files in a "staging area"• git commit: is purely local• git push: sends the files to the remote server

Using git as if it were svn: further notes

Notes:• git status: tells you what you have modified• git commit -a: automatically adds modified files (that it

knows about)

Using git as if it were svn: diff

svn diff -r HEAD svn update   becomes git fetchgit diff origin mastergit rebase Notes:• this lets you "see what's new" before merging it into your

current directory tree

Using git as if it were svn: local changes

svn update   becomes

git stashgit pull --rebasegit stash pop

Notes:• this lets you save your current edits without committing them

to your local repository• you then can bring them back and apply them on top of the

latest code from the remote repository

Git as it was meant to be: branches

git help --workflows•  This page describes the "recommended workflows"

o so these are what the git developers use themselveso these are the best documentedo these form the core language for collaboration using gito We should follow them as closely as possible

•  Standard Integration Brancheso maint tracks the commits that should go into the next

"maintenance release", i.e., update of the last released stable version;

o master tracks the commits that should go into the next release;

o next is intended as a testing branch for topics being tested for stability for master. 

Git as it was meant to be: topic branches•  Brad King's excellent summary (with ascii art)

o http://public.kitware.com/Wiki/Git/Workflow/Topic•  Key Concepts:

o Amortize the effort of release preparation throughout development

o Support granular selection of features for release o Allow immature features to be published without delaying

release o Keep unrelated development paths (topics)

independent of one another o  Maintain a clean shape of history

• Note: cmake uses this "branchy" approach, vtk does not (yet)

Git as it was meant to be: notation

Images: Brad King

Git as it was meant to be: new topic

Images: Brad King

Git as it was meant to be: implement topic

Images: Brad King

Git as it was meant to be: push topic

Images: Brad King

Git as it was meant to be: mature topic

Images: Brad King

Git as it was meant to be: finish topic

Images: Brad King

Git as it was meant to be: history shape

Images: Brad King

Git summary

• Our goal is to "do it right the first time"o Implement topic branch workflows

• Learn best practices from the communityo Study workflow conventions used in other projects

• Get familiar with the tools before jumping ino Developers should create dummy repositories and

branches to see how all the tools behaveo Read man pages to become comfortable with the

terminology