Dreaming in Git

Understanding Git well enough to anticipate its every move.

Marcel M. Cary

Dreaming?

Learning a foreign language:

At first you decide what to say in your native language and translate it
Eventually, your thoughts begin to surface directly in the new language, avoiding the need for translation
Someday, it becomes second-nature; you notice you are dreaming in the new language

Goals

Develop a visual model for thinking about Git
Learn how some commands map to this model
See tools for discovering how additional commands manipulate that model
Begin to understand why Git is fast

About Me

At O'Reilly Media (this campus)
On a team of 5 developers, collaborating via Git every day
Using Git as primary version control for 7 years
Have trained people on using Git
Contributor to git.git, the Git codebase

Level

I will assume you:

Already use Git
Have a basic familiarity with branching and merging

This is not an intro-level presentation, but you can still learn something if you have not used Git before.

Git Commit IDs

Git uses a sha1 hash to name a commit
Like an id identifies a row in a database
Like pointer points at an object in C/C++

Example Commit IDs

~/Projects/git|master$ git log --format=fuller 2c3c395e
commit 2c3c395e84409c278bd7b050877c36d04b952056
Author:     Marcel M. Cary <marcel@oak.homeunix.org>
AuthorDate: Fri Feb 6 19:24:28 2009 -0800
Commit:     Junio C Hamano <gitster@pobox.com>
CommitDate: Sat Feb 7 00:45:29 2009 -0800


    git-sh-setup: Use "cd" option, not /bin/pwd, for symlinked work tree

    In cd_to_toplevel, instead of 'cd $(unset PWD; /bin/pwd)/$path'
    use 'cd -P $path'.  The "-P" option yields a desirable similarity to
    ...

More Commit IDs

~/Projects/git|master$ git log --oneline 7d233dea
7d233de gitweb: Hyperlink multiple git hashes on the same commit message line
024aa7d system_path(): simplify using strip_path_suffix(), and add suffix "git"
4fcc86b Introduce the function strip_path_suffix()
88e3880 filter-branch -d: Export GIT_DIR earlier
51b2ead disallow providing multiple upstream branches to rebase, pull --rebase
d61027b Skip timestamp differences for diff --no-index
b94ead7 git-svn: fix parsing of timestamp obtained from svn
df5d10a gitweb: Fix warnings with override permitted but no repo override
bed5122 Documentation/git-push: --all, --mirror, --tags can not be combined
...

Commit ID, AKA:

Hash
SHA1
Commit ID

Immutability

Git Commit IDs are a digest (checksum) of the commit attributes, which cryptographically guarantees that the commit can't be altered.

Committing

~$ mkdir example-repo
~$ cd example-repo
~/example-repo$ git init
~/example-repo|master$ touch README.md
~/example-repo|master$ git add README.md
~/example-repo|master$ git commit -m 'Initial commit'
[master c714722] Initial commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 README.md

Another Commit

~/example-repo|master$ echo hi > README.md
~/example-repo|master$ git commit -am 'Say hi'
[master 016e54b] Say hi
 1 file changed, 1 insertion(+)

~/example-repo|master$ git log -p
commit 016e54bea7d5803346ed1b57b963fefe3ea22d9d
Author: Marcel M. Cary <marcel@oreilly.com>
Date:   Tue Feb 9 20:16:48 2016 -0800

    Say hi

diff --git a/README.md b/README.md
index e69de29..3b18e51 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1 @@
+hi

commit c714722b9a633a523a982ad5b88374a37683ce1d
Author: Marcel M. Cary <marcel@oreilly.com>
Date:   Tue Feb 9 20:05:58 2016 -0800

    Initial commit
...

A Better Commit

~/example-repo|master$ echo 'Hello World!' > README.md
~/example-repo|master$ git commit --amend -am 'Say Hello!'
[master d2b3e97] Say Hello!
 Date: Tue Feb 9 20:16:48 2016 -0800
 1 file changed, 1 insertion(+)

But we can do better! This README is weak. Bland.

Let's replace the contents of the file with something a bit more exciting. [fragment] "Hello World!". We'll add an exclamation point and capitalization and say it with gusto. (;

Then we'll commit with a message that reflects what we did: it also has an exclamation point and a capital "Hello".

Note the "--amend" option to "git commit": this tells git to augment the latest commit.

This is not an uncommon circumstance in real coding: you make a change, then commit it, and then realize you want to make it a little better -- remove some debug spew, fix a subtle bug, or refactor some hard-to-read code. "git commit amend" gives you a second chance.

~/example-repo|master$ git log -p
commit d2b3e97df640b0d2a863630af42d35ecb13573cd
Author: Marcel M. Cary <marcel@oreilly.com>
Date:   Tue Feb 9 20:16:48 2016 -0800

    Say Hello!

diff --git a/README.md b/README.md
index e69de29..980a0d5 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1 @@
+Hello World!

commit c714722b9a633a523a982ad5b88374a37683ce1d
Author: Marcel M. Cary <marcel@oreilly.com>
Date:   Tue Feb 9 20:05:58 2016 -0800

    Initial commit
...

Which Just Happened?

We created a new commit and destroyed the old one
We just changed our commit to sound better
We just created a new commit

How can you tell?

Can I still see the old commit?
How does Git know which commit I'm on?
What exactly does Git do when I commit??

Model for Commits

Let's create a visual model for commits.

Initial commit

git log --format=fuller c714722b

Commit ID:

c714722b9a633a523a982ad5b88374a37683ce1d

Author:

Marcel M. Cary <marcel@oreilly.com>

AuthorDate:

Tue Feb 9 20:05:58 2016 -0800

Committer:

Marcel M. Cary <marcel@oreilly.com>

CommitDate:

Tue Feb 9 20:05:58 2016 -0800

Message:

Initial commit

Second Commit

Commit ID:

016e54be

Message:

Say hi

Parent:

c714722b

→

Commit ID:

c714722b

Message:

Initial commit

Revised Commit

016e54be

Say hi

↓

d2b3e97d

Say Hello!

↓

c714722b

Initial commit

Reflog

~/example-repo|master$ git reflog master
d2b3e97 master@{0}: commit (amend): Say Hello!
016e54b master@{1}: commit: Say hi
c714722 master@{2}: commit (initial): Initial commit

Superseded Commit

~/example-repo|master$ git show 016e54b
commit 016e54bea7d5803346ed1b57b963fefe3ea22d9d
Author: Marcel M. Cary <marcel@oreilly.com>
Date:   Tue Feb 9 20:16:48 2016 -0800

    Say hi

diff --git a/README.md b/README.md
index e69de29..3b18e51 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1 @@
+hi

How does Git know which commit is "current"?

Branches

master

↓

016e54be

Say hi

↓

d2b3e97d

Say Hello!

↓

c714722b

Initial commit

Remember the Reflog?

~/example-repo|master$ git reflog master
d2b3e97 master@{0}: commit (amend): Say Hello!
016e54b master@{1}: commit: Say hi
c714722 master@{2}: commit (initial): Initial commit

What's the difference between the reflog and the log?

A branch's reflog is the history of changes to a branch, like an undo history
A branch's log is the list of commits reachable from that branch
If all you ever do is add commits to that branch, they show the same entries

Branch Log

master

↓

016e54be

Say hi

↓

d2b3e97d
Say Hello!

↓

c714722b
Initial commit

Warning

When collaborating, amending risks introducing redundant versions of a commit into your commit log if your collaborators don't also abandon the superseded commit.

(See "RECOVERING FROM UPSTREAM REBASE" in the git-rebase manual.)

Branching

~/example-repo|master$ git checkout -b fill-in-readme
Switched to a new branch 'fill-in-readme'
~/Projects/example-repo|fill-in-readme$ git branch
* fill-in-readme
  master

Add a Pointer

master

↓

fill-in-readme

↓

d2b3e97d

Say Hello!

↓

...

Branching is Fast

No matter how many files or commits in your repo,
branching just creates a pointer and updates HEAD.

Symbolic Refs

HEAD is a symbolic ref — a pointer to a branch

~/example-repo|fill-in-readme$ git symbolic-ref HEAD
refs/heads/fill-in-readme

Looks like a File!

refs/heads/fill-in-readme

~/example-repo$ find . | grep refs/heads/fill-in-readme
./.git/logs/refs/heads/fill-in-readme
./.git/refs/heads/fill-in-readme

~/example-repo$ cat .git/refs/heads/fill-in-readme
d2b3e97df640b0d2a863630af42d35ecb13573cd

Symbolic ref / Symlink

A Symoblic Ref used to be a Symolic Link, until Git supported Windows.

~/example-repo$ grep -r . refs/heads/fill-in-readme
./.git/HEAD:ref: refs/heads/fill-in-readme

Do some work...

~/example-repo|fill-in-readme$ cat > README.md <<EOF
> Example Repo
> ============
>
> Hello World!
> EOF
~/example-repo|fill-in-readme$ git commit -am 'Fill
 in the README'
[fill-in-readme 30842db] Fill in the README
 1 file changed, 3 insertions(+)

Branch Follows

master

↓

HEAD

↓

fill-in-readme

↓

30842dbd

Fill in the README

↓

d2b3e97d

Say Hello!

Merging

Makes master have all changes from both branches

~/example-repo|fill-in-readme$ git checkout master
Switched to branch 'master'
~/example-repo|master$ git merge fill-in-readme
Updating d2b3e97..30842db
Fast-forward
 README.md | 3 +++
 1 file changed, 3 insertions(+)

Checkout Master

master

↓

←

HEAD

↓

fill-in-readme

30842dbd

Fill in the README

↓

d2b3e97d

Say Hello!

Fast Forward Merge

←

fill-in-readme

HEAD

↓

master

↓

30842dbd

Fill in the README

↓

d2b3e97d

Say Hello!

Non-Fast Forward

Suppose instead that master already had additional commits.

Divergent Master

HEAD

→

↓

master

←

fill-in-readme

2c89b052

Add src

↓

30842dbd

Fill in the README

↓

d2b3e97d

Say Hello!

Merging

2545de7d

Merge branch 'fill-in-readme'

HEAD

→

↓

master

←

fill-in-readme

↓

2c89b052

Add src

↓

30842dbd

Fill in the README

↓

d2b3e97d

Say Hello!

ASCII Art

~/example-repo|master$ git log --oneline \
                         --decorate --all --graph
*   2545de7 (HEAD, master) Merge branch 'fill-in-readme'
|\  
| * 30842db (fill-in-readme) Fill in the README
* | 2c89b05 Add src
|/  
* d2b3e97 Say Hello!
* c714722 Initial commit

Commit Exclusion

$ git log --oneline master
2545de7 Merge branch 'fill-in-readme'
2c89b05 Add src
30842db Fill in the README
d2b3e97 Say Hello!
c714722 Initial commit
$ git log --oneline ^fill-in-readme master
2545de7 Merge branch 'fill-in-readme'
2c89b05 Add src
$ git log --oneline fill-in-readme..master
2545de7 Merge branch 'fill-in-readme'
2c89b05 Add src

Merge Conflicts

Conflicting Edits

HEAD

→

↓

master

←

fill-in-readme

2c89b052
Add contributors
to README

↓

30842dbd

                    Fill in the README

↓

d2b3e97d

Say Hello!

README.md
on master

+Contributors
+------------
+
 Hello World!

README.md
on fill-in-readme

+Example Repo
+============
+
 Hello World!

Automatic Merge Fail

~/example-repo|master$ git merge fill-in-readme
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Recorded preimage for 'README.md'
Automatic merge failed; fix conflicts and then
    commit the result.

Ahh! Merge failed what do I do?! [pause]

Remain calm. Git's output here is pretty informative.

First, [fragment] Git says it's trying to merge README.md for you.

Then, [fragment] Git tells you it got a merge conflict, [fragment] what kind of conflict, [fragment] and which file.

Then it tells you that it created a "preimage" version of the file [fragment].

This will help you, the human, decide how to sensibly resolve the conflict.

And finally [fragment], it tells you that you'll need to invoke "git commit" after resolving the conflicts.

[segue] There is one detail that it doesn't tell you here -- that's how to resolve conflicts.

Git Status

~/example-repo|master*+|MERGING$ git status
On branch master
You have unmerged paths.
  (fix conflicts and run "git commit")

Unmerged paths:
  (use "git add ..." to mark resolution)

  both modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

Conflict Markers

README.md

<<<<<<< HEAD
Contributors
------------
=======
Example Repo
============
>>>>>>> fill-in-readme
        
Hello World!

In README.md, we find special markers [fragment].

In the top section [fragment], we have the version from the branch we are on, labeled as HEAD, which is master.

In the bottom section [fragment], we have the version from the branch we asked to merge, which is "fill-in-branch".

Notice that the blank line [fragment] we added before "Hello World" on both branches is not part of the conflict. Git only flags conflicts when:

the change is to the same or adjacent lines, and...
the change is different on each branch

[fragment (removes highlight)]

So if we modified different sections of the same file, we would not get merge conflicts.

If we were working with code instead of text, would that guarantee our program wasn't broken? [pause] (No, but it's a good heuristic.)

Resolving Conflicts

README.md

Example Repo
============

<<<<<<< HEADContributors
------------
=======
Example Repo
============
>>>>>>> fill-in-readme
Hello World!

~/example-repo|master*+|MERGING$ git add README.md
~/example-repo|master+|MERGING$ git commit

[**Best to trigger fragments in main window to avoid jitter.**]

So let's resolve the conflict.

A best practice is to start with the other party's version and re-apply your changes to it. It's tempting to start with the code you understand better, but chances are good that you'll miss a nuance in the other person's code.

So in this case, we are working on the "fill-in-readme" branch, and someone else added contributors. We'll start with the contributors [fragment] [fragment].

Then we'll add back in our change to add the "Example Repo" heading.

As directected by "git status", we add the file [fragment] to mark it as resolved, ...

And we run "git commit" [fragment] to tell Git we're ready to record the merge.

[segue] And for your commit message...

Merge Commit Message

Merge branch 'fill-in-readme'

Conflicts:
    README.md
        Keep Contributors from master, and keep
        top-level heading from fill-in-readme.

Rebasing

Rebase my pull request??

Scenario

~/example-repo|fill-in-readme$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
~/example-repo|master=$ git pull --ff-only
From http://github.com/mcary/example-repo
   d2b3e97..2c89b05  master     -> origin/master
Updating d2b3e97..2c89b05
Fast-forward
 src/example.c | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 src/example.c
~/example-repo|master=$ git log --oneline d2b3e97..2c89b05
2c89b05 Add src
~/example-repo|master=$ git checkout -
Switched to branch 'fill-in-readme'

Instead of creating a merge commit in the last non-fast-forward merge example, let's rebase.

Suppose we got that "Add src" commit when pulling from an upstream repository.

We switch to master [fragment], ...

Then pull [fragment].

Note that I'm using the "--ff-only" option [fragment] to avoid accidentally creating a merge commit. ("git pull" would otherwise commit as needed, but we don't expect to need a commit because we've done our README work on a feature branch instead of master.)

Git reports how it updated the master branch with a commit range [fragment].

We can list those commits [fragment] by passing that same commit range [fragment] to "git log".

In this case we received exactly one commit, the "Add src" commit.

Now we'll switch back to the "fill-in-readme" branch [fragment]. [pause]

Rebase Command

~/example-repo|fill-in-readme$ git rebase master
First, rewinding head to replay your work on top of it...
Applying: Fill in the README

Rebase

→

master

HEAD

←

↓

fill-in-readme

2c89b052
Add src

↓

d892049

Fill in the README

↓

30842dbd

                      Fill in the README

↓

d2b3e97d
Say Hello!

Rebasing takes a stack of commits and re-stacks them onto a different base.

In this case, the stack is just one commit [fragment], on the "fill-in-readme" branch.

The base of our stack is on the "say hello" commit [fragment].

Our new base will be the "Add src" commit [fragment] on master.

When we rebase, Git recreates a new commit on the new base [fragment].

The new commit introduces the same change as the original, so it has the same patch.

But because the parent pointer differs, it must have a new hash and be a new commit. [pause]

Then, Git updates the fill-in-readme branch to point at the new commit.

As with amending, the old commit is still there, even though no branches point to it anymore.

And, as with merging:

The resulting branch incorporates all changes from the branch we were on and the branch we rebased onto...
And there could be conflicts.

Hopefully this picture clarifies what rebasing is, and how it got its name.

Note that there's also an option, "-i", to rebase, that turns on interactive rebase, which tends to be use for different purposes more akin to "git commit --amend". It's a great tool, and this presentation is a great foundation for learning more about it.

Recap

Immutability
Amending
Committing
Branches
HEAD
Merging: fast-forward or non
Resoling merge conflicts
Commit exclusion and ranges
Rebasing

Tonight we covered:

Immutability of commits: they never change but they can be superseded. The old one will still be available.
Amending is an example of this.
We covered committing, and how Git keeps track of the current commit with branches, and the current branch with HEAD.
We covered merging, both fast-forward and non-fast-forward...
... resolving merge conflicts, and when to expect conflicts.
We covered excluding commits from a particular branch, or listing a range of commits.
We covered rebasing, and what it means...
And we saw a visual model for what Git is doing with commits...
... and commands you can use to see what Git has done.

[pause]

Questions? [long pause]

Next time you're near the edge of your comfort zone with Git:

Try drawing out the commits and branches you have.
Use the commands we talked about to confirm your drawing.
Guess what your next command will do to that picture...
... and after you run it, check if that's what happened.

If you were right, good for you. If not, refine your model of how Git works and try again. Soon, you'll be able to anticipate what Git will do before you run the command.

Thanks for coming tonight, and happy versioning.

Dreaming in Git

Understanding Git well enough to anticipate its every move.

Marcel M. Cary

Slides: www.oak.homeunix.org/~marcel/nblug-git

Dreaming in Git

Dreaming?

Goals

About Me

Level

Git Commit IDs

Example Commit IDs

More Commit IDs

Commit ID, AKA:

Immutability

Committing

Another Commit

A Better Commit

Which Just Happened?

How can you tell?

Model for Commits

Initial commit

Second Commit

Revised Commit

Reflog

Superseded Commit

Branches

Remember the Reflog?

Branch Log

Warning

Branching

Add a Pointer

You are Here

Branching is Fast

Symbolic Refs

Looks like a File!

Symbolic ref / Symlink

Do some work...

Branch Follows

Merging

Checkout Master

Fast Forward Merge

Non-Fast Forward

Divergent Master

Merging

ASCII Art

Commit Exclusion

Merge Conflicts

Conflicting Edits

Automatic Merge Fail

Git Status

Conflict Markers

Resolving Conflicts

Merge Commit Message

Rebasing

Scenario

Rebase Command

Rebase

Recap

Dreaming in Git