- Overview of version control and git (15 mins)
- A sample git work flow (5 mins)
- Successful projects and their characteristics (5 mins)
- Recommendations (5 mins)
- Discussion and Q&A (15 mins)
- References
Throughout this document italics denote my opinion. All other information should be objective :)
- 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
- 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.
- Requires much reading and understanding
- Flip side : information is overwhelming
- Much used for all programming
- But why?
- 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?
- 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!
- 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
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.
- 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 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")
- Used by many, many, many actively developed projects
- Cocos2D, Ruby on Rails, nodejs, XBMC, Android, CyanogenMod,
- FacebookSDK, AmazonSDK, Git, etc.
- Flavor of the moment?
> 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.
- 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.
- Take a repository "SomeSDK"
- Assume you want to work on adding "facebook support"
- You have two choices :
> 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
> 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"
- 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"
- Branches in remotes are also referenced by a "file-system-like" name
- "remotes/origin/master"
- "remotes/origin/async-file-io"
> ### 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
> ### Committer ...
> git am <patch files> ### Applies patch to repository
> ### 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"
- 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
- 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"
- 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.
- Login as Developer
- Create a project named TestProject on GitHub
- Use the web interface
- Will create a repo named TestProject
- https://github.com/developer/testproject
- Clone this repo to your local Mac/Linux/Windows machine
> cd $HOME
> git clone [email protected]: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 "[email protected]:developer/testproject.git"
> git branch -a ### Will show all branches
### "master" and "remotes/origin/master"
> 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 "[email protected]:developer/testproject.git"
- So, using github.com is having two repos
- Up to the developer to keep them in sync
- GitHub provides each Developer with an account
- Committer has a similar account
- Committer has a project named SomeProject
- Developer can fork SomeProject
- Now there is a copy of the SomeProject repo at
- Work on this by cloning to your local machine
- Make changes
- Commit these changes in your local machine's repo
- Push these changes to https://github.com/developer/Someproject
- Now, changes are visible to the world!!!
- 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.)
- 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
- 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
- Discussion
- 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!)
- 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
- What is not a good example?
- ... A webpage with a lot of statements about Git usage, but no proof.
- http://nvie.com/posts/a-successful-git-branching-model/
- Git
- Linux
- Ruby on Rails
- nodejs
- cocos2d
- Cairo
Note : These characteristics are less about Git and more about successful code
- Freedom to fork
- Code is always stable
- Easy to build
- Well defined commit criteria
- One committer or small committer team
- Committer reviews and integrates changes
- Easy to understand commit tree, few branches
- 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 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?
- Create repos for your project
- https://github.com/
- .../SpeedRacer/UnrealEngine
- .../SpeedRacer/ZDK-Android
- .../SpeedRacer/ZDK-iOS
- .../SpeedRacer/FacebookSDK
- https://github.com/
- Individual developers should clone the projects they work on
- For example :
- https://github.com/
- .../xxxx/UnrealEngine
- .../yyyy/ZDK-iOS
- https://github.com/
- Discussed in "3 : A sample git work flow"
- Use GitHub pull requests
- OR
- Use the example of a successful project :
- http://www.cocos2d-iphone.org/wiki/doku.php/faq
- 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
- http://www.cocos2d-iphone.org/wiki/doku.php/faq
- https://github.com/gitster/git/blob/master/Documentation/SubmittingPatches
- 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
- Please use fast-forwarding
- It keeps history clean
- It makes the committer's job easy
- The top Google hit for "git branching model" is
- DONT trust Google Search for your project :-)
- DO ask for objective measurements
- 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