diff options
Diffstat (limited to 'lecture-notes/vcs/vcs.tex')
| -rw-r--r-- | lecture-notes/vcs/vcs.tex | 516 |
1 files changed, 516 insertions, 0 deletions
diff --git a/lecture-notes/vcs/vcs.tex b/lecture-notes/vcs/vcs.tex new file mode 100644 index 0000000..3b5e6ab --- /dev/null +++ b/lecture-notes/vcs/vcs.tex @@ -0,0 +1,516 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Version Control Systems +% +% Author: FOSSEE +% Copyright (c) 2009, FOSSEE, IIT Bombay +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\documentclass[14pt,compress]{beamer} + +\mode<presentation> +{ + \usetheme{Warsaw} + \useoutertheme{infolines} + \setbeamercovered{transparent} +} + +\usepackage[english]{babel} +\usepackage[latin1]{inputenc} +%\usepackage{times} +\usepackage[T1]{fontenc} + +% Taken from Fernando's slides. +\usepackage{ae,aecompl} +\usepackage{mathpazo,courier,euler} +\usepackage[scaled=.95]{helvet} + +\definecolor{darkgreen}{rgb}{0,0.5,0} + +\usepackage{listings} +\lstset{language=bash, + basicstyle=\ttfamily\bfseries, + commentstyle=\color{red}\itshape, + stringstyle=\color{darkgreen}, + showstringspaces=false, + keywordstyle=\color{blue}\bfseries} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Macros +\setbeamercolor{emphbar}{bg=blue!20, fg=black} +\newcommand{\emphbar}[1] +{\begin{beamercolorbox}[rounded=true]{emphbar} + {#1} + \end{beamercolorbox} +} +\newcounter{time} +\setcounter{time}{0} +\newcommand{\inctime}[1]{\addtocounter{time}{#1}{\tiny \thetime\ m}} + +\newcommand{\typ}[1]{\lstinline{#1}} + +\newcommand{\kwrd}[1]{ \texttt{\textbf{\color{blue}{#1}}} } + +% Title page +\title[Mercurial]{Version Control with \typ{hg}} + +\author[FOSSEE] {FOSSEE} + +\institute[IIT Bombay] {Department of Aerospace Engineering\\IIT Bombay} +\date[]{} + +\AtBeginSection[] +{ + \begin{frame}<beamer> + \frametitle{Outline} + \tableofcontents[currentsection,currentsubsection] + \end{frame} +} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DOCUMENT STARTS +\begin{document} + +\begin{frame} + \maketitle +\end{frame} + +% CREATING TOC +\begin{frame} + \frametitle{Outline} + \tableofcontents + % You might wish to add the option [pausesections] +\end{frame} + +\begin{frame} + \frametitle{Objectives} + At the end of this session, you will be able to: + \begin{itemize} + \item Understand what is Version Control and the need for it + \item Create and use repository on a daily basis + \item Clone existing repositories, from the web + \item View the history of a repository + \item Make changes to a repository and commit them + \item Work collaboratively with a team + \end{itemize} +\end{frame} + +%% There are some %$ used just to minimise the effect of $ sign used +%% in lstlisting. In emacs it looks dirty. + +% Introduction to course-need of version control, history, options available. +\section{Introduction} + +\begin{frame} + \frametitle{What is Version Control?} + \begin{block}{} + A way to track changes made to files over time, by keeping copies + of files as we change them. + \end{block} +\end{frame} + +%% Home made version control system? +\begin{frame}[fragile] + \frametitle{Home-brewed} + \begin{center} + An example of a \typ{home-brew} Version Control system + \includegraphics[height=1.8in,width=4.2in]{images/folder.png} + \end{center} + \begin{lstlisting} +$ ls +a.out id1.txt id2.txt identifier.cpp id.txt lex pda1.cpp pda2.cpp pda.cpp pda.txt string.txt + \end{lstlisting} %%$ + %%a screen-shot of folder with all crazy names. +\end{frame} + +\begin{frame}[fragile] + \frametitle{Problems} + \begin{block}{} + \begin{itemize} + \item Name and changes made are not related or linked. + \item Can't track sequence of changes made to a file. + \item Does not scale. + \end{itemize} + \end{block} +\end{frame} + +\begin{frame}[fragile] + \frametitle{The need for Version Control} + \begin{itemize} + \item \alert{To err is Human} \ldots + \item Tracking the history and evolution of a project + \item To collaborate effectively on a project + \item To efficiently track down bugs and pin-point the changes that + caused it + \end{itemize} +\end{frame} + +%% Introduction to how logs are managed in VCS. +%% A analogy in logs and day-to-day life? +\begin{frame}[fragile] + \frametitle{How does it work? --- Analogy} + It is, in some ways, similar to playing an Video game. + \begin{itemize} + \item We play games in stages + \item Once we finish a stage or a task -- \alert{we SAVE} + \item We continue playing + \item But, if necessary, we could choose from one of the saved + states and start from there + \item We could alter the course of the game + \end{itemize} +\end{frame} + + +\begin{frame} + \frametitle{Mercurial or \typ{hg}} + \begin{center} + \includegraphics[height=.75in,interpolate=true]{images/mercurial_logo} + \end{center} + \begin{itemize} + \item Easy to learn and use + \item Lightweight + \item Scales excellently + \item Written in Python + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Installation} + \begin{itemize} + \item \typ{sudo apt-get install mercurial} + \item TortoiseHg + \item \typ{\$ hg} + \item \typ{\$ hg version} + \end{itemize} +\end{frame} + +\section{Let there be a Repo!} +% init, status, commit, log, [ui] +\begin{frame} + \frametitle{We need a repo!} + \begin{itemize} + \item A Repository (repo) is where all the action is! + \item Project files along with a special directory that stores all the + changes + \item We take snapshots of the whole repository; not individual + files. + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Initializing a repo} + \begin{itemize} + \item \typ{\$ hg init} + \item Creates a fresh repository + \item Adds a \typ{.hg} directory to our \emph{working directory} + \end{itemize} + \emphbar{\typ{.hg} directory keeps log of changes made henceforth} +\end{frame} + +\begin{frame} + \frametitle{Status report} + \begin{itemize} + \item \typ{hg status} gives the status of our repo + \item Use it often; at least as a beginner + \item \typ{hg help command} gives us help about \typ{command} + \end{itemize} +\end{frame} + +\begin{frame}[fragile] + \frametitle{Status codes} + \begin{lstlisting} + M = modified + A = added + R = removed + C = clean + ! = missing + ? = not tracked + I = ignored + \end{lstlisting} +\end{frame} + +\begin{frame} + \frametitle{Adding files} + \begin{itemize} + \item From \typ{hg status} we know, none of the files are being + tracked, yet. + \item \typ{hg add} --- asking \typ{hg} to track these files + \item As expected \typ{hg status} prepends an \typ{A} to the file + names. + \item \typ{? --> A} + \item \typ{! --> R} (\typ{hg remove}) + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Taking Snapshots} + \begin{itemize} + \item \typ{hg commit} + \item Asking Mercurial to take a snapshot; remember the changes made + to the repository. + \item \typ{-u FirstName LastName <email>} + \item \typ{-m ``Commit message''} -- a description of changes committed. + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Thumbnail views} + \begin{itemize} + \item \typ{hg log}~ gives the log of the changes made + \item A \typ{changeset} is an atomic collection of changes to the + files (between successive commits) + \end{itemize} + \begin{block}{Log information} + \begin{itemize} + \item \alert{changeset}: Identifier for the changeset + \item \alert{user}: Details of user who created the changeset + \item \alert{date}: Date and time of creation + \item \alert{summary}: One line description + \end{itemize} + \end{block} +\end{frame} + +\begin{frame} + \frametitle{User information} + \begin{itemize} + \item User information is set in the \typ{hgrc} file + \item It can be set globally or local to the project + \item Global \typ{hgrc} + \begin{itemize} + \item \typ{\$HOME/.hgrc} -- Unix like systems + \item \typ{\%HOME\%\\.hgrc} -- Windows + \end{itemize} + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{\alert{Advice}: \typ{commits}, messages} + \begin{itemize} + \item Atomic changes; one change with one \typ{commit} + \item Single line summary --- 60 to 65 characters long + \item Followed by paragraphs of detailed description + \begin{itemize} + \item Why the change? + \item What does it effect? + \item Known bugs/issues? + \item etc. + \end{itemize} + \end{itemize} +\end{frame} + +\section{But Why \typ{commit}~?} + +\begin{frame} + \frametitle{Operational overhead?} + \begin{itemize} + \item But why do we \typ{commit}? + \item Isn't all this just adding to operational costs? + \item Isn't all this a waste of time? + \end{itemize} + \begin{center} + \emphbar{No! You shall see the benefits, soon!} + \end{center} +\end{frame} + +\begin{frame} + \frametitle{Revert Changes} + \begin{itemize} + \item Undo all changes; the editor can only do so much. + \item \typ{hg revert --all} + \item \typ{hg revert filename} + \item Present file, with changes --- \typ{filename.orig} + \end{itemize} +\end{frame} + +\begin{frame}[fragile] + \frametitle{Viewing Changes} + \begin{itemize} + \item \typ{hg diff} --- all changes since last commit + \end{itemize} + \begin{block}{} + \begin{lstlisting} + - this line was deleted + + this line was added + \end{lstlisting} + \end{block} +\end{frame} + + +\begin{frame}[fragile] + \frametitle{Revision numbering} + \begin{itemize} + \item \typ{changeset: n:cbf6e2a375b4} + \item \typ{n} is the revision number + \item The revision number is local to a repository + \item \typ{cbf6e2a375b4} is the unique identifier + \end{itemize} +\end{frame} + +\begin{frame}[fragile] + \frametitle{Using revision numbers} + \begin{itemize} + \item \typ{-r n} can be passed as arguments to commands to specify + the revision number + \item For instance, \typ{hg diff -r1 -r2} + \item \typ{m:n} specifies a range of revision numbers + \item For instance, \typ{hg log -r0:2} + \end{itemize} +\end{frame} + +\section{Collaborating with Mercurial} +\begin{frame}[fragile] + \frametitle{Cloning Repositories} + \begin{itemize} + \item \typ{hg clone SOURCE [DEST]} + \item All \typ{hg} repositories are self-contained + \end{itemize} +\end{frame} + +\begin{frame}[fragile] + \frametitle{Sharing Repositories} + \begin{itemize} + \item \typ{hg serve} + \item Can be cloned with \typ{hg clone http://my-ip-address:8000} + \item We share a central repository; work on our local copies. + \item Set write permissions in \typ{.hg/hgrc} + \end{itemize} + \begin{lstlisting} + [web] + push_ssl=False + allow_push=* + \end{lstlisting} +\end{frame} + +\begin{frame} + \frametitle{Sharing Changes} + \begin{itemize} + \item Use \typ{hg push} to push your \typ{commits} + (\typ{changesets}) to the central repository + \end{itemize} +\end{frame} + + +\begin{frame} + \frametitle{Pulling Changes} + \begin{itemize} + \item \typ{hg incoming} shows new \typ{changesets} in the server + \item To get these \typ{changesets}, we use \typ{hg pull} + \item These changes do not affect our working directory + \item \typ{hg parent} shows the parents of the working directory + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Pulling Changes \ldots} + \begin{itemize} + \item \typ{hg update} will update the working directory + \begin{itemize} + \item Updates to the \typ{tip} if no revision is specified + \item \typ{tip} is the most recently added changeset + \item Can specify revision number to update to + \end{itemize} + \item \typ{hg tip} shows the \typ{tip} of the repository + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Simultaneous Changes} + \begin{itemize} + \item The logs of both repositories will be different + \item The repositories have diverged + \item \typ{hg push} fails, in such a scenario + \item \alert{Never, Never, Never, Ever} use \typ{hg push -f} + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Merging} + \begin{itemize} + \item Pull and merge, when \typ{abort: push creates new remote + heads!} + \item \typ{hg merge} will merge the two diverged heads + \item \typ{commit} after you have \typ{merged}! + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Simultaneous Changes \ldots} + \begin{itemize} + \item \typ{outgoing} shows the \typ{changesets} that will be pushed + \item \typ{hg push} works! + \item Look at the `Change graph'! + \end{itemize} +\end{frame} + +\begin{frame} + \frametitle{Simultaneous Conflicting Changes} + \begin{itemize} + \item What if the changes conflict? -- overlapping edits + \item \typ{hg push} fails; \typ{hg pull}; \typ{hg merge} + \item You now get a diff view with 3 panes + \begin{itemize} + \item First --- current file + \item Second --- \typ{changesets} that you pulled + \item Third --- file before you made your changes + \end{itemize} + \item Resolve conflict and save + \item \typ{hg commit}; \typ{hg push} + \item Look at the `Change graph'! + \end{itemize} +\end{frame} + +\section{Conclusion} + +\begin{frame} + \frametitle{\alert{Advice}: Work-flow} + General work-flow + \begin{itemize} + \item \typ{pull}; \typ{update} + \item Make changes + \item \typ{commit} + \item If changes on repo, \typ{pull} and \typ{merge} + \item \typ{push} + \end{itemize} + \emphbar{Commit Early, Commit Often} +\end{frame} + +\begin{frame}[fragile,allowframebreaks] + \frametitle{Summary} + In this session, we have learnt to: + \begin{itemize} + \item initialize new repositories, using \typ{hg init} + \item check the status using \typ{hg status} + \item get help for any command using \typ{hg help} + \item commit changes or take snapshots using \typ{hg commit} + \item view the history of a repository using \typ{hg log} + \item set the user info in the global \typ{hgrc} file + \item undo changes using \typ{hg revert} + \item view changes using \typ{hg diff} + \item use revision numbers as arguments to various commands + \item clone repositories using \typ{hg clone} + \item server repositories using \typ{hg serve} + \item push changes using \typ{hg push} + \item pull changes using \typ{hg pull} + \item update working directory to latest revision using \typ{hg + update} + \item merge two heads using \typ{hg merge} + \item resolve merge conflicts using \typ{hg resolve} + \end{itemize} +\end{frame} + + +\begin{frame} + \frametitle{References} + \begin{itemize} + \item \href{http://betterexplained.com/articles/a-visual-guide-to-version-control/}{A Visual Guide to Version Control} + \item \href{http://karlagius.com/2009/01/09/version-control-for-the-masses/}{Version Control for the Masses} + \item \href{http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/}{(Illustrated) Intro to Distributed Version Control} + \item \href{http://mercurial.selenic.com/wiki/UnderstandingMercurial}{Understanding Mercurial} + \item \href{http://mercurial.selenic.com/wiki/Tutorial}{A Tutorial on Using Mercurial} + \item \href{http://hginit.com/}{Hg Init: a Mercurial tutorial} + \item \href{http://mercurial.selenic.com/wiki/BeginnersGuides}{Beginners Guides} + \item \href{http://software-carpentry.org/4_0/vc/}{Software Carpentry} + \end{itemize} +\end{frame} + +\end{document} + |