path: root/git.tex

% vim: set tabstop=4:
% vim: set shiftwidth=4:
% vim: set expandtab:

\RHpresentationHead{
    \documentclass[pdftex,unicode,xcolor=table,slidestop,compress]{beamer}
}

\RHarticleHead{
    % This does not work, because of colors, \insertauthor, etc.
    \documentclass[a4paper,12pt,pdftex,unicode]{article}
    \usepackage[envcountsect]{beamerarticle}
}

%\usepackage{pgfpages}
\usetheme{Git}
\setbeamertemplate{navigation symbols}{}
\setbeamercovered{transparent=5}

\usepackage[utf8]{inputenc}
%\usepackage[lang]{babel}
\usepackage{setspace,amsfonts,calc,upquote,hyperref,floatflt,graphicx}
\usepackage[table]{xcolor}
\usepackage{colortbl}
\usepackage[absolute,overlay]{textpos}

\defverb\verbemail|Random Hacker <rand@hacker.com>|
\defverb\kzakemail|<kzak@redhat.com>|

% presentation title/author/etc.
\title{Git}
\subtitle{(Why not CVS? ... because Git.)}
\author{Karel Zak\\
\kzakemail}
\date{}

% fancy section/part pages?
%\fancySectionOpens
%\fancyPartOpens


\begin{document}

\begin{rhbg}
\begin{frame}
    \titlepage
\end{frame}
\end{rhbg}

\begin{frame}[plain]
\vspace*{30ex}
Copyright \copyright{}\ \ \the\year\ \ Karel Zak.\\
\vspace*{1ex}
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.
\end{frame}

% table of contents
\begin{frame}
    \frametitle{Agenda}
    \tableofcontents
\end{frame}

\section{Intro}

\begin{frame}
    \frametitle{What is Git?}
    \begin{quote}
    ``I'm an egotistical bastard, and I name all my projects after myself. First 'Linux', now 'git'.'' (Linus Torvalds)
    \end{quote}
    \vspace*{4ex}
    \begin{itemize}
        \item fast distributed revision control system
        \item unusually rich command set
        \item provides both high-level operations and full access to internals
        \item originally created by Linus Torvalds for kernel development
        \item design was inspired by BitKeeper and Monotone
        \item GNU General Public License, version 2
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{Basic features}
    \begin{itemize}
        \item distributed development model
        \item support for non-linear development (branching and merging)
        \item ready for large projects (very good performance)
        \item repositories can be easily published (git://, ssh://, http://, rsync://, ...)
        \item cryptographic authentication of history (GPG-signed tags)
        \item internally objects are addressed by content (SHA-1) -- no filenames
        \item local branches are local only (off-line work)
    \end{itemize}
\end{frame}

\subsection{Development model}

\begin{frame}
    \frametitle{Centralized model}
    \resizebox{7cm}{4cm}{\includegraphics{git-centralized.png}}
    \begin{itemize}
        \item extra policy for write access
        \item SCM is not development tool, but source code archive only
        \item every change has impact to all developers
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{Distributed model}
    \resizebox{8cm}{5cm}{\includegraphics{git-distributed.png}}
    \begin{itemize}
        \item maintainer has full control over primary (his) repository
        \item support for non-linear development
        \item repositories can be easily published (git://, ssh://, http://, ...)
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{Git improves your work manners and habits}
    \begin{itemize}
        \item
            branching and merging is cheap

        \begin{itemize}
            \item you can prototyping
            \item you can collaborate with others developers on incomplete and unstable stuff
            \item you can easily (e.g. every day) rebase your changes to new upstream code
            \item often merging (rebase) minimize conflicts between your patches and upstream
        \end{itemize}

        \item
            small patch is the best patch (patch per feature/change)

        \begin{itemize}
            \item reviewers hate huge patches
            \item well separated feature or change is easy to revert
        \end{itemize}
    \end{itemize}
\end{frame}

\section{Implementation}


\begin{frame}
    \frametitle{Internal objects}
    \begin{block}{}
       All objects are content-addressable by SHA-1.
    \end{block}

    \begin{description}[references]
        \item[commit] refers to ``tree'' and ``parent`` (connection into the project history)
        \item[tree] represents the state of a single directory (list of ``blob'' objects and subtrees)
        \item[blob] contains file data without any other structure
        \item[references] are human readable names for commits; for example tags, see files under .git/refs/heads/.
    \end{description}
\end{frame}

\begin{frame}
    \frametitle{Internal objects}
    \resizebox{8cm}{4cm}{\includegraphics{git-objdb.png}}
    \begin{description}[commit]
        \item[commit] -- connection between ``tree'' and ``parent``
        \item[tree] -- state of a single directory
        \item[blob] -- contain file data
    \end{description}
\end{frame}


\begin{frame}[containsverbatim]
    \frametitle{Trust}
    \begin{itemize}
        \item everything is content-addressed and based on SHA-1
        \item two trees are same when HEAD SHA-1 are same
        \item tags could be GPG-signed
    \end{itemize}

    \begin{exampleblock}{}
    \scriptsize{
    	\begin{verbatim}
 $ git tag -v v2.13
 object 49ef7acdf77066ed05a6c828c261d332c4f54644
 type commit
 tag v2.13
 tagger Karel Zak <kzak@redhat.com> Tue Aug 28 01:01:35 2007 +0200

 stable release v2.13
 gpg: Signature made Tue 28 Aug 2007 01:01:35 AM CEST using DSA key ID DC06D885
 gpg: Good signature from "Karel Zak <kzak@redhat.com>" \end{verbatim}
    }
    \end{exampleblock}
\end{frame}


\subsection{Naming revisions}

\begin{frame}[containsverbatim]
    \frametitle{Object reference}
    \defverb\ngrandparent|commit~n|
    \defverb\nparent|commit^n|
    \begin{description}[ref@\{date\}]
        \item[SHA-1] 40-hexdigit object name
        \item[tag] human readable name for commit
        \item[\nparent] N-th parent
        \item[\ngrandparent] N-th generation grand-parent of the named commit object, following only the first parent.
        \item[ref@\{date\}] specify the value of the ref at a prior point in time
        \item[:/text] commit whose commit message starts with the specified text
        \item[HEAD] refers to the head of the current branch
    \end{description}

    \begin{exampleblock}{}
        \begin{verbatim} rev~3   =    rev^^^    =   rev^1^1^1 \end{verbatim}
    \end{exampleblock}

    \begin{exampleblock}{}
        \begin{verbatim} $ git reset HEAD^ \end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}[containsverbatim]
    \frametitle{Ranges}
    \begin{description}[r1...r2]
        \item[r1..r2] commits reachable from r2 but exclude the ones reachable from r1
        \item[r1...r2] set of commits that are reachable from either one of r1 or r2 but not from both
    \end{description}

    \begin{exampleblock}{}
        \begin{verbatim} $ git log v2.13..v2.14 \end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}
    \frametitle{"tree-ish"}
    Lots of commands take a tree as an argument. A tree can be referred to in many different ways, by:

    \begin{itemize}
        \item name for that tree
        \item name of a commit that refers to the tree
        \item name of a branch whose head refers to that tree
    \end{itemize}
\end{frame}

\section{Repositories}

\begin{frame}[containsverbatim]
    \frametitle{Create a repository}

    \begin{itemize}
        \item create a new repository
            \begin{exampleblock}{}
                \small{
                \begin{verbatim}
 $ mkdir project
 $ cd project
 $ git init \end{verbatim}
            }
             \end{exampleblock}
        \item clone an existing remote repository ("origin" repository)
            \begin{exampleblock}{}
                \small{ \begin{verbatim} $ git clone http://foo.com/project \end{verbatim} }
            \end{exampleblock}
        \item add a next remote repository
            \begin{exampleblock}{}
                \small{
                \begin{verbatim} $ git config remote.bar.url git://bar.com/project
 $ git config remote.bar.fetch master:refs/remotes/bar/master
 $ git fetch bar \end{verbatim}
                }
            \end{exampleblock}
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{Visualisation}
    \includegraphics[width=0.9\textwidth]{gitk.png}
\end{frame}

\section{Branches}

\begin{frame}[containsverbatim]
    \frametitle{Branches}
    \begin{exampleblock}{}
        \begin{verbatim}
         o--o--o   <-- Branch A
        /
 o--o--o--o--o     <-- master
        \
         o--o--o   <-- Branch B  \end{verbatim}
    \end{exampleblock}

    \begin{description}[branch head]
        \item[branch] is line of development
        \item[branch head] is a reference to the most recent commit on a branch
    \end{description}
    \vspace*{1ex}
    Branches, remote-tracking branches, and tags are all references to commits.

\end{frame}

\begin{frame}[containsverbatim]
    \frametitle{Manipulating branches}
    \defverb\branchname|<branch>|
    \begin{itemize}
        \item \structure{git branch} lists, creates, or deletes branches
        \item \structure{git checkout \branchname} makes the current branch \branchname, updating the working directory
        \item \structure{git checkout -b \branchname} creates a new branch \branchname check it out
        \item \structure{git show-branch} shows branches and their commits
        \item \structure{git diff \branchname..\branchname} diffs between branches
    \end{itemize}
\end{frame}

\begin{frame}[containsverbatim]
    \frametitle{Rebase branch}
    \begin{exampleblock}{Before}
        \begin{verbatim}
                 A---B---C topic
                /
           D---E---F---G master \end{verbatim}
    \end{exampleblock}

    \begin{exampleblock}{Command}
        \begin{verbatim} $ git rebase master topic \end{verbatim}
    \end{exampleblock}

    \begin{exampleblock}{After}
        \begin{verbatim}
                         A---B---C topic
                        /
           D---E---F---G master \end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}[containsverbatim]
    \frametitle{Edit 2nd commit from the top}
    \begin{enumerate}
        \item create a temporary branch (rewind to the commit in question):
            \begin{exampleblock}{}
        \begin{verbatim}    $ git checkout -f -b tmp HEAD~2 \end{verbatim}
            \end{exampleblock}

        \item reset old changes and redo the commit
            \begin{exampleblock}{}
             \begin{verbatim}
    $ git reset HEAD^
    $ vim foo.c
    $ git commit -a -c ORIG_HEAD \end{verbatim}
            \end{exampleblock}

        \item replay the later changes to the master:
            \begin{exampleblock}{}
                \begin{verbatim}    $ git rebase --onto tmp master~2 master \end{verbatim}
            \end{exampleblock}

        \item clean up (delete) the temporary branch
            \begin{exampleblock}{}
                \begin{verbatim}    $ git branch -D tmp \end{verbatim}
            \end{exampleblock}
    \end{enumerate}
\end{frame}

\section{Real life with Git}

\begin{frame}
    \frametitle{Changes in project history}
    \begin{itemize}
        \item the latest patches -- (\texttt{git reset}) reset current HEAD

        \item deep in project history
            \begin{itemize}
                \item rebease
                    \begin{itemize}
                        \item impact to all rebased commits (new SHA-1)
                        \item impact to all tags

                        \item useless for publicly pushed changes
                    \end{itemize}
                \item patch revert (\texttt{git revert})
                    \begin{itemize}
                        \item zero impact to project history
                    \end{itemize}
            \end{itemize}
    \end{itemize}
\end{frame}

\begin{frame}
    \frametitle{Send a patch}
    Basic rules:
    \begin{itemize}
        \item one patch per e-mail
        \item don't use stupid e-mail clients (e.g. Outlook)
        \item (don't use attachments)
        \item export patches by \texttt{git format-patch}
        \item send patches by \texttt{git send-email}

        \item well formatted patch is possible to apply by \texttt{git am}

        \item don't forget to keep correct authorship (e.g when you are not author of the patch)

        \item use commit messages -- a patch without comment is incomplete crap
    \end{itemize}
\end{frame}

\section{Commands}

\begin{frame}[containsverbatim]
    \frametitle{Syntax}
    \begin{itemize}
        \item \texttt{git <commandname> [options]}
        \item \texttt{git-<commandname> [options]}
    \end{itemize}

    \begin{exampleblock}{High level}
    	\begin{verbatim} $ git commit -a -s -m "cool change" \end{verbatim}
    \end{exampleblock}
    \begin{exampleblock}{Low level}
    	\begin{verbatim} $ git rev-list --pretty=oneline v2.13.. \end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}
    \frametitle{Basic commands}
    \begin{description}[git format-path]
        \item[git init] creates en empty repository at \texttt{./.git}
        \item[git add] adds file contents to the next commit
        \item[git reset] resets current HEAD
        \item[git status] shows the working tree status
        \item[git commit] records changes to the repository
        \item[git log] shows commit log
        \item[git show] shows commit (or another object)
        \item[git format-path] exports a change
        \item[git send-email] sends patch(s)
        \item[git am] applies a series of patches from a mailbox
    \end{description}
\end{frame}

\subsection{Commits and patches}

\begin{frame}[containsverbatim]
    \frametitle{Commit changes}
    \begin{block}{}
        \begin{verbatim} git commit [options] [<file>] \end{verbatim}
    \end{block}
    \begin{itemize}
        \item \structure{-a} commits all modified or deleted files
        \item \structure{-s} adds Signed-off-by line at the end of the commit message

        \item \structure{-c ORIG\_HEAD} reuses a commit message (e.g. from previously reseted commit)
        \item \structure{--author "\verbemail"} overrides the author name

        \item starts \structure{\$EDITOR} for commit message (or \texttt{-m "<commit message>"})
    \end{itemize}

    \begin{exampleblock}{}
    	\begin{verbatim} $ git commit -a -s\end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}[containsverbatim]
     \frametitle{Export patches to files}
     \begin{block}{}
        \begin{verbatim} git format-patch [options] <since|range> \end{verbatim}
     \end{block}
     \begin{itemize}
        \item creates one file per patch
        \item created patches are usable by \structure{git am}
    \end{itemize}
    \begin{exampleblock}{}
    \scriptsize{
        \begin{verbatim}
$ git format-patch -o ~/ HEAD~5
/home/kzak/0001-setterm-opened-file-leaving-unclosed.patch
/home/kzak/0002-sfdisk-opened-files-leaving-unclosed.patch
/home/kzak/0003-blockdev-fix-opened-file-leaving-unclosed.patch
/home/kzak/0004-tailf-opened-file-leaving-unclosed.patch
/home/kzak/0005-tests-use-losetup-s.patch \end{verbatim}
    }
    \end{exampleblock}
\end{frame}

\begin{frame}
    \frametitle{Patch description}
	\includegraphics[width=0.9\textwidth]{git-patch.png}
\end{frame}

\begin{frame}[containsverbatim]
     \frametitle{Send patches by e-mail}
     \begin{block}{}
         \begin{verbatim} git send-email [options] <file|dir> \end{verbatim}
     \end{block}
     Takes the patches given on the command line and emails them out.\\
     \begin{itemize}
        \item no attachments
        \item no broken patch format
        \item correct subject line
     \end{itemize}
     \begin{exampleblock}{}
        \begin{verbatim}
$ git send-email --to "God <father@heaven.com>" \
                 ~/0001-make-this-world-better.patch \end{verbatim}
    \end{exampleblock}
\end{frame}

\begin{frame}[containsverbatim]
    \frametitle{Browsing changes}
    \begin{description}[git whatchanged]
        \item[git log] shows commit logs
        \item[git show] shows one or more objects (blobs, trees, tags and commits)
        \item[git blame] shows what revision and author last modified each line of a file
        \item[git whatchanged] shows logs with difference each commit introduces
    \end{description}
    \begin{exampleblock}{}
    \begin{scriptsize}
        \begin{verbatim}
$ git log v2.5..                     # commits since v2.5
$ git log test..master               # commits reachable from master
                                     #         but not test
$ git log --since="2 weeks ago"      # commits from the last 2 weeks
$ git log Makefile                   # commits which modify Makefile
$ git log --pretty=format:"%h [%an]" # commit log in format
                                     #        "sha-1 [Author Name]"
$ git blame -L 10,15 foo.c           # who modified code between lines
                                       10 and 15
$ git show c1a47c171b                # shows selecte object (commit) \end{verbatim}
    \end{scriptsize}
    \end{exampleblock}
\end{frame}

\section{Misc}

\begin{frame}
    \frametitle{Gitweb}
	\includegraphics[width=0.9\textwidth]{gitweb.png}
\end{frame}

\begin{frame}
  \frametitle{References}
  \begin{thebibliography}{Git User's Manua}
  \bibitem[Git User's Manual]{GitUserManual}
    Git User's Manual
    \newblock {\url{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}}
  \bibitem[Git Tutorial]{GitTutorial}
    A tutorial introduction to git
    \newblock {\url{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}}
  \bibitem[The perfect patch]{PerfectPatch}
    The perfect patch
    \newblock {\url{http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt}}
  \end{thebibliography}
\end{frame}

\begin{frame}
    \hfill
    \begin{center}
    {\Huge The end.}
    \par\vspace*{0.5cm}
    Thanks for listening.
    \end{center}
    \hfill
\end{frame}

\end{document}