git 101 for cloudstack
DESCRIPTION
An introduction to version control using git, github and the Apache CloudStack git repository. Git is a distributed version control where developers can mantain a working local copy, make local changes and push to a central repository to share their code with other developers. Git has replaced SVN and CVS has the version control system of choice, especially with the adoption of github by the OSS community. In this talk we show the basics of version control, we use gist from github to put simple scripts under version control and submit patches to it. We then show how to clone the cloudstack repository, explore the various feature and release branches. We then show how to create a patch and submit it to the Apache Software Foundation review board so that a committer of the CloudStack community can pick it up and apply it to the source tree. This is the perfect talk to discover git and submit your first patch to CloudStack.TRANSCRIPT
Using Git 101
Sebas/en Goasguen @sebgoa
Outline
• Intro to version control and Git • Crea/ng your first git repo using Gist • Cloning the CloudStack repo • Managing branches • Making your first commit • Applying a patch
NB: Check the footnotes for addi/onal informa/on
Version Control
• Revision control (a.k.a version control) is the management of modifica/ons of digital informa/on.
• In the context of soMware engineering it represents the management of the mul-ple versions of a so3ware as it evolves.
• In other terms it tracks changes in the source code.
hOp://en.wikipedia.org/wiki/Revision_control
Version Control Systems
• Historically: – Centralized systems used – Concurrent Version System (CVS) – Subversion (SVN)
• Currently: – Distributed version control – Git (2005) – Mercurial/hg
hOp://cvs.nongnu.org hOp://subversion.apache.org
hOp://git-‐scm.com hOp://mercurial.selenic.com
Workflow
• Developers clone a central repository
• Local repository is a working copy
• Updates are made locally (fast)
• When done, changes are pushed back to master
• Developers could push/pull to each other
hOp://i.stack.imgur.com/9IW5z.png
Ge]ng Git
• Apache CloudStack (ACS) uses Git as distributed version control system
• Install git on your machine. Depending on your OS and package manager:
! !#yum install git-core!! !#apt-get install git!! !#port install git-core!
Tour GitHub
• Check the publicly accessible repositories
• Create an account
Exercise: • Check Gist • Put a document under revision control
hOps://github.com/repositories hOps://gist.github.com
Create a Gist
Copy/Paste code or text in the main window, add a decrip/on. hOps://gist.github.com
See your first version in the UI
Clone gist
$git clone https://gist.github.com/5027212.git!Cloning into '5027212'...!remote: Counting objects: 3, done.!remote: Compressing objects: 100% (2/2), done.!remote: Total 3 (delta 0), reused 0 (delta 0)!Unpacking objects: 100% (3/3), done.!
$ cd 5027212/!$ ls!crawler.py!
NB: Here crawler.py is just an example, you will have a different filename
Modify and Commit your Gist
$ vi crawler.py !$ git add crawler.py !$ git commit -m "This is a gist test"!• [master 578d363] This is a gist test!• 1 file changed, 2 insertions(+)!$ git push!Username for 'https://gist.github.com': runseb!Password for 'https://[email protected]': !Counting objects: 5, done.!Delta compression using up to 4 threads.!Compressing objects: 100% (2/2), done.!Writing objects: 100% (3/3), 312 bytes, done.!Total 3 (delta 1), reused 0 (delta 0)!To https://gist.github.com/5027212.git! 04d6d71..578d363 master -> master!
Explana/ons
• We opened the file and made some changes • We made sure the changes were being tracked (git add).
• We commi:ed the changes to our local repository (git commit).
• To share these changes with others we pushed them to the remote repository (git push).
See the revisions
Browsing CloudStack
Explore the latest commits, view the diffs, browse the various branches hOps://git-‐wip-‐us.apache.org/repos/asf?p=incubator-‐cloudstack.git
Clone CloudStack
git clone https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git!
• Which branch are you on ?
$ git branch!* master!
What is a branch ? • A branch keeps track of a
history of code changes. • Mul/ple branches keep
track of diverging histories of code changes.
• You can switch between branches to work on code changes without impac/ng another branch
• You can merge branches to unify histories
hOp://git-‐scm.com/book/ch3-‐1.html
Iden/fy an ACS branch
$ git remote show origin!* remote origin! Fetch URL: https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git! Push URL: https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git! HEAD branch: master! Remote branches:! 4.0 tracked! 4.1 tracked!!<snip>!
Branching
• Releases are kept in their own branch (e.g 4.0, 4.1)
• Features are being developed on their own branch (e.g ipv6, events-‐framework)
• Default branch is master • You can checkout a remote branch • You can create a local branch
Checkout 4.0
$ git checkout 4.0!Branch 4.0 set up to track remote branch 4.0 from origin.!Switched to a new branch ’4.0’!$ git branch!* 4.0! master!!
• You now have a 4.0 local branch which tracks the 4.0 remote branch.
• Changes in your local branch is not propagated to the remote un/l you push.
Syncing with Others
• Other developers will push changes to the remote repository.
• To make sure you stay in-‐sync with the remote you need to pull changes to your local branch
• A pull will try to merge changes in the remote with your local branch. It may result in conflicts.!
$ git pull!Already up-to-date.!
Branching
• Get familiar with branching on your local repository
• Create branches, switch between them and delete them
$ git checkout –b foobar!$ git branch!$ git checkout master!$ git branch!$ git branch –D foobar!
hOp://git-‐scm.com/book/ch3-‐1.html
Configure git
vi ~/.gitconfig!git config –global user.name “your name”!git config –global user.email [email protected]!!!
• There are a lot more configura/on possible
hOp://incubator.apache.org/cloudstack/develop/non-‐contributors.html hOp://git-‐scm.com/book/en/Git-‐Basics-‐Tips-‐and-‐Tricks
Your first ACS Patch
• AMer cloning the ACS repository • Create a local branch (e.g mybranch) • Edit the files you want to modify. (e.g Add some documenta/on, fix a bug from JIRA)
• Stage your changes and check that you did not forget any files.
• Commit to the local branch. • Create a patch.
hOps://issues.apache.org/jira/browse/CLOUDSTACK hOp://incubator.apache.org/cloudstack/develop/non-‐contributors.html
First Patch
$ git checkout –b mybranch!!
• Make the changes you want $ git add <file you changed>!$ git status –s!$ git commit –m “Comment your changes”!$ git format-patch master –stdout > ~/myfirstpatch.patch!!!
• Look at the content of the patch
Verify the Patch
• It is a good idea to check that your patch can be applied cleanly
• Create a new branch star/ng from master, apply your patch, if successful submit to review board
$ git checkout master!$ git checkout –b testbranch!$ git apply --check ~/myfirstpatch.patch!$ git apply ~/myfirstpatch.patch!
Submit patch
• If you don’t have write access to the remote repository, you need a mechanism to send your patch upstream.
• In ACS we use Review Board. Create an account and enter a review request.
hOp://incubator.apache.org/cloudstack/develop/non-‐contributors.html hOps://reviews.apache.org/dashboard/
Conclusions
• Learn and Use version control • Simple cases are well…simple J • Git is used heavily, create a personal github account
• Apache CloudStack uses Git • Prepare patches and send them to us • Become an Apache Commi:er