\documentclass[xcolor=dvipsnames]{beamer}

\setbeamertemplate{navigation symbols}{}
\useoutertheme{infolines}
\usecolortheme[named=violet]{structure}
\setbeamertemplate{items}[circle]

\usepackage{graphicx}
\usepackage{bera}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{xspace}
\usepackage{hyperref}

\input{lststyles.tex}

\newcommand{\git}{\texttt{git}\xspace}


\author[Brett Viren]{Brett Viren}
\institute[BNL]
{
  Physics Department
  
  \includegraphics[height=1.5cm]{bnl-logo}
}
\title[g4lbne/git/worch]{G4LBNE Migration from CVS to \git \\ and some other stuff}
\date[2014/2/13]{G4LBNE phone meeting 2014/2/13}

\begin{document}

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


\begin{frame}
  \frametitle{Outline}
  \tableofcontents
\end{frame}

\section{The Migration}

\begin{frame}[fragile]
  \frametitle{Overview of Migration}

  \begin{enumerate}
  \item Backed up old CVS
  \item Run \texttt{cvs2git} following \href{https://cdcvs.fnal.gov/redmine/projects/fermi-redmine/wiki/Using_cvs2git}{this Fermilab Redmine page} but had to run it on my workstation as it failed on the Fermilab server.
  \item Create initial \git repository for \texttt{cvs2git} data
  \item Tar it up, copy it to server and unpack
  \end{enumerate}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Cruft}
  \begin{lstlisting}[language=sh]
$ ls -l /cvs/projects/lbne-beamsim/
drwxrwsr-x. 3 p-lbne-beamsim redmine 6144 Feb  7 12:02 CVSROOT
drwxrwsr-x. 5 p-lbne-beamsim redmine 4096 Sep 13 10:04 g4lbne
drwxrwsr-x. 7 p-lbne-beamsim redmine 2048 Feb 11 10:24 g4lbne.git
drwxrwsr-x. 6 p-lbne-beamsim redmine 4096 Apr 23  2013 g4numi
drwxrwsr-x. 4 p-lbne-beamsim redmine 2048 Feb 11 09:30 lbne-beamsim

$ ls -l /cvs/projects/lbne-beamsim/lbne-beamsim/
drwxrwsr-x. 13 p-lbne-beamsim redmine 4096 Feb 11 09:30 g4lbne
drwxrwsr-x.  7 p-lbne-beamsim redmine 4096 Feb 11 09:30 g4numi
  \end{lstlisting}
  \begin{itemize}
  \item  Multiple copies of \texttt{g4lbne} and \texttt{g4numi} CVS directories +\texttt{CVSROOT}
  \item \texttt{g4lbne.git} is made from \texttt{lbne-beamsim/g4lbne/}
  \end{itemize}
  Any reason to keep the CVS cruft around? 
\end{frame}

\begin{frame}[fragile]
  \frametitle{Redmine Changes}
  Modified Redmine w.r.t. repositories
  \begin{itemize}
  \item "Deleted" CVS (actual repository still there)
  \item Added the new \git as primary repository
  \item Added a secondar \texttt{worch} repository
  \end{itemize}

  \vspace{2mm}
  Still browse at usual location:
  \footnotesize
  \begin{center}
    \url{https://cdcvs.fnal.gov/redmine/projects/lbne-beamsim/repository}
  \end{center}
\end{frame}

\section{Basic \git}

\begin{frame}
  \tableofcontents[currentsection]
\end{frame}

\begin{frame}
  \frametitle{The parts of \git}
  CVS has just a working directory and a remote repository, \git has these parts:
  \begin{description}
  \item[working directory] holds the files you edit, compile, etc.
  \item[index] a staging area maintained by \git for preparing commits
  \item[repository] the \git file system holding commits, branches and tags
    \begin{itemize}
    \item a \textit{local} repository is the one associated with your working directory
    \item a \textit{remote} repository is some other one but otherwise is not special
    \end{itemize}
  \end{description}
  \begin{itemize}
  \item Everything, except the working directory, is under
    \texttt{.git/} which is found at top level in the working
    directory itself.
  \item One rarely needs to explicitly look in \texttt{.git/}
  \item Your local repository can serve as another's remote repository
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{\git from nothing}
  Start a new git repository from nothing is easy:
  \begin{lstlisting}[language=sh,emph={init}]
$ mkdir somedir
$ cd somedir
$ git init
  \end{lstlisting}
%$
\end{frame}

\begin{frame}[fragile]
  \frametitle{Cloning}
  To ``clone'' a \git repository means to make a local repository based on some other existing one.

  \begin{lstlisting}[language=sh]
$ git clone <URL>
  \end{lstlisting}
%$

  \begin{description}
  \item[anonymous URL] clone with no authentication but only one-way copy
  \end{description}
  \begin{lstlisting}[language=sh]
http://cdcvs.fnal.gov/projects/lbne-beamsim/g4lbne.git
  \end{lstlisting}

  \begin{description}
  \item[authenticated URL] clone with Fermilab Kerberos and Services accounts mitigated by Redmine.
  \end{description}
  \begin{lstlisting}[language=sh]
ssh://p-lbne-beamsim@cdcvs.fnal.gov/cvs/projects/lbne-beamsim/g4lbne.git
  \end{lstlisting}
\end{frame}


\begin{frame}[fragile]
  \frametitle{My First Clone}
  \begin{lstlisting}[language=sh,emph={clone,branch}]
$ git clone http://cdcvs.fnal.gov/projects/lbne-beamsim/g4lbne.git
$ cd g4lbne
$ ls -l
total 92
-rw-r--r-- 1 bv bv   676 Feb 12 21:10 CMakeLists.txt
drwxr-xr-x 4 bv bv  4096 Feb 12 21:10 example
-rw-r--r-- 1 bv bv 12097 Feb 12 21:10 g4lbne.cc
...
$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/muonFlux
  remotes/origin/v2
  \end{lstlisting}
%$
  \begin{description}
  \item[origin] default name the remote git repository
  \item[master] conventional name for main branch
  \end{description}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Visualizing the repository - gitk}
  \vspace{-2mm}
  \begin{center}
    \includegraphics[width=0.9\textwidth]{gitk-ss}
  \end{center}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Visualizing the repository - gitk}
  Use ``\texttt{gitk --all}'' for:
  \begin{itemize}
  \item Seeing recent commits
  \item Viewing their diffs
  \item Searching for a particular change
  \item Understanding which branches and tags are where
  \item Getting a specific commit hash (SHA1 ID)
  \item Instead of \texttt{--all} may focus on a specific directory or file.
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Info from the command line}
  \begin{description}
  \item[\texttt{git status}] state of working directory, lists any working files added/modified/deleted
  \item[\texttt{git log [<file>]}] see recent commit messages, potentially limited to one file
  \item[\texttt{git diff [<commit>]}] see diff between working directory and local repository or some specific commit (various ways to ``spell'' commit)
  \item[\texttt{git branch -a}] list local and remote branches
  \item[\texttt{git tag}] list what tags have been placed
  \item[\texttt{git remote -v}] list what remote repositories that your local repository knows
  \end{description}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Updating your local repository}

  From time to time you will want to update your local repository with
  any changes that have been pushed to the remote Redmine \git
  repository by others.

  \begin{description}
  \item[\texttt{git fetch}] this will download all commits from the remote repository but not merge into local branches or working directory.
  \item[\texttt{git pull}] this is a \texttt{fetch} plus a \texttt{merge} of the remote branch into your local branch and working directory.
  \end{description}

  \begin{itemize}
  \item A ``\texttt{git pull}'' is most similar to a ``\texttt{cvs update}''.
  \item You must have a ``clean'' \texttt{pull} before you may upload any of your own commis
  \item During the merge of a \texttt{pull} a conflict may arise (more later)
  \end{itemize}

\end{frame}

\begin{frame}[fragile]
  \frametitle{Adding new files to \git}
  Before a file can be tracked by git it needs to be added:
  \begin{lstlisting}[language=sh,emph={add}]
$ emacs somefile.cc
$ git add somefile.cc
  \end{lstlisting}
  This does not yet commit the file (technically it adds it to the
  \git ``index''). Rather, it makes git aware of it so that it may be
  committed in the future.

  You may add already added files w/out problem.

\end{frame}

\begin{frame}[fragile]
  \frametitle{Commit your own changes}
  A commit \textbf{always} is a local operation.
  \begin{lstlisting}[language=sh,emph={commit,add}]
$ emacs somefile.cc
$ git add somefile.cc
$ git commit -m "A succinct and useful commit message" 
# or
$ git commit -m "A succinct and useful commit message" somefile.cc
# or
$ git commit -a -m "A succinct and useful commit message"
  \end{lstlisting}
%$

  \begin{itemize}
  \item The ``\texttt{add + commit}'' will only commit those files added
  \item The ``\texttt{commit somefile.cc}'' commits only that file
  \item The ``\texttt{commit -a}'' commits all files modified (and
    which have been previously added)
  \end{itemize}

\end{frame}

\begin{frame}[fragile]
  \frametitle{Sharing your commits with others}

  There are many paradigms to share \git commits.  In our central-repository convention you ``push'' them to Redmine's \git repository.

  \begin{lstlisting}[language=sh,emph={push}]
$ git push origin master
# or just
$ git push    
  \end{lstlisting}
  \begin{itemize}
  \item First form explicitly says which remote to use (``origin'') and which branch (``master'')
  \item If the clone was made as described before, ``\texttt{origin
      master}'' are the default and can be omitted.
  \item You must use an authenticated clone to push.
    \begin{itemize}
    \item If you started with an anonymous clone you can add an authenticated remote.
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Adding more remotes}

  Say you started with an anonymous clone, then you made some changes
  and did some (local) commits and want to share them.

  \begin{lstlisting}[language=sh,emph={redmine}]
$ git remote add redmine \
  ssh://p-lbne-beamsim@cdcvs.fnal.gov/cvs/projects/lbne-beamsim/g4lbne.git
$ git pull redmine master    
$ git push redmine master    
  \end{lstlisting}
%$
Pick any name you like instead of ``\textcolor{red}{\texttt{redmine}}''.
\end{frame}










\begin{frame}[fragile]
  \frametitle{Conflicts}
  What are conflicts:
  \begin{itemize}
  \item \git does a good job of merging commits to the same file made by multiple people.
  \item but, if they overlap the same part of code \git can not figure
    out who's commit should ``win''
    \begin{itemize}
    \item this produces a ``conflict''
    \end{itemize}
  \item a conflict is reported during the merge part of a \texttt{git pull}
  \end{itemize}
  Resolving conflicts:
  \begin{itemize}
  \item Edit the conflicting file(s) and find regions delimited by ``\verb|<<< / === / >>>|''
  \item Pick your version, the remote version or some mix of the two
  \item add and commit the result.
  \end{itemize}
  Note: this is very similar to how conflicts were dealt with in CVS.
\end{frame}

\begin{frame}[fragile]
  \frametitle{Where to go for more}
  There are boat loads of documentation on \git!
  \begin{description}
  \item[Pro Git] \url{http://git-scm.com/book/}
  \item[online help] All commands are self documenting
  \end{description}
  \begin{lstlisting}[language=sh]
$ git help
$ git help commit
  \end{lstlisting}

  Since git is so distributed we do not have to get hung up on where
  remote repositories live or even how many any particular project
  has.  Some fantastic free hosting services:

  \begin{description}
  \item[FNAL Redmine] \url{https://cdcvs.fnal.gov/redmine/}
  \item[GitHub] \url{https://github.com/}
  \item[Gitorious] \url{https://gitorious.org/}
  \item[Gitolite] \url{http://gitolite.com/} (DIY)
  \end{description}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Some Nifty Extras}
  \begin{description}
  \item[shell completion] \git comes with some setup for
    \texttt{<TAB>} completion.  Use it, it makes working with git
    commands must easier.
    \url{https://github.com/git/git/tree/master/contrib/completion}
  \item[shell prompt] you can also modify your prompt to indicate some
    simple \git state such as active branch.  For bash I add \texttt{\$(\_\_git\_ps1 "(\%s)")}
  \item[git flow] a clone/branch/push/pull/merge methodology to well
    organize development.  It can be enacted by plain git but there
    are additional \git commands to assist.  These can be included in
    figure g4lbne installations.
  \end{description}
\end{frame}


\end{document}