Wrote about distributed versioning

git-tutorial.tex

@@ -24,10 +24,40 @@
 \section{Git Tools}
 \label{sec:tools}
 
+Depending on which OS you use, there are some different choices of git
+clients available. For the purpose of this tutorial we will only
+consider running git from a terminal shell, but you can of course
+install one of the available gui clients and transform the information
+given in the tutorial to that gui client.
 
+\subsubsection*{Linux}
+\label{linux}
+Git packages are included in at least all major Linux
+distributions. Just use your package manager of choice to find and
+install git.
 
-\section{Hands-On Excercise}
+\subsubsection*{MacOSX}
+\label{sec:macosx}
+Get your git client from \verb|http://git-scm.com/download/mac|
+
+\subsubsection*{Windows}
+\label{sec:windows}
+Get your Windows git client from \verb|http://git-scm.com/download/win|.
+
+
+\section{Hands-On Example}
 \label{sec:handson}
+In this section we will walk through the basic git operations using
+this very tutorial as an example project. We will first show the
+workflow for a standalone repository, typically what you would have
+for versioning your own small projects. Then we will show what happens
+when we want to work in a distributed context, cooperating with other
+people.
+
+\subsection{Standalone Repository}
+\label{sec:standalone}
+The simplest use case is that of one single developer, one local
+repository. 
 
 \begin{figure}[h!]
   \centering
@@ -57,10 +87,10 @@ git config --global --get user.name
 Let us say we have a directory with files that we want to version
 control using git.
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ pwd
+andersn@stodola: pwd
 /local/home/andersn/work/computers/git-tutorial
 
-andersn@stodola:../computers/git-tutorial$ ls
+andersn@stodola: ls
 git-tutorial.aux  git-tutorial.pdf    git-tutorial.tex   
 lifecycle.png  git-tutorial.log  #git-tutorial.tex#  
 git-tutorial.tex~  
@@ -68,14 +98,14 @@ git-tutorial.tex~
 
 We can now create a new repository in this directory
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ git init
+andersn@stodola: git init
 \end{lstlisting}
 
 The result of this command is a new subdirectory called \verb|.git|
 that contains the actual git repository. If you look into it you will
 see various files and subdirectories.
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ ls .git/
+andersn@stodola: ls .git/
 branches  config  description  HEAD  hooks  info  objects  refs
 \end{lstlisting}
 Some of these are human readable while others are not. If you are
@@ -94,7 +124,7 @@ from the \LaTeX source. We will take care of that when it is time to
 add files to the repository.
 
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ git status 
+andersn@stodola: git status 
 # On branch master
 #
 # Initial commit
@@ -112,8 +142,8 @@ nothing added to commit but untracked files present (use "git add" to track)
 \end{lstlisting}
 
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ git add lifecycle.png git-tutorial.tex
-andersn@stodola:../computers/git-tutorial$ git status 
+andersn@stodola: git add lifecycle.png git-tutorial.tex
+andersn@stodola: git status 
 # On branch master
 #
 # Initial commit
@@ -134,17 +164,27 @@ andersn@stodola:../computers/git-tutorial$ git status
 #       git-tutorial.tex~
 \end{lstlisting}
 
+\subsubsection*{Using gitignore}
+\label{sec:gitignore}
 
+As you have just seen \verb|git status| lists a number of untracked
+files that we are not interested in versioning, and as the number of
+unversioned files grow they tend to clutter the view. By creating a
+file called \verb|.gitignore| in which we list filenames and name
+pattern that we do not want git to consider the view becomes much more
+uncluttered.
 \begin{lstlisting}
 *.aux
 *.log
 *~
 git-tutorial.pdf
 \end{lstlisting}
+Adding \verb|.gitignore| to our repository and running
+\verb|git status| again we see that it now looks much better.
 
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ git add .gitignore
-andersn@stodola:../computers/git-tutorial$ git status 
+andersn@stodola: git add .gitignore
+andersn@stodola: git status 
 # On branch master
 #
 # Initial commit
@@ -155,27 +195,96 @@ andersn@stodola:../computers/git-tutorial$ git status
 #       new file:   .gitignore
 #       new file:   git-tutorial.tex
 #       new file:   lifecycle.png
-#
-# Changes not staged for commit:
-#   (use "git add <file>..." to update what will be committed)
-#   (use "git checkout -- <file>..." to discard changes in working directory)
-#
-#       modified:   git-tutorial.tex
-#
 \end{lstlisting}
 
-
+\subsubsection*{Commit}
+\label{sec:commit}
+If we are satisfied with the output of \verb|git status| it is now
+time to perform a commit operation and create an initial revision of
+the project in the repository. The text within double quote marks is a
+revision comment. Good revision comments, that is, meaningful but
+terse, are important as they can be of good use when you or someone
+else at some time look back into the revision history and try to find
+out what happened and when.
 \begin{lstlisting}
-andersn@stodola:../computers/git-tutorial$ git commit -am"Initial commit"
+andersn@stodola: git commit -am"Initial commit"
 [master (root-commit) c6d834c] Initial commit
  3 files changed, 146 insertions(+)
  create mode 100644 .gitignore
  create mode 100644 git-tutorial.tex
  create mode 100644 lifecycle.png
 
-andersn@stodola:../computers/git-tutorial$ git status 
+andersn@stodola: git status 
 # On branch master
 nothing to commit (working directory clean)
 \end{lstlisting}
 
+After performing the first commit, work goes on. New files are added
+and existing files are edited. Whenever it feels motivated, add new
+files to the repository and perform new commits with meaningful commit
+messages.
+
+\subsection{Distributed Work}
+\label{sec:distributed}
+
+With the distributed model of git (and bzr,hg,darcs,...) each user has
+his own repository, in contrast to the centralized model of subversion
+and cvs where there is only one central repository where the version
+data of a project may be stored. With multiple repository copies we
+need operations to keep different repositories synchronized.
+
+In this tutorial we will keep to the model with one ``master''
+repository with which all users synchronize. However, this model is by
+no means enforced by the git tool. Users could just as well
+synchronized directly with their fellow users' repositories, but
+practical difficulties with allowing access to all repositories as
+well as the higher level of discipline needed to keep all repositories
+synchronized can make this flat hierarchy model cumbersome for all but
+very experienced users.
+
+\subsubsection*{Clone}
+\label{clone}
+To create a local copy of a remote repository we use \verb|git clone|
+\begin{lstlisting}
+andersn@fiol: git clone andersn@stodola.control.lth.se:work/computers/git-tutorial
+Cloning into 'git-tutorial'...
+remote: Counting objects: 11, done.
+remote: Compressing objects: 100% (10/10), done.
+remote: Total 11 (delta 2), reused 0 (delta 0)
+Receiving objects: 100% (11/11), 46.64 KiB, done.
+Resolving deltas: 100% (2/2), done.
+\end{lstlisting}
+
+\subsubsection*{Pull}
+\label{pull}
+When we want to check for, and merge into our repository copy, changes
+made to the master repository, we can use \verb|git pull|
+\begin{lstlisting}
+andersn@fiol: git pull
+Already up-to-date.
+\end{lstlisting}
+In this case it was not particularly interesting since the local clone
+was already up to date with the remote master.
+
+\subsubsection*{Push}
+\label{push}
+
+\subsubsection*{Merge}
+\label{merge}
+
+
+
+
+
+\section{Further Reading}
+\label{sec:furtherreading}
+
+\begin{itemize}
+\item A cheat sheet is good to print out and have at hand next to your keyboard: \\
+  \verb|http://git-scm.com/documentation|
+  or\\
+  \verb|http://www.git-tower.com/files/cheatsheet/Git_Cheat_Sheet_grey.pdf|
+\item The \emph{Pro Git} book is available online: \verb|http://git-scm.com/book|
+\end{itemize}
+
 \end{document}