branching.tex

\documentclass[slidestop]{beamer}

\input{../shared/shared.tex}

\author{Martijn Vermaat}
\title{\courseTitle}
\providecommand{\mySubTitle}{Working with branches in Git}
\providecommand{\myConference}{Git course}
\providecommand{\myGroup}{}
\providecommand{\myDepartment}{Department of Human Genetics}
\providecommand{\myCenter}{Center for Human and Clinical Genetics}

\usetheme{lumc}

\lstset{
  basicstyle=\ttfamily,
  language=none,
  frame=none,
  numbers=none,
  numbersep=0
}

\AtBeginSection[]
{
  \begin{frame}
    \frametitle{Table of contents}
    \tableofcontents[currentsection, subsectionstyle=hide/hide]
  \end{frame}
}

\begin{document}

% This disables the \pause command, handy in the editing phase.
%\renewcommand{\pause}{}

% Make the title page.
\makeTitleSlide{\includegraphics[width=3.5cm]{git_logo}}

\section{The Git commit graph}
\subsection{A linear history}
\begin{pframe}
  \includegraphics[width=10cm]{linear}
  \smallskip

  \begin{itemize}
    \item Every commit has a parent.
    \item {\em Committing} creates a new commit on top of the current one.
  \end{itemize}
\end{pframe}

\subsection{The default \lstinline{master} branch}
\begin{pframe}
  \includegraphics[width=10cm]{master}
  \smallskip

  \begin{itemize}
    \item A {\em branch} is a pointer to a commit.
    \item By default there is one branch: \lstinline{master}.
  \end{itemize}
\end{pframe}

\subsection{The current commit: \lstinline{HEAD}}
\begin{pframe}
  \begin{itemize}
    \item The current commit is called \lstinline{HEAD} (shown in blue here).
    \item \lstinline{HEAD} is actually a pointer to the current branch.
    \item (Or to the current commit if there is no current branch -- this is
      called detached head state.)
  \end{itemize}
  \bigskip

  \includegraphics[width=10cm]{head}
\end{pframe}

\subsection{Committing moves \lstinline{HEAD} and the current branch}
\begin{pframe}
  \begin{itemize}
    \item Committing moves the current branch to the new commit.
    \item Of course, \lstinline{HEAD} moves with it.
    \item (In detached head state, only \lstinline{HEAD} moves.)
  \end{itemize}
  \bigskip

  \includegraphics[width=10cm]{commit}
\end{pframe}

\subsection{A non-linear history}
\begin{pframe}
  \includegraphics[width=10cm]{nonlinear}
  \smallskip

  \begin{itemize}
    \item The commit graph can become non-linear.
    \item Usually by committing from the same commit twice.
  \end{itemize}
\end{pframe}

\subsection{Use branches to keep track of different code paths}
\begin{pframe}
  \begin{itemize}
    \item Branch names are easier to remember than commit hashes.
    \item Branch names make it clear what commits are about.
  \end{itemize}
  \bigskip

  \includegraphics[width=6cm]{branches}
\end{pframe}

\subsection{Different code paths may later join}
\begin{pframe}
  \begin{itemize}
    \item Commits from different branches can be brought together.
    \item We call this {\em merging}.
  \end{itemize}
  \bigskip

  \includegraphics[width=6cm]{merge}
\end{pframe}

\section{Inspecting the commit graph}
\subsection{An example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example}
  \smallskip

  \begin{itemize}
    \item Branches \lstinline{license} and \lstinline{interface} diverged from
      \lstinline{master}.
    \item Only \lstinline{license} has been merged back into
      \lstinline{master}.
    \item Current branch is \lstinline{master}.
  \end{itemize}
\end{pframe}

\subsection{Showing the current branch: \lstinline{git status}}
\begin{pframe}
  \begin{lstlisting}
$ git status
# On branch master
nothing to commit (working directory clean)
  \end{lstlisting}

  Remember: you cannot type \lstinline{git status} enough!
\end{pframe}

\subsection{Listing branches: \lstinline{git branch}}
\begin{pframe}
  \begin{lstlisting}
$ git branch
  interface
  license
* master
  \end{lstlisting}

  Three branches, current branch is \lstinline{master}.
  \pause

  \begin{lstlisting}
$ git branch -v
  interface 8fc25c1 Trivial Python interface
  license   0fbe3e3 Add MIT license
* master    c7f3bd9 Add .gitignore file
  \end{lstlisting}

  \lstinline{-v}: Shows the commit each branch points to.
\end{pframe}

\subsection{The commit log: \lstinline{git log}}
\begin{pframe}
  \begin{lstlisting}
$ git log --oneline --decorate
c7f3bd9 (HEAD, master) Add .gitignore file
4a44c4e Merge branch 'license'
64af1ee Add course teachers to README
0fbe3e3 (license) Add MIT license
d1c7fd7 Initial commit with README
  \end{lstlisting}

  \lstinline{--oneline}: Shows commit summary on one line.

  \lstinline{--decorate}: Adds branch information.
\end{pframe}

\subsection{The commit log as a graph: \lstinline{git log}}
\begin{pframe}
  \begin{lstlisting}
$ git log --oneline --decorate --graph --all
* 8fc25c1 (interface) Trivial Python interface
| * c7f3bd9 (HEAD, master) Add .gitignore file
|/
*   4a44c4e Merge branch 'license'
|\
| * 0fbe3e3 (license) Add MIT license
* | 64af1ee Add course teachers to README
|/
* d1c7fd7 Initial commit with README
  \end{lstlisting}

  \lstinline{--graph}: Shows the commit graph.

  \lstinline{--all}: Includes all branches instead of just the current.
\end{pframe}

\subsection{Switching to another branch: \lstinline{git checkout}}
\begin{pframe}
  \begin{lstlisting}
$ git checkout interface
Switched to branch 'interface'
  \end{lstlisting}

  This points \lstinline{HEAD} to the named branch and updates your working
  directory.
  \pause

  \begin{lstlisting}
$ git status
# On branch interface
nothing to commit (working directory clean)
  \end{lstlisting}
\end{pframe}

\section{Manipulating the commit graph}
\subsection{An example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example}
  \smallskip

  \begin{itemize}
    \item Branches \lstinline{license} and \lstinline{interface} diverged from
      \lstinline{master}.
    \item Only \lstinline{license} has been merged back into
      \lstinline{master}.
    \item Current branch is \lstinline{master}.
  \end{itemize}
\end{pframe}

\subsection{Creating a new branch: \lstinline{git branch}}
\begin{pframe}
  \begin{lstlisting}
$ git branch lib
  \end{lstlisting}

  Creates branch \lstinline{lib} at \lstinline{HEAD}.
  \pause

  \begin{lstlisting}
$ git checkout lib
Switched to branch 'lib'
  \end{lstlisting}
  \pause

  Or, for Git pro's, in one command:
  \begin{lstlisting}
$ git checkout -b lib
Switched to a new branch 'lib'
  \end{lstlisting}

  At this point, \lstinline{lib} is just a label to the same commit as
  \lstinline{master}.
\end{pframe}

\subsection{Our example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example-branched}
  \smallskip

  Created branch \lstinline{lib} from \lstinline{master}.
\end{pframe}

\subsection{Working on a branch: \lstinline{git commit}}
\begin{pframe}
  We can extend the \lstinline{lib} branch by adding commits.
  \begin{lstlisting}
$ echo 'VERSION=1' > testlib.py
$ git add testlib.py
$ git commit -m 'Add empty testlib'
  \end{lstlisting}
  \pause

  \begin{lstlisting}
$ git log --oneline --decorate --graph --all
* 251a51b (HEAD, lib) Add empty testlib
* c7f3bd9 (master) Add .gitignore file
| * 8fc25c1 (interface) Trivial Python interface
|/
*   4a44c4e Merge branch 'license'
|\
| * 0fbe3e3 (license) Add MIT license
...
  \end{lstlisting}
\end{pframe}

\subsection{Our example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example-committed}
  \smallskip

  Extended branch \lstinline{lib}.
\end{pframe}

\subsection{Fast forward merging: \lstinline{git merge}}
\begin{pframe}
  Let's merge our work on \lstinline{lib} back into \lstinline{master}.
  \begin{lstlisting}
$ git checkout master
Switched to branch 'master'
$ git merge lib
Updating c7f3bd9..251a51b
Fast-forward
 testlib.py |    1 +
 1 file changed, 1 insertion(+)
 create mode 100644 testlib.py
  \end{lstlisting}

  This merge was easy:
  \begin{itemize}
    \item \lstinline{lib} was directly upstream of \lstinline{master}.
    \item Git just moves \lstinline{HEAD} and \lstinline{master} to point to
      \lstinline{lib}.
    \item This is called a {\em fast forward merge}.
  \end{itemize}
\end{pframe}

\subsection{Our example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example-merged-ff}
  \smallskip

  Merged branch \lstinline{lib} into \lstinline{master} (fast forward).
\end{pframe}

\subsection{Three-way merging: \lstinline{git merge}}
\begin{pframe}
  Let's merge our work on \lstinline{interface} back into \lstinline{master}.
  \begin{lstlisting}
$ git merge interface
Merge made by the 'recursive' strategy.
 interface.py |    3 +++
 1 file changed, 3 insertions(+)
 create mode 100755 interface.py
  \end{lstlisting}
  \vspace{-0.25cm}

  This merge was harder:
  \begin{itemize}
    \item \lstinline{interface} and \lstinline{master} had diverged.
    \item Git determines changes in \lstinline{interface} and
      \lstinline{master} since their most recent common ancestor and creates a
      new commit from that.
    \item This is called a {\em recursive three-way merge} and the resulting
      merge a {\em merge commit}.
  \end{itemize}
\end{pframe}

\subsection{Our example repository}
\begin{pframe}
  \includegraphics[width=8cm]{example-merged}
  \smallskip

  Merged branch \lstinline{interface} into \lstinline{master}.
\end{pframe}

\subsection{Deleting branches: \lstinline{git branch}}
\begin{pframe}
  Old branches that have been merged can be deleted.
  \begin{lstlisting}
$ git branch -d interface
Deleted branch interface (was 8fc25c1).
  \end{lstlisting}

  \begin{lstlisting}
$ git branch -d lib license
Deleted branch lib (was 251a51b).
Deleted branch license (was 0fbe3e3).
  \end{lstlisting}

  No history is lost, just labels removed.
\end{pframe}

\section{Basic merge conflicts}
\subsection{Merge conflicts}
\begin{pframe}
  Git is pretty good at merging:
  \begin{itemize}
    \item The changes might have been in different files.
    \item Or in different parts of the same file.
    \item Git tries to figure out a sensible result.
  \end{itemize}
  \bigskip
  \pause

  Sometimes this is not possible:
  \begin{itemize}
    \item The changes might be incompatible.
    \item When we try \lstinline{git merge}, Git gives up.
    \item This situation is called a {\em merge conflict}.
  \end{itemize}
\end{pframe}

\subsection{Setting the stage (1/3)}
\begin{pframe}
  \begin{lstlisting}
$ git log --oneline --decorate --graph --all
* 9d2ad27 (HEAD, master) State character preference
| * 374ab60 (simpsons) State character preference
|/
* 4012f4f Initial commit
  \end{lstlisting}

  We'd like to merge branch \lstinline{simpsons} into \lstinline{master}.
\end{pframe}

\subsection{Setting the stage (2/3)}
\begin{pframe}
  The last commit on \lstinline{master}:
  \begin{lstlisting}
$ git show --oneline
9d2ad27 State character preference
diff --git a/README b/README
index de15194..ef40359 100644
--- a/README
+++ b/README
@@ -1,2 +1,4 @@
 Facts about television series
 =============================
+
+My favorite character is Eric Cartman.
  \end{lstlisting}
\end{pframe}

\subsection{Setting the stage (3/3)}
\begin{pframe}
  The last commit on \lstinline{simpsons}:
  \begin{lstlisting}
$ git show --oneline simpsons
374ab60 State character preference
diff --git a/README b/README
index de15194..9dd729b 100644
--- a/README
+++ b/README
@@ -1,2 +1,4 @@
 Facts about television series
 =============================
+
+My favorite character is Homer Simpson.
  \end{lstlisting}
\end{pframe}

\subsection{Creating a merge conflict}
\begin{pframe}
  \vspace{-0.5cm}
  \begin{lstlisting}
$ git merge simpsons
Auto-merging README
CONFLICT (content): Merge conflict in README
Automatic merge failed; fix conflicts and then
commit the result.

$ git status
# On branch master
# Unmerged paths:
#   (use "git add/rm <file>.." as appropriate to
#    mark resolution)
#
#              both modified:      README
#
no changes added to commit (use "git add" and/or
"git commit -a")
  \end{lstlisting}
\end{pframe}

\subsection{Resolving a merge conflict (1/2)}
\begin{pframe}
  \begin{lstlisting}
$ cat README
Facts about television series
=============================

<<<<<<< HEAD
My favorite character is Eric Cartman.
=======
My favorite character is Homer Simpson.
>>>>>>> simpsons
  \end{lstlisting}

  What we had is under \lstinline{HEAD}, what \lstinline{simpsons} had is above
  \lstinline{simpsons}.
  \pause

  \begin{lstlisting}
$ emacs README
  \end{lstlisting}
\end{pframe}

\subsection{Resolving a merge conflict (2/2)}
\begin{pframe}
  We resolve the conflict by hand.
  \begin{lstlisting}
$ cat README
Facts about television series
=============================

My favorite characters are Eric Cartman
and Homer Simpson.
  \end{lstlisting}
  \pause

  And can now finish the merge commit.
  \begin{lstlisting}
$ git add README
$ git commit
[master 1e496cb] Merge branch 'simpsons'
  \end{lstlisting}
\end{pframe}

\subsection{Aborting a merge}
\begin{pframe}
  If you don't feel like resolving the merge conflict, you can go back with
  \lstinline{git merge --abort}.
  \begin{lstlisting}
$ git merge simpsons
Auto-merging README
CONFLICT (content): Merge conflict in README
Automatic merge failed; fix conflicts and then
commit the result.
  \end{lstlisting}

  \begin{lstlisting}
$ git merge --abort
  \end{lstlisting}

  \begin{lstlisting}
$ git status
# On branch master
nothing to commit (working directory clean)
  \end{lstlisting}
\end{pframe}

\subsection{Resolving conflicts with \lstinline{git mergetool}}
\begin{pframe}
  We can also use graphical merge tools such as {\em Meld}.
  \begin{lstlisting}
$ git mergetool
merge tool candidates: meld opendiff kdiff3 ...
Merging:
README

Normal merge conflict for 'README':
  {local}: modified file
  {remote}: modified file
Hit return to start merge resolution tool (meld):
  \end{lstlisting}
\end{pframe}

\subsection{Meld example}
\begin{pframe}
  \includegraphics[width=11cm]{meld}
  \smallskip

  Tools like Meld provide an editable three-way diff.
\end{pframe}

\makeAcknowledgementsSlide{
  \begin{tabular}{l}
    \acknowledgements
  \end{tabular}
  \bigskip

  \hfill\includegraphics[width=3.5cm]{git_logo}

  \begin{tabular}{l}
    \small\url{http://git-scm.com/book}\\
    \small\url{https://www.atlassian.com/git}
  \end{tabular}
}

\end{document}