\chapter*{Disclaimer}

\medskip{}
Pandora Products has carefully checked the information in this document and believes it to be accurate. However, Pandora Products assumes no responsibility for any inaccuracies that this document may contain. In no event will Pandora Products be liable for direct, indirect, special, exemplary, incidental, or consequential damages resulting from any defect or omission in this document, even if advised of the possibility of such damages. 

In the interest of product development, Pandora Products reserves the right to make improvements to the information in this document and the products that it describes at any time, without notice or obligation. 

Additional Contributors

\chapter{Source Control \& Why you need it}

\section{What is Source Control?}

A source control system is software that manages the files in a project. A project (like this book or a software application) usually has a number of files. These files in turn are managed by organizing them in directories and sub-directories. At any particular time this set of files in their present edited state make up a working copy of the project at the latest version. If other people are working the same project you would give them your current working copy to start with. As they find and fix problems, their working copy will become different from the one that you have (it will be in a different version). For you to be able to continue where they left off, you will need some mechanism to update your working copy of the files to the latest version available in the team. As soon as you have updated your files, this new version of the project goes through the same cycle again. Most likely the current version will be identified with a code, this is why books have editions and software has versions.

Software developers on large projects with multiple developers could see this cycle and realized they needed a tool to control the changes. With multiple developers sometimes the same file would be edited by two different people changing it in different ways and records of what got changed would be lost. It was hard to bring out a new release of the software and be sure that all the work of all team members to fix bugs and write enhancements were included.

A tool called Source Code Control System \cite{SCCS} was developed at Bell Labs in 1972 to track changes in files. It would remember each of the changes made to a file and store comments about why this was done. It also limited who could edit the file so conflicting edits would not be done. \cite{USE-SCCS}

\label{versioning}This was important but developers could see more was needed. They needed to be able to save the state of all the files in a project and give it a name (i.e., Release 3.14). As software projects mature you will have a released version of the software being used as well as bug reports written against it, while the next release of the software is being developed adding new features. The source control system would have to handle what are now called branches. One branch name for example "Version 1" is released but continues to have fixes added to create Version 1.1, 1.2, etc. At the same time you also have another branch which named "Version 2" with new features added under construction. 

In 1986 the open source Concurrent Version Control system CVS \cite{CVS} was developed. This system could label groups of files and allow multiple branches (i.e. versions) simultaneously. There have been many other systems developed since them some open source and some proprietary.

Fossil which was originally released in 2006 \cite{FOSSIL-HOME} is a easy to install version control system that also includes a trouble ticketing system ( Figure\vref{fig:viewticket}), a wiki ( Figure \vref{sub:Wiki-Use}) and self hosted web server ( Figure\vref{fig:Starting-Webserver}).


\section{Why version the files in your project?}

Why do you want to use a source control system? You won't be able to create files, delete files or, move files between directories at random. Making changes in your code becomes a check list of steps that must be followed carefully.

With all those hassles why do it? One of the most horrible feelings as a developer is the ``It worked yesterday'' syndrome. That is, you had code that worked just fine and now it doesn't. If you work on only one document, it is conceivable that you saved a copy under a different name (perhaps with a date) that you could go back to. But if you did not, you doubtlessly feel helpless at your inability to get back to working code. With a source control system and careful adherence to procedures you can just go back in time and get yesterday's code, or the code from one hour ago, or from last month. After you have don this, starting from known good code, you can figure out what happened.

Having a source control system also gives you the freedom to experiment, ``let's try that radical new technique'', and if it doesn't work it's easy to just go back to the previous state.

The rest of this book is a user manual for the Fossil version control system that does code management and much much more. It runs on multiple OS's and is free and open source software (FOSS). It is simple to install as it has only one executable and the repositories it creates are a single file that is easy to back up and are usually only 50\% the size of the original source.


\subsection{How to get it}

If this has interested you then you can get a copy of the Fossil executable here \url{http://www.fossil-scm.org/download.html}. There are Linux, Mac, and Windows executable links on this page. The source code is also available if you want or need to compile yourself. This web site, containing this PDF and the code behind the PDF, is self-hosted by Fossil (see Section\vref{sec:Multiple-Users}). 


\section{Source control description}

This next section is useful if you have not used source control systems before. I will define some of the vocabulary and explain the basic ideas of source control.


\subsection{Check out systems}

When describing the grandaddy of source control systems, like SCCS I said it managed the changes for a single file and also prevented multiple people from working on the same file at the same time. This is representative of a whole class of source control systems. In these you have the idea of ``checking-out'' a file so you can edit it. At the same time while other people using the system can see who is working on the file they are prevented from touching it. They can get a read-only copy so they can say build software but only the ``owner'' can edit it. When done editing the ``owner'' checks it back in then anyone else could work on on it. At the same time the system has recorded who had it and the changes made to it.

This system works well in small groups with real time communication. A common problem is that a file is checked out by some one else and \textbf{you} have to make a change in it. In a small group setting, just a shout over the cube wall will solve the problem. 


\subsection{Merge systems}

In systems represented by CVS or Subversion the barrier is not getting a file to work on but putting it back under version control. In these systems you pull the source code files to a working directory in your area. Then you edit these files making necessary changes. When done you commit or check them back into the repository. At this point they are back under version control and the system knows the changes from the last version to this version.

This gets around the problem mentioned above when others are blocked from working on a file. You now have the opposite problem in that more than one person can edit the same file and make changes. This is handled by the check-in process. There only one person at a time may check in a file. That being the case the system checks the file and if there are changes in repository file that are NOT in the one to be checked in stops the check in process. The system will ask if the user wants to merge these changes into his copy. Once that is done the new version of the file can be checked in.

This type of system is used on large projects like the Linux kernel or other systems where you have a large number of geographically distributed contributors.


\subsection{Distributed systems}

The representatives of two major systems we have described thus far are centralized. That is there is only one repository on a single server. When you get a copy of the files or check in files it all goes to just one place. These work and can support many, many users. A distributed system is an extension of this where it allows the repositories to be duplicated and has mechanisms to synchronize them. 

With a single server users of the repository must be able to connect to it to get updates and for check ins of new code. If you are not connected to the server you are stuck and cannot continue working. Distributed systems allow you to have your own copy of the repository then continue working and when back in communication synchronize with the server. This is very useful where people take their work home and cannot access the company network. Each person can have a copy of the repository and continue working and re-sync upon return to the office.


\subsection{Common Terms}

The following is a list of terms I will use when talking about version control or Fossil.
\begin{description}
\item [{Repository}] This is the store when the version controlled files are kept. It will be managed by a source control system
\item [{SCS}] Source control system, this is software that manages a group of files keeping track of changes and allowing multiple users to modify them in a controlled fashion
\item [{Commit}] In Fossil to store the current set of new and changed files into the repository.
\item [{Trunk}] The main line of code descent in a Fossil repository.
\item [{Branch}] A user defined split in the files served by an SCS. This allow multiple work points on the same repository. Older branches (versions) might have bug fixes applied and newer branches (versions) can have new features added.

\BOOKMARK [0][-]{chapter.1}{1 Source Control \046 Why you need it}{}% 1
\BOOKMARK [1][-]{section.1.1}{1.1 What is Source Control?}{chapter.1}% 2
\BOOKMARK [1][-]{section.1.2}{1.2 Why version the files in your project?}{chapter.1}% 3
\BOOKMARK [2][-]{subsection.1.2.1}{1.2.1 How to get it}{section.1.2}% 4
\BOOKMARK [1][-]{section.1.3}{1.3 Source control description}{chapter.1}% 5
\BOOKMARK [2][-]{subsection.1.3.1}{1.3.1 Check out systems}{section.1.3}% 6
\BOOKMARK [2][-]{subsection.1.3.2}{1.3.2 Merge systems}{section.1.3}% 7
\BOOKMARK [2][-]{subsection.1.3.3}{1.3.3 Distributed systems}{section.1.3}% 8
\BOOKMARK [2][-]{subsection.1.3.4}{1.3.4 Common Terms}{section.1.3}% 9
\BOOKMARK [0][-]{chapter.2}{2 Single Users}{}% 10

\usepackage{varioref}
\usepackage{float}
\usepackage{url}
\usepackage{amsmath}
\usepackage{makeidx}
\makeindex
\usepackage{graphicx}
\makeatletter % Changes control code settings - probably lyx inheritance. Closed by \makeatother below


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\pdfpageheight\paperheight
\pdfpagewidth\paperwidth

\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
\newenvironment{lyxcode}
{\par\begin{list}{}{
\setlength{\rightmargin}{\leftmargin}
\setlength{\listparindent}{0pt}% needed for AMS classes
\raggedright
\setlength{\itemsep}{0pt}
\setlength{\parsep}{0pt}
\normalfont\ttfamily}%
 \item[]}
{\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.

% Include the proper LaTeX packages:
%----------------------------------------------------------------------------------------------------
\usepackage{graphicx}
\usepackage{titling}
\usepackage{ifthen}
\usepackage[absolute]{textpos}
\usepackage[colorlinks=true,
                       pagecolor=black,
                       menucolor=black,
                       linkcolor=black,
                       citecolor=blue,
                       pagebordercolor=1 1 1,
                       urlcolor=red,
                       plainpages=false,
                       pdfpagelabels=true,
                       bookmarksnumbered=true]{hyperref}
\usepackage{lastpage}

\newcommand{\reportTopic}{<reportTopic>}
\newcommand{\revisionNumber}{<rev. no.>}
\newcommand{\documentNumber}{<doc. no.>}


% Setup the right-hand header to display the current doc section:
%----------------------------------------------------------------------------------------------------
\renewcommand{\sectionmark}[1]{\markright{#1}}
\renewcommand{\subsectionmark}[1]{\markright{#1}}

% Setup for roman numeral page numbers until TOC:
%----------------------------------------------------------------------------------------------------
\newboolean{romanpn}

\pagenumbering{roman}
\setboolean{romanpn}{true}
\let\myTOC\tableofcontents

\renewcommand\tableofcontents{%
\myTOC
\clearpage
\pagenumbering{arabic}
\setboolean{romanpn}{false}
}

% Modify titlepage format:
%----------------------------------------------------------------------------------------------------
\setlength{\TPHorizModule}{1in}
\setlength{\TPVertModule}{\TPHorizModule}
\textblockorigin{3.25in}{1in}

\pretitle
 {
    \begin{flushright}\LARGE\sffamily 
    \thispagestyle{empty}
    \begin{textblock}{4}(0,0)
    \includegraphics[width=4in,keepaspectratio=true]{Layout/fossil.png}
    \end{textblock}
    \vspace{2in}
  }

\posttitle{\par\end{flushright}}

\preauthor{\begin{flushright} \large \sffamily \lineskip 0.5em 
\begin{tabular}[t]{c}}
\postauthor{\end{tabular} \par\end{flushright}}

%\predate{\begin{flushright}\large \sffamily Document Number: \documentNumber \\ Revision Number: \revisionNumber \\}

%\postdate{
%\vspace{2in}
%\\Pandora Products.
%\\215 Uschak Road
%\\Derry, PA  15627
%\par\end{flushright}}

% Setup "fancy" page layout:
%----------------------------------------------------------------------------------------------------
\fancyhf{}
\setlength{\topmargin}{-1in}
\setlength{\headheight}{1in}
\setlength{\headsep}{0.5in}
\setlength{\oddsidemargin}{0.25in}
\setlength{\evensidemargin}{\oddsidemargin}
\setlength{\textwidth}{6in}
\setlength{\headwidth}{\textwidth}
\setlength{\textheight}{8.375in}
\setlength{\footskip}{0.5in}

% Setup header:
%------------------------------------------------------------------------------------------
\fancyhead[L]{\sffamily Fossil Version Control}


% Setup footer:
%------------------------------------------------------------------------------------------
\renewcommand{\footrulewidth}{0.4pt}
%\fancyfoot[L]{\sffamily \bfseries \documentNumber \\ \mdseries Revision:  \revisionNumber}
%\fancyfoot[C]{\sffamily \bfseries\thedate \\ }
\fancyfoot[R]{\ifthenelse{\boolean{romanpn}}{\sffamily  \thepage}{\sffamily Page \thepage\ of \pageref{LastPage}}}

\makeatother

\usepackage{babel}
\begin{document}
\renewcommand{\documentNumber}{PAN-20100424}

\renewcommand{\reportTopic}{A Users Guide}

\renewcommand{\revisionNumber}{2.0}


\title{Fossil Version Control\\ \reportTopic}


\author{Jim Schimpf}


\date{}

\maketitle
\thispagestyle{empty}

\newpage{}
2010 Pandora Products.
 
Document number: \documentNumber{}

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 United States License. To view a copy of this license, visit \url{http://creativecommons.org/licenses/by-sa/3.0/us/} or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. 

\medskip{}
Pandora Products \\
215 Uschak Road \\
Derry, PA 15627 \\
United States of America

\medskip{}
Phone: 724.539.1276 \\
Fax: 724.539.1276 \\
Web: http://www.fossil-scm.org/schimpf-book/index \\
Email: jim.schimpf@gmail.com \\

\textbf{This version:}

Revision Number: \revisionNumber{}

Date: November 29, 2012


\tableofcontents{}

% ----------- Start of Document Content ------------------

\include{Chapters/foreword}