2015-11-04

• This document at GitHub
• This document as local preview

• Concepts
  • Git Object
    • Example: View Git objects
  • Git Revision/Name
    • Branches
    • Detached HEAD
    • Relative commits (^ vs ~)
    • Commit ranges
  • Remote repositories
    • Example: Sync across repos laterally
• Basic commands
  • TL;DR
    • Example: understand git status output
  • Staging Area
• reset vs checkout
• rebase vs merge vs reset
  • Rebasing
  • Merging
  • Resetting
• Survey of commands
  • Determine when a branch split off from master
  • Determine when a commit was eventually merged into master
  • Example: Do a rebase
  • Example: Recover from a pushed rebase
  • Example: Undo a merge
  • Example: Find a bug using git bisect
• Getting out of jams
• GrabCAD specific
• Development Environment
  • Sample .gitconfig
• Resources

• Git tracks file system snapshots (not deltas)

  e.g.,

  Subversion tracks deltas (revisions are constructed)

  

  whereas Git tracks snapshots (deltas are derived)

  

  However

  • pack files uses deltas internally but this is transparent

• A repository is a set of snapshots with parent-child relationships. Each repository has entire history.

  • Can restore a GitHub repo from a cloned copy!

  However

  • Unreferenced commits are garbage collected
  • By default, clones don't have pull requests (PR)
  • By default, lightweight tags are not cloned/synced

Git is basically a key-value database where keys are SHA1 hashes and values are Git objects (e.g., .git/objects/05/7915f4dc999e1a7903b4e58f33df27419701b9)

• Blob (i.e., file)
• Tree (i.e., directory)
• Commit (has reference to parent commits)
• Annotated tag (lightweight tags are not objects)

$ ls -la .git/objects/
$ git rev-parse head
$ git cat-file -p 50ed0df
$ git cat-file -p 9393828
$ git cat-file -p c2b9c90

See Pro Git book

• Is a "pointer" to Git object

• Types of pointers

  • SHA1 (e.g., 50ed0df30cbb0322331af9256711a94b622f990d). Does not move.

  • Reference (e.g., .git/refs/SOMEPATH path that leads to SHA1 hash). Can move. See Pro Git book

    • .git/refs/heads = point to last commit for a branch
    • .git/refs/tags = point to lightweight [not annotated] tag
    • .git/refs/remotes = point to last known HEAD on remote repos
    • .git/refs/pull/[0-9]+/(head|merge) = point to pull request commit

  • ^ or ~ suffixed (see below "Relative commits")

  • Colon path (e.g., HEAD~:README.md) (see Stack Overflow article)

  • Double colon path (e.g., :1:README.md) (for merges :1 for common stage, :2 for merge target, :3 for merge source)

  • ... and more types at "gitrevisions" manpage

• tree-ish = anything that points to a Git tree

• commit-ish = anything that points to a Git commit

  • Is also a tree-ish
  • See Stack Overflow article

Branches are references to commits.

• Local branch (e.g., .git/refs/heads/master)
  • Is moved by reset or checkout
• Remote branch (e.g., .git/refs/heads/master on remote repository)
  • Is moved [on remote repo] when others push to it
• Remote-tracking branch (e.g., .git/refs/remotes/origin/master) = last know position of "remote branch"
  • Is moved by fetch or pull
• Tracking branch = Local branch pegged to remote-tracking branch (e.g., branch.merge entry in .git/config)
  • Is moved by reset or checkout (i.e., same as local branch)
  • status is affected by either: local branch move or remote-tracking branch move

"detached HEAD" state = current HEAD is not on a branch HEAD

• Okay for viewing
• Do not do this for commits.
  • Otherwise, you will "lose" the commit when you do checkout to another branch or tag.
  • If you do this by mistake, use reflog to recover.

See Pro Git book

Use git rev-parse to find the SHA1 hash a reference refers to.

Following are all same

$ git log refA..refB
$ git log ^refA refB
$ git log refB --not refA

double dot (..) + triple dot (...) has different meanings between git log vs git diff

command	double dot (..)	triple dot (...)
	A -> B	mergeBase(A, B) -> B
	reach(B) - reach(A)	reach(B) + reach(A) - reach(mergeBase(A, B))

http://stackoverflow.com/questions/7251477/what-are-the-differences-between-double-dot-and-triple-dot-in-git-dif#answer-7256391

• git clone will create origin tracking remote repository (name origin is convention and not inherently special)
• git remote add REMOTE_NAME URL
• git remote -v
• git push REMOTE_NAME

$ git remote add pc /Volumes/Users/howard/code/hmak3d/eagle-desktop
$ git push -u pc mybranch
$ ls -la .git/refs/remotes/

See full list at git-scm

Covers 90% of Git usages

# Create local repo
$ git clone [email protected]:GrabCAD/eagle-print.git
$ vim README.txt
$ git diff
$ git add README.txt
$ git diff --staged
$ git commit README.txt

# Sync between local + remote repos
$ git push
$ git pull

# Create new branch and push to original repo
$ git checkout -b NEW_BRANCH
$ git push -u origin NEW_BRANCH

File has 4 states:

• Moving references
  • reset moves HEAD and the branch HEAD points to
  • checkout moves just HEAD

reset runs in 3 modes

checkout generally affects just working directory and staging area.

See Pro Git book

• When to rebase [instead of merge]?

• Never push a reset/rebase on master

• Never push a reset/rebase on branch unless all collaborators willing to either

  • throw away their local changes
  • rebase their changes on the new head. Note: A merge would undermine the point of the initial rebase.

• Which way to merge (master to branch 1st or branch to master 1st)?

• master -> branch merge vs branch -> master -> branch merge

  $ git checkout feature
  $ git merge    master       ## feature^1 is 1st parent; master is 2nd parent
  $ git checkout feature
  $ git merge    branch       ## fast-forwards; ref(feature) moved to ref(master)
  
  $ git checkout master
  $ git merge    feature      ## feature^1 is 2nd parent; master is 1st parent
  $ git checkout feature
  $ git merge    master       ## fast-forwards; ref(master) moved to ref(feature)
  

  Merge from branch to master 1st to keep master's history as "primary" (i.e., master is always 1st parent)

  What if already did opposite? ... then do a branch to master merge to restore "lineage" back to master.

• Avoid adding new files in merges. git log, gitk and many other git tools don't by default show merge deltas.

• Show master ever be fast forwarded on a merge?

Do this to:

• "undo" an accidental commit not yet pushed
• "undo" a rebase (use with git reflog)
• With caution: recover from a pushed rebase (you will lose changes)
• Split a commit during rebasing

• git log

  • git log --grep regexp to find string in comment
  • git log -S STRING to find string in diff (i.e., who deleted a line)
  • git log -G REGEXP to find a regexp pattern in diff
  • git log -p to report deltas
  • git log -m to analyze merge commits
  • git log --graph --oneline --decorate' to see text render of gitk
  • git log --graph --format="%h%d %an [%ar] %s"

• git push REMOTE :SPEC to delete tags + branches on remote

• git ls-files --error-unmatch PATH or git cat-file -t :0:PATH to see if a file is tracked

• git blame/log through file renames

  $ git blame      --follow -- NEW_FILENAME
  $ git log --stat --follow -- NEW_FILENAME
  $ git blame      --follow RENAME_SHA^ -- OLD_FILENAME
  $ git log --stat --follow RENAME_SHA^ -- OLD_FILENAME
  

• git reset magic

• git reflog to recover from rebase/reset

• git tag pruning

  $ git config --global alias.prunetag '!git tag -l | xargs git tag -d && git fetch -t'
  

• git clean -nxd + -fxd to scrub

• gitk and search on file path

• git merge -Xignore-all-space to reduce conflicts

• git merge --no-commit -X subtree=DIR eagle-desktop/GC-25779-NoStoreSelect to merge remote branch into directory DIR in local checkout

• git remote prune or git fetch --prune to delete remote-tracking branches

• git add -p (or git add -i) to trickle in new changes into several commits

TL;DR

git merge-base branch master

Explanation

Given

			o---o---o---B
		   /
	---o---1---o---o---o---A

git merge-base A B is 1

But what about more than 3 branches?

Given

		  o---o---o---o---C
		 /
		/   o---o---o---B
	   /   /
	---2---1---o---o---o---A

git merge-base A B C is 1 because the arguments are iteratively combined into hypothetical merges. i.e.,

                  o---o---o---o---o
                 /                 \
                /   o---o---o---o---M
               /   /
           ---2---1---o---o---o---A

git merge-base A B C = git merge-base A M = 1

TL;DR

	$ git log SHA1..master --oneline --ancestry-path > since.txt           # get direct path from SHA1 to master/head
	$ git log SHA1..master --oneline --merges --first-parent > merges.txt  # get merges onto master done *after* SHA1
	$ comm -12 since.txt merges.txt | tail -1                              # get earlier common commit between above 2 results

There is no single command. General approach is:

1. Get commits between your SHA1 + master. This will include extra stuff for commits done after the answer.
2. Get commits for merges along master made after the SHA1. This will include extra stuff for other branch merges done before the answer.
3. First the earliest commit between the two lists. This is the answer.

Explanation

• --ancestry-path prunes commits only to those on a direct path.

  Given

  						   D---E-------F
  						  /     \       \
  						 B---C---G---H---I---J
  						/                     \
  					   A-------K---------------L--M
  

  D..M = ^D M = {C, K, E, F, G, H, I, J, L, M } (i.e., everything but {A, B, D})

  						   D---E-------F
  						        \       \
  						     C---G---H---I---J
  						                      \
  					           K---------------L--M
  

  D..M --ancestry-path drops stuff that is not in the direct path between D + M (i.e., everything but {A, B, D, C, K})

  						   D---E-------F
  						        \       \
  						         G---H---I---J
  						                      \
  					                           L--M
  

• --merges prunes commits only to merges. This is useful for ignoring branch activity.

  Given

  						   D---E-------F
  						  /     \       \
  						 B---C---G---H---I---J
  						/                     \
  					   A-------K---------------L--M
  

  git log --merges M = { G, I, L }

• --first-parent prunes commits only to first parents. This is useful for ignoring branch activity.

  Given

  						   D---E-------F
  						  /     \       \
  						 B---C---G---H---I---J
  						/                     \
  					   A-------K---------------L--M
  

  git log --first-parent M = { A, K, L }

  So combining first-parent + merges is useful. If we have

  						   D---E-------F
  						  /     \       \
  						 B---C---G---H---I---J
  						/         \           \
  					   A-------K---N-----------L--M
  

  git log --first-parent --merges M = { N, L }

git rebase to rewrite history

To split commits:

	$ git fetch origin
	$ git rebase -i START_REV_EXCLUDED # and use "edit" on commit to split
	$ git reset head~
	$ git add -p PATH
	$ git commit
	$ git add -p PATH
	$ git commit
	$ git rebase --continue

To combine commits:

	$ git fetch origin
	$ git rebase -i START_REV_EXCLUDED # and use "squash" on later commits
	$ git commit
	$ git rebase --continue

You have not made any commits, but after a fetch you see

$ git status
On branch master
Your branch and 'origin/master' have diverged,
and have 1 and 1 different commit each, respectively.
  (use "git pull" to merge the remote branch into yours)
nothing to commit (use -u to show untracked files)

Someone else must have pushed out a rebase without warning you. They shouldn't have. 😧

The error message is cryptic because a rebase causes older commits to no longer belong to the remote repo (origin in this case). The abandoned/orphaned commits incorrectly appear to Git as changes you've made [not past changes already made on origin].

Since you are sure you do not have any commits, recover by doing:

$ git reset --hard origin/master

Note: If you did have commits, then you can do:

• another git rebase on origin/master if you're nice, or
• a git merge if the house is burning

git revert -m KEEP to undo a merge

	$ git log -1 -m -p REV
	$ git rev-parse REV^1 # To make sure `-m` argument is current
	$ git revert -m 1

• https://git-scm.com/docs/git-revert
• https://github.com/git/git/blob/master/Documentation/howto/revert-a-faulty-merge.txt

	$ git bisect start BAD_COMMITTISH GOOD_COMMITTISH
	$ git bisect run TESTSCRIPT	# Find earliest commit where TESTSCRIPT *fails*
	$ git bisect reset	# Clean up

logically same as manual steps

	$ git bisect start
	$ git bisect bad [BAD_COMMITTISH]	# Omit default to HEAD
	$ git bisect good GOOD_COMMITTISH	# Puts you into commit 1/2-way btwn good and bad

	$ git bisect bad	# Lower upper bound
	$ git bisect good	# Increase lower bound

	# Repeat "git bisect (bad | good)" to adjust bounds.  Stop when upper = lower.
	# i.e., repeated do: TESTSCRIPT && git bisect bad || git bisect good

	$ git bisect reset	# Clean up

• How do I cherry-pick changes (i.e., selective merge)? (-m 1 to generate diff against 1st parent)
• How do I minimize merge conflicts? See Pro Git book
• How to undo a merge? See Pro Git book
• How to undo a merge undo? Why would one want to do this?
• How do I find which commit introduced a bug?

• Use grunt bumpcommit in node development

  https://docs.google.com/document/d/1WkMp2b3nydn4Z4pS2grwc7oA7XLCpyG9SF50sGAvEmM/edit#heading=h.q6qiz7z2pq8h

• Don't forget to push tags. Do both:

  $ git push --tags
  $ git push
  

  or

  $ git push origin head --tags
  

• Vim Git plugin: http://www.vim.org/scripts/script.php?script_id=90

  let mapleader = ","
  let VCSCommandMapPrefix = "<Leader>v"	" So that VCSCommand uses ,v instead of ,c
  

• Other Vim plugins

  • Vundle package manager
  • Sublime-like multiple cursors
  • Emmet dynamic snippets

• Bash Git autocomplete

  # On Mac/Homebrew, setup via: brew install bash-completion
  [ -n "${IS_MAC}" ] && [ -f $(brew --prefix)/etc/bash_completion ] && source $(brew --prefix)/etc/bash_completion
  [ -n "${IS_WIN}" ] && [ -f /etc/git-completion.bash ] && source /etc/git-completion.bash
  

• zsh

• Git clients

  • msysGit (CLI bundled with Git install for Windows) https://git-for-windows.github.io/
  • tig (Git text UI) http://jonas.nitro.dk/tig/
  • gitk (Git GUI)
  • Atlassian SourceTree (Git GUI) https://www.sourcetreeapp.com/
  • GitHub Desktop (Git GUI) https://desktop.github.com/
  • TortoiseGit (GUI Integrated w/ Windows Explorer) https://tortoisegit.org/

• Chrome search engine https://git-scm.com/search/results?search=%s

• Vim ag integration: https://robots.thoughtbot.com/faster-grepping-in-vim

• Plug for Silver Searcher (ag)

   $ brew install ag
   $ choco install ag
  

[user]
	email = [email protected]
	name = John Doe
[alias]
	ann = annotate
	bl = blame
	br = branch
	bs = bisect
	ci = commit
	co = checkout
	cp = cherry-pick
	di = diff
	di0 = difftool -y --extcmd='diff -d'
	dis = diff --staged
	dt = difftool -y
	dts = difftool -y --staged
	logg = log --graph --oneline --decorate
	loggi = log --graph --format=\"%C(auto)%h%d %C(green)%an%Creset %C(yellow)[%ai]%Creset %s%C\"
	loggr = log --graph --format=\"%C(auto)%h%d %C(green)%an%Creset %C(yellow)[%ar]%Creset %s%C\"
	prunetag = !git tag -l | xargs git tag -d && git fetch -t
	reflogi = reflog --format=\"%C(auto)%h %gd [%ai] %s\"
	reflogr = reflog --format=\"%C(auto)%h %gd [%ar] %s\"
	rl = rev-list
	rp = rev-parse
	st = status -uno
	sts = status -uno -s
[diff]
	tool = opendiff
#	tool = meld
[push]
	default = simple

• https://git-scm.com/book/en/v2 (Pro Git book by Chacon & Straub)
• https://try.github.io/levels/1/challenges/1 (Interactive online tutorial for Git basics)
• http://pcottle.github.io/learnGitBranching/ (Interactive online tutorial for more advanced Git)
• http://gitref.org/index.html (Concise survey of Git)
• http://alblue.bandlem.com/Tag/gtotw/ (Blog covering tips that shed light on Git internals)
• http://www.git-tower.com/blog/git-cheat-sheet (Git CLI command cheat sheet)
• https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_prerequisites Chromium recommendations for Git onboarding

// vim:noet:ic:isk+=-