1 of 65

Git and GitHub 101

Introduction and Basics

2 of 65

Also see the GitHub 102 and 103 classes

GitHub 102

GitHub 103

3 of 65

First: Get a github3.cisco.com account!

4 of 65

https://engit.cisco.com/ci/#/request/question

Login with your CEC�Product: Github (NOT git!)�Category: New user request�Server: github3�Organization: CSPG/VIC

5 of 65

Git and GitHub: What’s the difference?

GIT

Version control system
Command line and GUI clients

GITHUB

Cloud hosting for Git repositories

Github.com: Open source / public
Github3.cisco.com (Github Enterprise): internal to Cisco

Includes lots of features integrated with your cloud-hosted git repositories

Code review
Continuous integration / testing

6 of 65

Subversion != Git

Do not expect Git to be exactly like Subversion.

There are fundamental differences.

7 of 65

Subversion

Centralized
Commits are remote

No staging area

Has “r” numbers for commits
Committing is the end of the development process
Add / remove entire files
Branching is uncommon

Merging is painfully slow

Branches and tags are folders

Emulates a file system
“trunk” is the default dev branch

8 of 65

Subversion

Git

Centralized
Commits are remote

No staging area

Has “r” numbers for commits
Committing is the end of the development process
Add / remove entire files
Branching is uncommon

Merging is painfully slow

Branches and tags are folders

Emulates a file system
“trunk” is the default dev branch

Distributed
Commits are local

Staging area for commits

Has SHA1 hashes for commits
Committing is the middle of the development process
Add / remove changes to files
Branching is extremely common

Merging is blazing fast

Real branches and tags

Is a directed acyclic graph (DAG)
“master” is the default dev branch

9 of 65

10 of 65

Git

11 of 65

Simple SVN → GIT command analogs

SVN operation	SVN commands	Git commands
Checkout	svn checkout https://…	git clone https://github3.cisco.com/… or git clone git@github3.cisco.com://…
See the history	svn log -r 1233:1234 svn log -c 1234	git log git log abc123 git log --graph --decorate --abbrev-commit --pretty=oneline git show # shows the commit meta data and diff of last commit git show HEAD~1 # shows one prior to the last commit git show abc123 # shows specific commit with hash abc123
Add / remove files	svn add <new_files> svn del <old_files>	git add <new_files> git rm <old_files>
See your local changes	svn status svn diff	git status git diff git diff --cached # shows what you have already staged for commit
Delete local changes	svn clean	git checkout [<files and/or dirs>] git clean -dfx # this is the nuclear option -- be careful!
Commit	svn commit [<files>]	git add <files with changes> git commit [<files>] git push
Fetch remote changes	svn up	git pull [--rebase]

12 of 65

Git: Storage model

Commits stored in a directed acyclic graph (DAG)

Stores a snapshot of the files each time you commit

Every commit has a 40-character SHA1 hash

Understanding Git’s storage model is�very Very VERY helpful�in understanding�how to use Git

13 of 65

Git: Directed acyclic graph (DAG) of commits

ae235f

bc4829

82b4f3

994c4a

master

Each blue box = one commit

Contains file tree/diff, parent pointer, author, ...etc.

“bc4829” is an abbreviation of the 40-character unique SHA1 hash

HEAD

HEAD points to the currently-checked out branch

Green box = branch name. They can move / be updated to point to new blue boxes

14 of 65

Git: The commit

A commit is defined by:

A tree: SHA1 of the tree representing the directory snapshot
Parent pointer: SHA1 of the parent(s). Root commit has no parent
Author: Name and e-mail of person responsible for the commit and the associated date
Committer: Name and e-mail of person who created the commit and the associated date
Commit message: Message describing the commit

15 of 65

Git: Set your name / email address

Do this on every machine where you commit:

$ git config --global user.name "YOUR NAME"� $ git config --global user.email "YOUR_CEC@cisco.com"

Otherwise, you’ll end up with commits from <root@vic-fw-bodega.cisco.com>

And you will be very sad

User information can be configured globally or per-repository

Repository specific configuration can be set using --local switch

16 of 65

Git: Staging area

Working�directory

Git

repo

Git

staging area�(a.k.a. “index”)

git commit

git add

git status

git diff

git diff --cached

17 of 65

Git: Branching

Very efficient, as easy as writing 40 bytes to a file
Often done for new features or fixes
You can delete branches after merging
“Branch early, branch often”

Branching is easy

and common in git!

18 of 65

But branching is scary!

And hard!

And slow!

19 of 65

Subversion branching is scary, hard, and slow

20 of 65

Git branching is fast and easy

21 of 65

Git: Branching: Exmple scenario

There is an established Git repository and a feature is needed
This is the perfect opportunity to use a branch!

22 of 65

Git: Branching: Starting out

ae235f

bc4829

82b4f3

994c4a

master

HEAD

23 of 65

Git: Branching: Create a branch

ae235f

bc4829

82b4f3

994c4a

master

pr/feature

HEAD

Note that “master” is still the checked-out branch

$ git branch pr/feature

Creating a branch just means creating a label and pointing it to a node in the DAG

24 of 65

Git: Branching: Check out the new branch

ae235f

bc4829

82b4f3

994c4a

master

pr/feature

HEAD

Now pr/feature is the checked-out branch

$ git checkout pr/feature

Git pro tip:

git checkout -b pr/feature

both in one step

25 of 65

Git: Branching: Add some commits to the branch

ae235f

bc4829

82b4f3

994c4a

ab223f

master

pr/feature

cc443a

HEAD

Commits update the pr/feature branch and HEAD, but master doesn’t move

...make changes...

$ git add file1

$ git commit -m “first commit for feature branch”

...make more changes...

$ git add file2

$ git commit -m “second commit for feature branch”

26 of 65

Git: Branching: Uh oh...

While working on the feature, a critical bug is found and we need to fix it ASAP.

NOT on the pr/feature branch

What now?

27 of 65

Git: Branching: Make a new branch, add a commit

ae235f

bc4829

82b4f3

994c4a

ab223f

master

pr/feature

cc443a

pr/fix-ASAP

ce425b

HEAD

Create new branch and add a commit fixing the issue

$ git checkout master

$ git checkout -b pr/fix-ASAP

...make changes...

$ git add ...

$ git commit -m “fixes a huge problem”

28 of 65

Git: Branching: Let’s merge!

Now comes the time to merge the changes
Let’s merge the “ASAP” fix first

29 of 65

Git: Branching: Merge pr/fix-ASAP

ae235f

bc4829

82b4f3

994c4a

ab223f

master

pr/feature

cc443a

pr/fix-ASAP

ce425b

HEAD

Master can “fast foward” to the DAG node where pr/fix-ASAP points

$ git checkout master

$ git merge pr/fix-ASAP

master

30 of 65

Git: Branching: Merge pr/feature

ae235f

bc4829

82b4f3

994c4a

ab223f

master

pr/feature

cc443a

pr/fix-ASAP

ce425b

HEAD

aa993c

$ git checkout master

$ git merge pr/feature

...opens editor for merge commit message...

Merge

commit

31 of 65

Git: Tags

Used to mark important points in history
Tags are immutable -- they cannot change
Examples:

Releng builds
Releases

Like a branch label that never moves

32 of 65

Git: Tags example

ae235f

bc4829

82b4f3

994c4a

ab223f

master

pr/feature

cc443a

pr/fix-ASAP

ce425b

HEAD

aa993c

Immovable / immutable tags.

build-342

build-343

build-341

33 of 65

Git: Universal help

“git help” is your friend

“git help <command>” is also your friend

git help commit
git help log
...

34 of 65

Git: Additional resources

GitHub GUI client: https://desktop.github.com/

Windows, Mac
Has some local Git support, but not full-featured

Windows people might like Git For Windows

https://git-for-windows.github.io/

35 of 65

Git: Additional resources

Git tutorials, especially for SVN users:

36 of 65

GitHub

37 of 65

GitHub: At Cisco

VIC driver code is on github3.cisco.com

There is a “vic” organization
All the official repositories are in the “vic” organization

Each developer also has a “workspace” area

This is where developers do their own work

38 of 65

github3.cisco.com

vic organization

enic-usnic-linux repo

fnic-linux repo

esxi-enic repo

esxi-fnic repo

...

“Vic” repositories typically contain:

Team master development branch
Release branches
Official code reviews (replacing PRRQ code reviews)
Team wikis
Team-local bugs / to-do lists / issues

Generally: anything that is to be shared by the entire team

39 of 65

github3.cisco.com

jsquyres (workspace)

bturrubi (workspace)

enic-usnic-linux repo (“fork”)

esxi-enic repo (“fork”)

Developer workspace repositories typically contain:

Personal development branches
Short-lived / single topic branches: features, bugs
Any other Cisco work not (directly) related to your team

Generally: anything that is not yet ready for the overall team repository

40 of 65

github3.cisco.com

jsquyres (workspace)

bturrubi (workspace)

enic-usnic-linux repo

esxi-enic repo

vic organization

enic-usnic-linux repo

fnic-linux repo

esxi-enic repo

esxi-fnic repo

...

Developers can share and collaborate across all repos

(yes, even between workspaces)

41 of 65

GitHub main workflow:�GitHub Flow

42 of 65

GitHub flow: Make a personal branch

Team’s main development branch

Individual developer branch

43 of 65

GitHub flow: Developer makes some commits

44 of 65

GitHub flow: Developer opens a “pull request”

(i.e., request to “pull” the code from the developer branch into the main line)

45 of 65

GitHub flow: Discuss and review the code

46 of 65

GitHub flow: Merge the code back to the main line

47 of 65

GiHub flow: Let’s do that IRL

Go here: https://github3.cisco.com/vic/git-example

Fork me!

48 of 65

GiHub flow: Example scenario

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

Do this on GitHub3

Do this with Git

Do this on GitHub3

Do this with an editor

Do this on GitHub3

49 of 65

Live demonstration

50 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example repo

vic/git-example

repo

fork

51 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine

Make a “remote” to your fork
Prevent accidentally pushing to the vic repo

Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example repo

git-example�repo

Clone

vic/git-example

repo

NOTE

In the Webex recording of these slides, we discussed cloning your fork repository.

These slides have been changed slightly to show you cloning the VIC repository and adding a “remote” to communicate with your fork.

The concept of “remote” will be discussed in the “102” slides.

If you’re new to Git / GitHub, use the “clone the VIC repository” method that is now shown in both the 101 and 102 slides. As you get more familiar with Git / GitHub and get more sophisticated in your Git usage, you may choose to use the “clone the fork” method if you wish.

52 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine

Make a “remote” to your fork
Prevent accidentally pushing to the vic repo

Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example repo

git-example�repo

Clone

vic/git-example

repo

$ git clone git@github3.cisco.com:vic/git-example.git

53 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine

Make a “remote” to your fork
Prevent accidentally pushing to the vic repo

Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example repo

git-example�repo

Setup remote

vic/git-example

repo

$ git remote add myfork \

git@github3.cisco.com:jsquyres/git-example.git

Take this command on faith for the moment; we’ll explain it in the 102 class

54 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine

Make a “remote” to your fork
Prevent accidentally pushing to the vic repo

Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example repo

git-example�repo

Prevent accidentally pushing to the VIC repo

vic/git-example

repo

$ git remote set-url origin bogus --push

Take this command on faith for the moment; we’ll explain it in the 102 class

55 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

Developer machine (laptop, server, etc.)

git-example�repo

$ git checkout -b pr/my-local-branch

56 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

Developer machine (laptop, server, etc.)

git-example�repo

$ vi file1 file2 file3 …

$ git add file1 file2 file3 …

$ git commit

57 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

Developer machine (laptop, server, etc.)

jsquyres/git-example

Git-example repo

Push

vic/git-example

repo

$ git push myfork --dry-run

# If the “dry run” looks ok, do it For Real

$ git push myfork

58 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

jsquyres/git-example

vic/git-example

repo

PR

59 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

jsquyres/git-example

vic/git-example

repo

PR

60 of 65

GitHub flow: What we just did

Create a fork of the vic/git-example repo
Clone vic repo to your machine
Make a local branch
Make a change
Commit the change to your branch
Push this branch to your fork
Make a pull request
See that CI testing passes (coming soon!)
Get a code review
Merge!

github3.cisco.com

vic/git-example

61 of 65

GitHub: Additional resources

On-Demand Github training:

GitHub 101: Introduction to GitHub
GitHub 102: Using GitHub Desktop
GitHub 103: Using the Command Line

Lots and lots of Git / Github step-by-step guides:

https://help.github.com/

Google for lots more GitHub information

62 of 65

Additional resources

63 of 65

Our favorite (basic) Git config

$ cat $HOME/.gitconfig�…�[core]� # set your favorite editor if it doesn’t come up by default� editor = vim�[alias]� pr = pull --rebase� graph = log --graph --decorate --abbrev-commit --pretty=oneline� grapha = log --graph --decorate --abbrev-commit --pretty=oneline --all� unstage = reset HEAD --� cached = diff --cached� last = log -1 --stat�[color "status"]� added = green� changed = red� untracked = magenta

64 of 65

Command line interaction with GitHub

Example: checkout a pull request:

$ cd my_libfabric_git_clone�$ hub checkout https://github.com/ofiwg/libfabric/pull/2582

Get it:

https://github.com/github/hub
OS X: sudo port install hub�or
OS X: brew install hub

65 of 65

Open questions / discussion