Skip to content

Instantly share code, notes, and snippets.

@rolandoam

rolandoam/gist:2423749

Created April 19, 2012 19:56
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save rolandoam/2423749 to your computer and use it in GitHub Desktop.
Save rolandoam/2423749 to your computer and use it in GitHub Desktop.
Download ZIP
git presentation
Raw
gistfile1.md

Agenda

  1. Overview of version control and git (15 mins)
  2. A sample git work flow (5 mins)
  3. Successful projects and their characteristics (5 mins)
  4. Recommendations (5 mins)
  5. Discussion and Q&A (15 mins)
  6. References

Throughout this document italics denote my opinion. All other information should be objective :)

About me

  • https://github.com/folecr
  • I have used various source control systems
    • both distributed and centralized
    • SCCS/Teamware, Mercurial, Perforce, Visual SourceSafe, SVN
  • Have actively used Git since 2007/2008

Quick summary

  • There are thousands of projects using Git and GitHub
  • https://github.com/explore - 2,368,811 repositories
  • Please use the proven templates of open source projects
  • IMPORTANT : Don't re-invent the wheel. Use proven strategies.

Quick summary (contd.)

  • Requires much reading and understanding
  • Flip side : information is overwhelming

=== 1 ===

Overview of version control and git

Version control

  • Much used for all programming
  • But why?

Uses

  • Source code distribution to programmers
  • Source code release
  • Release management (numbering)
  • But all this can be done by simple scripts!
  • Is versioning control SIMPLY an off-the-shelf Release System?

Important use

  • Share code!
    • to refer to individual changes
    • to review changes
    • to revert changes
    • to manage multiple programmers
    • using the same codebase
  • Improves productivity!
    • The alternative is to work alone!

Also for code organization!

  • Individuals may organize multiple threads of work
  • To work on one codebase...
    • multiple threads of work simultaneously
    • and (just like a team) to review and revert
  • Overall, much more efficient than maintaining multiple archives
    • Or custom file management scripts

Git

http://www.git-scm.com

Originally developed by Linus Torvalds. First customer was the Linux kernel project.

  • Distributed version control
  • Every Git repository has the entire history of all files in the project.

Git (contd.)

  • Secure identification : Every commit can be securely identified by it's hash (under the limitations of SHA1 hashing)
  • Tools for editing the commit tree : re-ordering and editing the commit tree is exceptionally flexible.

GitHub

GitHub is a large scale code hosting platform built on Git. http://www.github.com

  • Organizations
  • Git repository management
  • Web based history browser
  • Web based management of code merges ("pull requests")

GitHub (contd.)

  • Used by many, many, many actively developed projects
  • Cocos2D, Ruby on Rails, nodejs, XBMC, Android, CyanogenMod,
  • FacebookSDK, AmazonSDK, Git, etc.

Caveat

  • Flavor of the moment?

=== 2 ===

A sample git work flow

Working with Git

> git init .                   ### Initialize repository
> touch <filenames>            ### creates files, git repository still empty
> git add <filenames>          ### adds to staging area, repo still empty
> git commit -m "Message text" ### committed! repo now has one version.

Working with Git (contd.)

  • A repository contains : local files, staging area, versioned tree
  • Each version is securely identified by a SHA has
  • The hash also uses the previous commit's hash so each commit tree
    • is uniquely and securely identified.

Branches

  • Take a repository "SomeSDK"
  • Assume you want to work on adding "facebook support"
  • You have two choices :

Branches (contd.)

Choice 1 : Make a copy of "SomeSDK" on your file system

    > cp -rf SomeSDK SomeSDK-facebook-support  ### Copy entire repo
    > cd SomeSDK-facebook-support               ### New repo has entire history
    > touch supportfacebook.cpp                  ### Make changes
    > git add supportfacebook.cpp
    > git commit -m "Add facebook support"       ### Commit to repository

Branches (contd.)

Choice 2 : Make a branch called "facebook-support"

    > cd SomeSDK
    > git checkout -b "facebook-support"         ### New branch, just like a copied directory
    > touch supportfacebook.cpp                  ### Make changes
    > git add supportfacebook.cpp
    > git commit -m "Add facebook support"       ### Commit to repository, in a branch named "facebook-support"

Remotes

  • Each Git repository has full history (Git is distributed)
  • Can hold references to other repositories ("remotes")
  • Referenced by a "file-system-like" name
    • "remotes/origin"

Remotes (contd.)

  • Branches in remotes are also referenced by a "file-system-like" name
    • "remotes/origin/master"
    • "remotes/origin/async-file-io"

Sharing changes with Git

> ### Developer ...
> git checkout -b <name of feature> ### Creates a new branch
> touch <filenames>                 ### Make changes
> git add <filenames>               ### Adds to staging area
> git commit -m "A change"          ### commits change
> git format-patch HEAD~..HEAD      ### Makes a patch of the most recent commit
> mail <0001-A-Change>              ### ... Email patch to committer

Sharing changes with Git (contd.)

> ### Committer ...
> git am <patch files>              ### Applies patch to repository

Sharing changes with Git (contd.)

> ### Developer ...
> git branch -d <name of feature>   ### Change accepted! Delete branch.
> git checkout master               ### Switch to master branch
> git fetch origin                  ### Get the changes from committer
> git rebase origin/master master   ### Re-applies master on top of origin/master 
                                    ### Developer now has committer's changes!
                                    ### Including Developer's previous change titled "A change"

Sharing changes with Git (contd.)

  • Commits are identified without specific version numbers
  • Because commits are identified by a hash of the commit and the ancestor commit, Developer is assured that the changes match Committer's

Working with GitHub

  • GitHub provides each Developer with an account
  • Each account can hold multiple repos
  • Each repo may have multiple branches
  • Think of your github account as a "shared folder of repos"

Working with GitHub (contd.)

  • There are multiple users with GitHub accounts
  • Also organizations :
    • An organization is like a user in how it contains repos
    • An organization may have members too.

Working with GitHub (contd.)

  • Login as Developer
  • Create a project named TestProject on GitHub
  • Clone this repo to your local Mac/Linux/Windows machine

Working with GitHub (contd.)

> cd $HOME
> git clone git@github.com:developer/testproject.git ### Creates a git repo named "testproject" in $HOME
> cd testproject
> git remote -v                     ### Will show all remotes
                                    ### Currently "origin" will point to the address you cloned from "git@github.com:developer/testproject.git"
> git branch -a                     ### Will show all branches
                                    ### "master" and "remotes/origin/master"

Working with GitHub (contd.)

> touch <filenames>                 ### Make changes
> git add <filenames>               ### Adds to staging area
> git commit -m "A change"          ### commits change
> git push origin master            ### push this change to the remote named origin
                                    ### Which is your github repo "git@github.com:developer/testproject.git"

Working with GitHub (contd.)

  • So, using github.com is having two repos
  • Up to the developer to keep them in sync

Sharing changes with GitHub

Sharing changes with GitHub (contd.)

Sharing changes with GitHub (contd.)

Sharing changes with GitHub (contd.)

  • Now, tell the committer that developer forked from
  • Open a github pull request
  • If Committer likes the changes, they will pull changes into their repository
  • OR, submit patches using git style (described earlier.)

Syncing Repos

  • This seems to be confusing
  • To RECAP : GitHub hosts git repos, Developer make clones of these repos
    • on local machines
  • These are two entirely separate Git repos
  • Connected only by a "git remote" entry

Syncing Repos (contd.)

  • Repos may go out of sync
    • Developer makes changes in local machine
    • Commits are added in GitHub repo
  • Also, Committer's repo and Developer's GitHub and Developer's repos
    • may go out of sync!
    • They are still separate Git repos
    • connected only by a "git remote" entry

Syncing Repos (contd.)

  • Discussion

=== 3 Successful projects and their characteristics ===

Example Git projects

  • A Git project with frequent contributions
  • Many developers. Let's say at least 10.
  • Developed in the open so we can learn from it.
  • With credible committers (hello... Linus Torvalds!)

Example Git projects (contd.)

  • Their developers have motivation to learn tool use
    • To get their commits/patches into the project
    • And therefore their contributions get credited!
  • Committers and developers have dealt with Git and GitHub issues

Example Git projects (contd.)

Example Git projects (contd.)

Example Git projects (contd.)

Example Git projects (contd.)

Characteristics

Note : These characteristics are less about Git and more about successful code

  1. Freedom to fork
  2. Code is always stable
  3. Easy to build
  4. Well defined commit criteria
  5. One committer or small committer team
  6. Committer reviews and integrates changes
  7. Easy to understand commit tree, few branches

=== 4 Recommendations ===

GitHub Teams and organizations

  • Create a GitHub organization for your project
  • If it is a game, use the name of the game
  • If it is a product, use the name of the product

GitHub Teams and organizations (contd.)

  • GitHub creates an "Owners" team
  • Create a "Developers" team
  • Add all developers to the "Developers" team
  • Minimize the Owners team

I suggest adding a non-programmer as an Owner to avoid accidental deletion. Maybe a QA engineer?

Project repos

  • Create repos for your project
    • https://github.com/
      • .../SpeedRacer/UnrealEngine
      • .../SpeedRacer/ZDK-Android
      • .../SpeedRacer/ZDK-iOS
      • .../SpeedRacer/FacebookSDK

Cloning

  • Individual developers should clone the projects they work on
  • For example :

Individual workflow

  • Discussed in "3 : A sample git work flow"

Contributing patches

Reviewing and committing

  • One owner per repository
  • Responsible for committing all changes
  • Maybe a small team for large repos
  • Too many committers causes chaos
  • ... and project loses direction

Reviewing and committing (contd.)

Feature branches

  • I suggest using feature branches in individual repos
  • Many developers find it painful
  • Highly recommended for larger changesets
  • You can generate GitHub pull requests from any-branch-to-any-branch
    • so can generate pull requests from a feature branch to a master

Fast forwarding

  • Please use fast-forwarding
  • It keeps history clean
  • It makes the committer's job easy

A note on branching

A note on branching (contd.)

  • This branching model is flawed :
    • previous released branches cannot be hot-fixed cleanly
    • Individual developers cannot rebase
    • fast-forward merges are impossible
  • It's basically Subversion in a Git repository.
  • Don't use it for a team

It's fine for individual developers

=== 5 Discussion and Q&A ===

=== 6 References ===

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment