Using Git with ODTBX: A Practical Tutorial

1. Using Git with ODTBX:A Practical Tutorial Ravi Mathur

2. Version Control Systems (VCS) • Old: Centralized VCS (Subversion) • State of the art before 2010 • Each “checkout”: snapshot of specific repo revision • Most repo operations require network connection • New: Distributed VCS (Git) • State of the art after 2010 • Each “clone”: FULL local copy of repository • Almost all repo operations are local (and FAST!) • ODTBX: 2.5GB (SVN)  1.7GB (Git)

3. Get Git • Official Website: http://git-scm.com • Preinstalled on Mac/Linux (command line) • GUI Clients: git-scm.com/downloads/guis • Mac: SourceTree • Windows: SourceTree, SmartGit, or TortoiseGit • DO THIS IMMEDIATELY: Set Git Identity • GUI Clients will prompt for this, or: • gitconfig --global user.name "John Doe” • gitconfig --global user.email johndoe@example.com

4. Get ODTBX • Git Clone: Copy entire repository • Analogous to svn checkout • For read/write access (with SourceForge account):git clone ssh://username@git.code.sf.net/p/odtbx/gitodtbx-git • For read-only access (without SourceForge account):git clone git://git.code.sf.net/p/odtbx/gitodtbx-git • For the internal repository (with NDC account):see Internal Repo slide • Repository Layout: • odtbx-git/odtbx/ODTBX_Source/, ODTBX_Data/, … vendor/ (All vendor folders) • No concept of “trunk” in Git • Clone ENTIRE repo (not just specific subfolders)

5. Working with ODTBX & Git • Almost all operations are on local repo! • Add/delete/modify files • Check commit log • Create/delete branches and tags • Git Workflow Quickstart (after cloning repo) • git pull: Download & merge from remote repo • work on files • git add files: Mark files (modified/new) for commit • git commit: Commit to local repo • git pull: Merge remote repo & do a final test • git push: Upload & merge to remote repo

6. The Git Commit Process • 3-step commit process (SVN is 2-step) • Working files: User-modified (also in SVN) • Staged files: Ready for commit • Committed files: Safely stored in repo (also in SVN) • Staging area • Commit all or only some changed files • Commit portions of a changed file • Allows for a forgiving & flexible work process • Can change many files, but commit them in groups according to features • http://git-scm.com/about/staging-area

7. The Git Commit Process • git add file • Adds file to staging area • Use to add new/modified files to staging area • git commit • Commits staged files to (local) repository • --dry-run: Test without actually committing • -a: Auto-add modified files to staging area, then commit all staged files.Shortcut for git add +git commit.

8. Git Branches • Very lightweight (no internal file duplication) • Easy to switch back & forth • git branch name: Create new branch “name” • git checkout name: Switch working branch to “name” • git merge name: Merge commit associated with branch “name” into current working branch • Main ODTBX development branch: develop • Default working branch for fresh clone • Analogous to SVN trunk • USE BRANCHES OFTEN!! (they only cost 41 bytes!) • http://git-scm.com/about/branching-and-merging

9. The ODTBX Git Workflow • If a new feature is being developed: • git checkout –b myfeature: Create & switch to branch • Work on files related to feature • Test feature • git add files: Add any new files to staging area • git commit –a: Stage modified files, then commit all staged files (modified + new). • git checkout develop: Switch to develop branch • git merge myfeature: Merge feature into develop • git pull: Get latest changes from remote repo • git push: ONLY AFTER RE-TEST & CCB APPROVAL

10. The ODTBX Git Workflow • If a trivial change is being made: • Work on files related to change • Test change • git add files: Add any new files to staging area • git commit –a: Stage modified files, then commit all staged files (modified + added). • gitpull: Get latest changes from remote repo • git push: ONLY AFTER TEST & CCB APPROVAL • For bug fixes: • Almost always nontrivial!! • Follow same process as for new features.

11. Git Revision Numbering • Git does NOT use revision numbers! • Think about it … everyone has their own repo…Rev 10 in my repo may be Rev 12 in your repo. • Git assigns 40-char hash to each commit • git log -1 cmt: Get commit log for commit cmt • cmt can be first few (at least 4) letters of full value • We will use 7-char hash abbreviation • Commit 66b69c5c0bc20d603ba21f7cb8fb1b796a94f167 •  Just use 66b69c5 • Use this everywhere ... even Mantis! • git log -1 66b69c5

12. External Contributors • Direct Contributor with SourceForge Account • ODTBXAdminUser Permissions: Add Contributor • Contributors have write access to SourceForge repo • Code contribution process: • Clone SourceForge repo • Create branch “myfeature” for contribution • Commit all tested contribution changes • Push branch (NOT DEVELOP) to repo • git push origin myfeature • ODTBX developer & CCB checks contribution • Merge branch into develop and push to SourceForge

13. External Contributors • Indirect Contributor • No direct write access to SourceForge repo • Code contribution process • Clone SourceForge repo • Create branch “myfeature” for contribution • Commit tested contribution changes • ODTBX developer pulls branch to local repo • Developer & CCB checks contribution • Merge branch into develop and push to SourceForge • Requires access to contributor’s repo

14. ODTBX Internal Repository • Contains sensitive code (potentially ITAR) • Take care when using internal repo! • Clone instructions provided by request • master/develop branches are restricted • They are sync’d with SourceForge nightly • NEVERtry to commit directly to master or develop • develop_internal branch should be used • Create your branch from develop_internal • Append “_internal” to your branch name