\chapter{Document Revision History}

\textit{Use the following table to track a history of this documents revisions. An entry should be made into this table for each version of the document}.

\begin{center}
\begin{tabular}{|>{\centering}p{0.5in}|>{\centering}p{0.5in}|p{3in}|>{\centering}p{1in}|}
\hline 
Version & Author & Description & Date\tabularnewline
\hline 
0.1 & js & Initial Version & 24-Apr-2010\tabularnewline
\hline 
0.2 & js & Finishing up Single User Chapter & 27-Apr-2010\tabularnewline
\hline 
0.3 & js & Working on introduction chapter & 30-Apr-2010\tabularnewline
\hline 
0.4 & js & Adding multiuser chapter & 1-May-2010\tabularnewline
\hline 
0.5 & mn & Adding editorial corrections {[}ebf40b842a{]} & 4-May-2010\tabularnewline
\hline 
0.6 & js & Adding Command sections {[}e11399d575{]} & 8-May-2010\tabularnewline
\hline 
0.7 & js & English \& spelling corrections & 19-May-2010\tabularnewline
\hline 
0.8 & js & Spelling fixes & 30-May-2010\tabularnewline
\hline 
0.9 & ws & Using Fossil merge {[}db6c734300{]} & 2-Jun-2010\tabularnewline
\hline 
1.0 & js/ws & Put Fossil merge first in handling fork & 3-Jun-2010\tabularnewline
\hline 
1.1 & mn & Fixes in multiple user chapter {[}e8770d3172{]} & 4-Jun-2010\tabularnewline
\hline 
1.2 & js & Start advanced use chapter {[}2abc23dae5{]} & 4-Jun-2010\tabularnewline
\hline 
1.3 & mn & English corrections Chapter 1 {[}8b324dc900{]} & 5-Jun-2010\tabularnewline
\hline 
1.4 & mn & Sections 2.1 \& 2.2 corrections {[}0b34cb6f04{]} & 7-Jun-2010\tabularnewline
\hline 
1.5 & js & Move close leaf to adv use {[}2abc23dae5{]} & 7-Jun-2010\tabularnewline
\hline 
1.6 & js & Convert Advanced chapter to forks and branching & 13-Jun-2010\tabularnewline
\hline 
1.7 & js/tr & Add note about IP port usage {[}a62efa8eba{]} & 8-Jul-2010\tabularnewline
\hline 
1.71 & javelin & Check on mispelling section 1.1 {[}637d974f62{]} & 15-Sep-2011\tabularnewline
\hline 
1.72 & anon & Fix absolute path in image regs {[}d54868853b{]} & 15-Sep-2011\tabularnewline
\hline 
1.73 & anon & Fix fossil create section 2.2.5 {[}36772d90a5{]} & 15-Sep-2011\tabularnewline
\hline 
1.74 & anon & Push/Pull described incorrectly {[}1b930fced6{]} & 15-Sep-2011\tabularnewline
\hline 
1.75 & arnel & Commands might be changed  {[}4aaf1f78bb{]} & 15-Sep-2011\tabularnewline
\hline 
2.0 & FvD & Updated and matched to fossil 1.25 & March 2013\tabularnewline
\hline 
\end{tabular}
\par\end{center}

Notes to the 2nd edition
------------------------

* Changed the lay-out of the document to formal tex (no longer lyx) and separation of chapters to separate files. This makes it easier to version the full text and to separate work on different chapters between reviewers / editors / authors.

* Changed the main class for the book to koma script book (scrbook). This will support separate chapters

* Changed all the \section{}s to \chapter{}s and upped the \subsubsection{}s to \section{}

* Readded the TH1 scripting section from change:

        Comment:	Added section on TH scripting [b832f46d31] 

\chapter{Fossil Commands}

\section{Introduction}
This section will go through the various Fossil command line commands. This will be divided into sections, the first will detail the must know commands. These are the ones you will be using all the time and will probably have memorized in short order. The other commands will be divided into Maintenance, Advanced, and Miscellaneous. These you will probably be checking as reference before use.

The most important command is \textbf{help}. You can always type \textbf{fossil help} at the command line and it will list out all the commands it has. Then typing f\textbf{ossil help <command> }will print out the detailed information on that command. You always have that as your reference. This section of the book will try to supplement the built in help with some examples and further explanation of what a command does. All of the commands will be placed in the index for easy searching

\textbf{NOTE:} Fossil is a moving target, commands might be added and others removed future versions. Type \textbf{fossil help }on your version to get the latest list. The following applies to the fossil I used when I wrote this and your version might be different.


\section{Basic Commands}
\subsection{help\index{help}}

This command is used to dump the current command set and version of Fossil. It can also be used in the form \textbf{fossil help <command> }to get further information on any command.

\begin{figure}[H]
\noindent \begin{centering}
\includegraphics{Images/Commands/help1}
\par\end{centering}

\caption{Help run}
\end{figure}

Actually this will give you only a subset of the help commands, limited to the commands that are used most often. If you want to see all commands available then issue the \textbf{fossil help --all} command. Between versions you will see changes as to what is included in the help sub-set.

An example of using the \textbf{help} function to get further information about a particular command:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~add}{\scriptsize \par}

{\scriptsize Usage:~fossil~add~FILE...}{\scriptsize \par}

{\scriptsize Make~arrangements~to~add~one~or~more~files~to~the~current~checkout}{\scriptsize \par}

{\scriptsize at~the~next~commit.}{\scriptsize \par}

{\scriptsize When~adding~files~recursively,~filenames~that~begin~with~\textquotedbl{}.\textquotedbl{}~are}{\scriptsize \par}

{\scriptsize excluded~by~default.~To~include~such~files,~add~the~\textquotedbl{}-{}-dotfiles\textquotedbl{}}{\scriptsize \par}

{\scriptsize option~to~the~command-line.}{\scriptsize \par}
\end{lyxcode}
\caption{Help detail}


\end{figure}



\subsection{add\index{add}}

The add command is used to add files into a repository. It is recursive and will pull in all files in subdirectories of the current. Fossil will not overwrite any of the files already present in the repository so it is safe to add all the files at any time. Only new files will be added.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil}{\scriptsize{}~}\textbf{\scriptsize help~add}{\scriptsize \par}

{\scriptsize Usage:~fossil~add~FILE...}{\scriptsize \par}

{\scriptsize Make~arrangements~to~add~one~or~more~files~to~the~current~checkout}{\scriptsize \par}

{\scriptsize at~the~next~commit.}{\scriptsize \par}

{\scriptsize When~adding~files~recursively,~filenames~that~begin~with~\textquotedbl{}.\textquotedbl{}~are}{\scriptsize \par}

{\scriptsize excluded~by~default.~To~include~such~files,~add~the~\textquotedbl{}-{}-dotfiles\textquotedbl{}}{\scriptsize \par}

{\scriptsize option~to~the~command-line.}{\scriptsize \par}
\end{lyxcode}
\caption{add detail}


\end{figure}


Typing:
\begin{lyxcode}
fossil~add~.
\end{lyxcode}
will add all files in the current directory and subdirectories.

Note none of these files are put in the repository untill a commit is done.


\subsection{rm\index{rm} or del\index{del}}

The rm command is used to remove files from the repository. The file is not deleted from the file system but it will be dropped from the repository on the next commit. This file will still be available in earlier versions of the repository but not in later ones.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rm}{\scriptsize \par}

{\scriptsize Usage:~fossil~rm~FILE...}{\scriptsize \par}

{\scriptsize{}~~~or:~fossil~del~FILE...}{\scriptsize \par}

{\scriptsize Remove~one~or~more~files~from~the~tree.}{\scriptsize \par}

{\scriptsize This~command~does~not~remove~the~files~from~disk.~~It~just~marks~the}{\scriptsize \par}

{\scriptsize files~as~no~longer~being~part~of~the~project.~~In~other~words,~future}{\scriptsize \par}

{\scriptsize changes~to~the~named~files~will~not~be~versioned.}{\scriptsize \par}
\end{lyxcode}
\caption{rm detail}


\end{figure}


You can delete groups of files by using wild-cards in their names. Thus if I had a group of files like com\_tr.c, com\_rx.c and com\_mgmt.c I could remove them all with:
\begin{lyxcode}
fossil~rm~com\_{*}.c
\end{lyxcode}
By running a ``fossil status'' you can see what files will be deleted on the next commit.


\subsection{rename\index{rename} or mv\index{mv}}

This command is used to rename a file in the repository. This does not rename files on disk so is usually used after you have renamed files on the disk then want to change this in the repository.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~rename}{\scriptsize \par}

{\scriptsize Usage:~fossil~mv|rename~OLDNAME~NEWNAME}{\scriptsize \par}

{\scriptsize{}~~~or:~fossil~mv|rename~OLDNAME...~DIR}{\scriptsize \par}

{\scriptsize Move~or~rename~one~or~more~files~within~the~tree}{\scriptsize \par}

{\scriptsize This~command~does~not~rename~the~files~on~disk.~~All~this~command~does~is}{\scriptsize \par}

{\scriptsize record~the~fact~that~filenames~have~changed~so~that~appropriate~notations}{\scriptsize \par}

{\scriptsize can~be~made~at~the~next~commit/checkin.}{\scriptsize \par}
\end{lyxcode}
\caption{rename detail}
\end{figure}


Just like add or rm you can use wild cards in the names and rename groups of files. Like them ``fossil status'' will show you the current state.


\subsection{status\index{status}}

The status command is used to show you the current state of your files relative to the repository. It will show you files added, deleted, and changed. This is only the condition of files that are already in the repository or under control of fossil. It also shows from where in the timeline you are checked out and where your repository is kept.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~status}{\scriptsize \par}

{\scriptsize repository:~~~/Users/jschimpf/Public/FOSSIL/FossilBook.fossil}{\scriptsize \par}

{\scriptsize local-root:~~~/Users/jschimpf/Public/FossilBook/}{\scriptsize \par}

{\scriptsize server-code:~~3e67da6d6212494456c69b1c5406a277d7e50430}{\scriptsize \par}

{\scriptsize checkout:~~~~~edd5b5fa4277604f365ec09238422c0aa7a28faf~2010-05-08~14:44:21~UTC}{\scriptsize \par}

{\scriptsize parent:~~~~~~~3f019cbc730db0eb35f20941533a22635856b2b3~2010-05-08~11:15:19~UTC}{\scriptsize \par}

{\scriptsize tags:~~~~~~~~~trunk}{\scriptsize \par}

{\scriptsize EDITED~~~~~fossilbook.lyx}{\scriptsize \par}

{\scriptsize EDITED~~~~~outline.txt}{\scriptsize \par}
\end{lyxcode}
\caption{\label{fig:status-run}status run}


\end{figure}


The listing above shows where my cloned copy of the repository is kept, where I am working, and the tags show me that I am checked out of the trunk. Finally it shows the status of the files: I am working on two of them.


\subsection{changes\index{changes}}

This lists the changed files like status but does not show the other information that status does.

\begin{figure}
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~changes}{\scriptsize \par}

{\scriptsize Usage:~fossil~changes}{\scriptsize \par}

{\scriptsize Report~on~the~edit~status~of~all~files~in~the~current~checkout.}{\scriptsize \par}

{\scriptsize See~also~the~\textquotedbl{}status\textquotedbl{}~and~\textquotedbl{}extra\textquotedbl{}~commands.}{\scriptsize \par}
\end{lyxcode}
\caption{changes details}


\end{figure}



\subsection{extra\index{extra}}

The extra command is used to find files you have added to your working directory but are not yet under Fossil control. This is important because if you move your working directory or others attempt to use the repository they won't have these files. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~extra}{\scriptsize \par}

{\scriptsize Usage:~fossil~extras~?-{}-dotfiles?~?-{}-ignore~GLOBPATTERN?}{\scriptsize \par}

{\scriptsize Print~a~list~of~all~files~in~the~source~tree~that~are~not~part~of}{\scriptsize \par}

{\scriptsize the~current~checkout.~~See~also~the~\textquotedbl{}clean\textquotedbl{}~command.}{\scriptsize \par}

{\scriptsize Files~and~subdirectories~whose~names~begin~with~\textquotedbl{}.\textquotedbl{}~are~normally}{\scriptsize \par}

{\scriptsize ignored~but~can~be~included~by~adding~the~-{}-dotfiles~option.}{\scriptsize \par}
\end{lyxcode}
\caption{extra details}


\end{figure}


The --dotfiles option shows you any files starting with ``.'' that are not under Fossil control. This would be important if you need those files in your repository. The last option --ignore allows you to ignore certain files you know don't belong in the repository. In my case there is a file called fossilbook.lyx\textasciitilde{} that is a \LyX{} backup file that I do not want, as it is temporary. So I can say
\begin{lyxcode}
fossil~extra~-{}-ignore~{*}.lyx\textasciitilde{}~
\end{lyxcode}
and only get:
\begin{lyxcode}
{[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~extra~-{}-ignore~{*}.lyx\textasciitilde{}}

Images/Commands/help1.epsf
\end{lyxcode}
instead of:
\begin{lyxcode}
{[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~extra}

Images/Commands/help1.epsf

fossilbook.lyx\textasciitilde{}
\end{lyxcode}

\subsection{revert\index{revert}}

The revert command is used to take a file back to the value in the repository. This is useful when you make a error in editing or other mistake.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~revert}{\scriptsize \par}

{\scriptsize Usage:~fossil~revert~?-r~REVISION?~FILE~...}{\scriptsize \par}

{\scriptsize Revert~to~the~current~repository~version~of~FILE,~or~to}{\scriptsize \par}

{\scriptsize the~version~associated~with~baseline~REVISION~if~the~-r~flag}{\scriptsize \par}

{\scriptsize appears.}{\scriptsize \par}

{\scriptsize If~a~file~is~reverted~accidently,~it~can~be~restored~using}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}fossil~undo\textquotedbl{}~command.}{\scriptsize \par}
\end{lyxcode}
\caption{revert details}


\end{figure}


With no parameters it will revert the file to the current revision, see Figure \vref{fig:status-run}. The -r option allows you to pick any revision from the time line.


\subsection{update\index{update}}

The update option will update a file or files to match the repository. With multiple users it should be done before you start working on any files. This ensures you have the latest version of all the files. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~update}{\scriptsize \par}

{\scriptsize Usage:~fossil~update~?VERSION?~?FILES...?}{\scriptsize \par}

{\scriptsize Change~the~version~of~the~current~checkout~to~VERSION.~~Any~uncommitted}{\scriptsize \par}

{\scriptsize changes~are~retained~and~applied~to~the~new~checkout.}{\scriptsize \par}



{\scriptsize The~VERSION~argument~can~be~a~specific~version~or~tag~or~branch~name.}{\scriptsize \par}

{\scriptsize If~the~VERSION~argument~is~omitted,~then~the~leaf~of~the~the~subtree}{\scriptsize \par}

{\scriptsize that~begins~at~the~current~version~is~used,~if~there~is~only~a~single}{\scriptsize \par}

{\scriptsize leaf.~~VERSION~can~also~be~\textquotedbl{}current\textquotedbl{}~to~select~the~leaf~of~the~current}{\scriptsize \par}

{\scriptsize version~or~\textquotedbl{}latest\textquotedbl{}~to~select~the~most~recent~check-in.}{\scriptsize \par}



{\scriptsize If~one~or~more~FILES~are~listed~after~the~VERSION~then~only~the}{\scriptsize \par}

{\scriptsize named~files~are~candidates~to~be~updated.~~If~FILES~is~omitted,~all}{\scriptsize \par}

{\scriptsize files~in~the~current~checkout~are~subject~to~be~updated.}{\scriptsize \par}



{\scriptsize The~-n~or~-{}-nochange~option~causes~this~command~to~do~a~\textquotedbl{}dry~run\textquotedbl{}.~~It}{\scriptsize \par}

{\scriptsize prints~out~what~would~have~happened~but~does~not~actually~make~any}{\scriptsize \par}

{\scriptsize changes~to~the~current~checkout~or~the~repository.}{\scriptsize \par}



{\scriptsize The~-v~or~-{}-verbose~option~prints~status~information~about~unchanged}{\scriptsize \par}

{\scriptsize files~in~addition~to~those~file~that~actually~do~change.}{\scriptsize \par}
\end{lyxcode}
\caption{update details}


\end{figure}


Update has a number of options, first you can tie the update to a particular version, if not picked then it just uses the latest. Second it can work on a single files or many files at once. That is you could say
\begin{lyxcode}
fossil~update~{*}.c
\end{lyxcode}
and it would update all C files.

Since this is a rather large set of changes it has a special ``dry run'' mode. If you add -n on the command it will just print out what will be done but not do it. This is very useful to do this trial if you are unsure what might happen. The -v command (which can be used with -n or alone) prints out the action for each file even if it does nothing.


\subsection{checkout\index{checkout} or co\index{co}}

This command is similar to update.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~checkout}{\scriptsize \par}

{\scriptsize Usage:~fossil~checkout~VERSION~?-f|-{}-force?~?-{}-keep?}{\scriptsize \par}

{\scriptsize Check~out~a~version~specified~on~the~command-line.~~This~command}{\scriptsize \par}

{\scriptsize will~abort~if~there~are~edited~files~in~the~current~checkout~unless}{\scriptsize \par}

{\scriptsize the~-{}-force~option~appears~on~the~command-line.~~The~-{}-keep~option}{\scriptsize \par}

{\scriptsize leaves~files~on~disk~unchanged,~except~the~manifest~and~manifest.uuid}{\scriptsize \par}

{\scriptsize files.}{\scriptsize \par}

{\scriptsize The~-{}-latest~flag~can~be~used~in~place~of~VERSION~to~checkout~the}{\scriptsize \par}

{\scriptsize latest~version~in~the~repository.}{\scriptsize \par}

{\scriptsize See~also~the~\textquotedbl{}update\textquotedbl{}~command.}{\scriptsize \par}
\end{lyxcode}
\caption{checkout or co details}


\end{figure}



\subsection{undo\index{undo}}

This is used to undo the last update, merge, or revert operation. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~undo}{\scriptsize \par}

{\scriptsize Usage:~fossil~undo~?FILENAME...?}{\scriptsize \par}



{\scriptsize Undo~the~most~recent~update~or~merge~or~revert~operation.~~If~FILENAME~is}{\scriptsize \par}

{\scriptsize specified~then~restore~the~content~of~the~named~file(s)~but~otherwise}{\scriptsize \par}

{\scriptsize leave~the~update~or~merge~or~revert~in~effect.}{\scriptsize \par}



{\scriptsize A~single~level~of~undo/redo~is~supported.~~The~undo/redo~stack}{\scriptsize \par}

{\scriptsize is~cleared~by~the~commit~and~checkout~commands.}{\scriptsize \par}
\end{lyxcode}
\caption{undo details}


\end{figure}


It acts on a single file or files if specified, otherwise if no file given, it undoes all of the last changes.


\subsection{diff\index{diff}}

The diff command is used to produce a text listing of the difference of a file in the working directory and that same file in the repository. If you don't specify a file it will show the differences between all the changed files in the working directory vs the repository. If you use the --from and --to options you can specify which versions to check and to compare between two different versions in the repository. Not using the --to means compare with the working directory.

If you have configured an external diff program it will be used unless you use the -i option which uses the diff built into Fossil.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~diff}{\scriptsize \par}

{\scriptsize Usage:~fossil~diff|gdiff~?options?~?FILE?}{\scriptsize \par}



{\scriptsize Show~the~difference~between~the~current~version~of~FILE~(as~it}{\scriptsize \par}

{\scriptsize exists~on~disk)~and~that~same~file~as~it~was~checked~out.~~Or}{\scriptsize \par}

{\scriptsize if~the~FILE~argument~is~omitted,~show~the~unsaved~changed~currently}{\scriptsize \par}

{\scriptsize in~the~working~check-out.}{\scriptsize \par}



{\scriptsize If~the~\textquotedbl{}-{}-from~VERSION\textquotedbl{}~or~\textquotedbl{}-r~VERSION\textquotedbl{}~option~is~used~it~specifies}{\scriptsize \par}

{\scriptsize the~source~check-in~for~the~diff~operation.~~If~not~specified,~the~}{\scriptsize \par}

{\scriptsize source~check-in~is~the~base~check-in~for~the~current~check-out.}{\scriptsize \par}

{\scriptsize If~the~\textquotedbl{}-{}-to~VERSION\textquotedbl{}~option~appears,~it~specifies~the~check-in~from}{\scriptsize \par}

{\scriptsize which~the~second~version~of~the~file~or~files~is~taken.~~If~there~is}{\scriptsize \par}

{\scriptsize no~\textquotedbl{}-{}-to\textquotedbl{}~option~then~the~(possibly~edited)~files~in~the~current~check-out}{\scriptsize \par}

{\scriptsize are~used.}{\scriptsize \par}



{\scriptsize The~\textquotedbl{}-i\textquotedbl{}~command-line~option~forces~the~use~of~the~internal~diff~logic}{\scriptsize \par}

{\scriptsize rather~than~any~external~diff~program~that~might~be~configured~using}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}setting\textquotedbl{}~command.~~If~no~external~diff~program~is~configured,~then}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}-i\textquotedbl{}~option~is~a~no-op.~~The~\textquotedbl{}-i\textquotedbl{}~option~converts~\textquotedbl{}gdiff\textquotedbl{}~into~\textquotedbl{}diff\textquotedbl{}.}{\scriptsize \par}
\end{lyxcode}
\caption{diff details}


\end{figure}



\subsection{gdiff\index{gdiff}}

This is the same as the diff command but uses (if configured) a graphical diff program you have on your system. See the settings command for details on how to set the graphical diff program.

\begin{figure}
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~gdiff}{\scriptsize \par}

{\scriptsize Usage:~fossil~diff|gdiff~?options?~?FILE?}{\scriptsize \par}

{\scriptsize Show~the~difference~between~the~current~version~of~FILE~(as~it}{\scriptsize \par}

{\scriptsize exists~on~disk)~and~that~same~file~as~it~was~checked~out.~~Or}{\scriptsize \par}

{\scriptsize if~the~FILE~argument~is~omitted,~show~the~unsaved~changed~currently}{\scriptsize \par}

{\scriptsize in~the~working~check-out.}{\scriptsize \par}

{\scriptsize If~the~\textquotedbl{}-{}-from~VERSION\textquotedbl{}~or~\textquotedbl{}-r~VERSION\textquotedbl{}~option~is~used~it~specifies}{\scriptsize \par}

{\scriptsize the~source~check-in~for~the~diff~operation.~~If~not~specified,~the~}{\scriptsize \par}

{\scriptsize source~check-in~is~the~base~check-in~for~the~current~check-out.}{\scriptsize \par}

{\scriptsize If~the~\textquotedbl{}-{}-to~VERSION\textquotedbl{}~option~appears,~it~specifies~the~check-in~from}{\scriptsize \par}

{\scriptsize which~the~second~version~of~the~file~or~files~is~taken.~~If~there~is}{\scriptsize \par}

{\scriptsize no~\textquotedbl{}-{}-to\textquotedbl{}~option~then~the~(possibly~edited)~files~in~the~current~check-out}{\scriptsize \par}

{\scriptsize are~used.}{\scriptsize \par}

{\scriptsize The~\textquotedbl{}-i\textquotedbl{}~command-line~option~forces~the~use~of~the~internal~diff~logic}{\scriptsize \par}

{\scriptsize rather~than~any~external~diff~program~that~might~be~configured~using}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}setting\textquotedbl{}~command.~~If~no~external~diff~program~is~configured,~then}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}-i\textquotedbl{}~option~is~a~no-op.~~The~\textquotedbl{}-i\textquotedbl{}~option~converts~\textquotedbl{}gdiff\textquotedbl{}~into~\textquotedbl{}diff\textquotedbl{}.}{\scriptsize \par}
\end{lyxcode}
\caption{gdiff details}


\end{figure}



\subsection{ui\index{ui} }

The ui command is used to start Fossil in a local webserver. The --port option is used to specify the port it uses, by default it uses 8080. It should automatically start the system's web browser and it will come up with the repository web page. If run within a working directory it will bring up the web page for that repository. If run outside the working directory you can specify the repository on the command line.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~ui}{\scriptsize \par}

{\scriptsize Usage:~fossil~server~?-P|-{}-port~TCPPORT?~?REPOSITORY?}{\scriptsize \par}

{\scriptsize{}~~~Or:~fossil~ui~?-P|-{}-port~TCPPORT?~?REPOSITORY?}{\scriptsize \par}



{\scriptsize Open~a~socket~and~begin~listening~and~responding~to~HTTP~requests~on}{\scriptsize \par}

{\scriptsize TCP~port~8080,~or~on~any~other~TCP~port~defined~by~the~-P~or}{\scriptsize \par}

{\scriptsize -{}-port~option.~~The~optional~argument~is~the~name~of~the~repository.}{\scriptsize \par}

{\scriptsize The~repository~argument~may~be~omitted~if~the~working~directory~is}{\scriptsize \par}

{\scriptsize within~an~open~checkout.}{\scriptsize \par}



{\scriptsize The~\textquotedbl{}ui\textquotedbl{}~command~automatically~starts~a~web~browser~after~initializing}{\scriptsize \par}

{\scriptsize the~web~server.}{\scriptsize \par}



{\scriptsize In~the~\textquotedbl{}server\textquotedbl{}~command,~the~REPOSITORY~can~be~a~directory~(aka~folder)}{\scriptsize \par}

{\scriptsize that~contains~one~or~more~repositories~with~names~ending~in~\textquotedbl{}.fossil\textquotedbl{}.}{\scriptsize \par}

{\scriptsize In~that~case,~the~first~element~of~the~URL~is~used~to~select~among~the}{\scriptsize \par}

{\scriptsize various~repositories.}{\scriptsize \par}
\end{lyxcode}
\caption{ui details}
\end{figure}



\subsection{server\index{server}}

This is a more powerful version of the ui command. This allows you to have multiple repositories supported by a single running Fossil webserver. This way you start the server and instead of a paricular repository you specify a directory where a number of repositories reside (all having the extension .fossil) then you can open and use any of them.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~server}{\scriptsize \par}

{\scriptsize Usage:~fossil~server~?-P|-{}-port~TCPPORT?~?REPOSITORY?}{\scriptsize \par}

{\scriptsize{}~~~Or:~fossil~ui~?-P|-{}-port~TCPPORT?~?REPOSITORY?}{\scriptsize \par}

{\scriptsize Open~a~socket~and~begin~listening~and~responding~to~HTTP~requests~on}{\scriptsize \par}

{\scriptsize TCP~port~8080,~or~on~any~other~TCP~port~defined~by~the~-P~or}{\scriptsize \par}

{\scriptsize -{}-port~option.~~The~optional~argument~is~the~name~of~the~repository.}{\scriptsize \par}

{\scriptsize The~repository~argument~may~be~omitted~if~the~working~directory~is}{\scriptsize \par}

{\scriptsize within~an~open~checkout.}{\scriptsize \par}

{\scriptsize The~\textquotedbl{}ui\textquotedbl{}~command~automatically~starts~a~web~browser~after~initializing}{\scriptsize \par}

{\scriptsize the~web~server.}{\scriptsize \par}

{\scriptsize In~the~\textquotedbl{}server\textquotedbl{}~command,~the~REPOSITORY~can~be~a~directory~(aka~folder)}{\scriptsize \par}

{\scriptsize that~contains~one~or~more~repositories~with~names~ending~in~\textquotedbl{}.fossil\textquotedbl{}.}{\scriptsize \par}

{\scriptsize In~that~case,~the~first~element~of~the~URL~is~used~to~select~among~the}{\scriptsize \par}

{\scriptsize various~repositories.}{\scriptsize \par}
\end{lyxcode}
\caption{server detail\label{fig:server-detail}}


\end{figure}



\subsection{commit\index{commit} or ci\index{ci}}

This is the command used to put the current changes in the working directory into the repository, giving this a new version and updating the timeline.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~commit}{\scriptsize \par}

{\scriptsize Usage:~fossil~commit~?OPTIONS?~?FILE...?}{\scriptsize \par}



{\scriptsize Create~a~new~version~containing~all~of~the~changes~in~the~current}{\scriptsize \par}

{\scriptsize checkout.~~You~will~be~prompted~to~enter~a~check-in~comment~unless}{\scriptsize \par}

{\scriptsize one~of~the~\textquotedbl{}-m\textquotedbl{}~or~\textquotedbl{}-M\textquotedbl{}~options~are~used~to~specify~a~comment.}{\scriptsize \par}

{\scriptsize \textquotedbl{}-m\textquotedbl{}~takes~a~single~string~for~the~commit~message~and~\textquotedbl{}-M\textquotedbl{}~requires}{\scriptsize \par}

{\scriptsize a~filename~from~which~to~read~the~commit~message.~If~neither~\textquotedbl{}-m\textquotedbl{}}{\scriptsize \par}

{\scriptsize nor~\textquotedbl{}-M\textquotedbl{}~are~specified~then~the~editor~defined~in~the~\textquotedbl{}editor\textquotedbl{}}{\scriptsize \par}

{\scriptsize fossil~option~(see~fossil~help~set)~will~be~used,~or~from~the}{\scriptsize \par}

{\scriptsize \textquotedbl{}VISUAL\textquotedbl{}~or~\textquotedbl{}EDITOR\textquotedbl{}~environment~variables~(in~that~order)~if~no}{\scriptsize \par}

{\scriptsize editor~is~set.}{\scriptsize \par}



{\scriptsize You~will~be~prompted~for~your~GPG~pass~phrase~in~order~to~sign~the}{\scriptsize \par}

{\scriptsize new~manifest~unless~the~\textquotedbl{}-{}-nosign\textquotedbl{}~options~is~used.~~All~files~that}{\scriptsize \par}

{\scriptsize have~changed~will~be~committed~unless~some~subset~of~files~is}{\scriptsize \par}

{\scriptsize specified~on~the~command~line.}{\scriptsize \par}



{\scriptsize The~-{}-branch~option~followed~by~a~branch~name~cases~the~new~check-in}{\scriptsize \par}

{\scriptsize to~be~placed~in~the~named~branch.~~The~-{}-bgcolor~option~can~be~followed}{\scriptsize \par}

{\scriptsize by~a~color~name~(ex:~~'\#ffc0c0')~to~specify~the~background~color~of}{\scriptsize \par}

{\scriptsize entries~in~the~new~branch~when~shown~in~the~web~timeline~interface.}{\scriptsize \par}

{\scriptsize A~check-in~is~not~permitted~to~fork~unless~the~-{}-force~or~-f}{\scriptsize \par}

{\scriptsize option~appears.~~A~check-in~is~not~allowed~against~a~closed~check-in.}{\scriptsize \par}

{\scriptsize The~-{}-private~option~creates~a~private~check-in~that~is~never~synced.}{\scriptsize \par}

{\scriptsize Children~of~private~check-ins~are~automatically~private.}{\scriptsize \par}



{\scriptsize Options:}{\scriptsize \par}

{\scriptsize{}~~~-{}-comment|-m~COMMENT-TEXT}{\scriptsize \par}

{\scriptsize{}~~~-{}-branch~NEW-BRANCH-NAME}{\scriptsize \par}

{\scriptsize{}~~~-{}-bgcolor~COLOR}{\scriptsize \par}

{\scriptsize{}~~~-{}-nosign}{\scriptsize \par}

{\scriptsize{}~~~-{}-force|-f}{\scriptsize \par}

{\scriptsize{}~~~-{}-private}{\scriptsize \par}

{\scriptsize{}~~~-{}-message-file|-M~COMMENT-FILE}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{commit details}


\end{figure}


It's a very good idea to always put a comment (-comment or -m) text on any commit. This way you get documentation in the timeline.


\section{Maintenance commands}

These commands you will probably use less often since the actions they perform are not needed in normal operation. You will have to use them and referring here or to \textbf{fossil help} will probably be required before use. Some of them like new or clone are only needed when you start a repository. Others like rebuild or reconstruct are only needed to fix or update a repository. 


\subsection{new\index{new}}

This command is used to create a new repository. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~new}{\scriptsize \par}

{\scriptsize Usage:~fossil~new~?OPTIONS?~FILENAME}{\scriptsize \par}



{\scriptsize Create~a~repository~for~a~new~project~in~the~file~named~FILENAME.}{\scriptsize \par}

{\scriptsize This~command~is~distinct~from~\textquotedbl{}clone\textquotedbl{}.~~The~\textquotedbl{}clone\textquotedbl{}~command~makes}{\scriptsize \par}

{\scriptsize a~copy~of~an~existing~project.~~This~command~starts~a~new~project.}{\scriptsize \par}

{\scriptsize By~default,~your~current~login~name~is~used~to~create~the~default}{\scriptsize \par}

{\scriptsize admin~user.~This~can~be~overridden~using~the~-A|-{}-admin-user}{\scriptsize \par}

{\scriptsize parameter.}{\scriptsize \par}



{\scriptsize Options:}{\scriptsize \par}

{\scriptsize{}~~~-{}-admin-user|-A~USERNAME}{\scriptsize \par}

{\scriptsize{}~~~-{}-date-override~DATETIME}{\scriptsize \par}
\end{lyxcode}
\caption{new details}


\end{figure}


The file name specifies the new repository name. The options provided allow you to specify the admin user name if you want it to be different than your current login and the starting date if you want it to be different than now.


\subsection{clone\index{clone}}

The clone command is used to create your own local version of the master repository. If you are supporting multiple users via a network accessible version of the original repository (see Section\vref{sub:Server-Setup}), then this command will copy that repository to your machine. Also it will make a link between your copy and the master, so that changes made in your copy will be propagated to the master.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~clone}{\scriptsize \par}

{\scriptsize Usage:~fossil~clone~?OPTIONS?~URL~FILENAME}{\scriptsize \par}



{\scriptsize Make~a~clone~of~a~repository~specified~by~URL~in~the~local}{\scriptsize \par}

{\scriptsize file~named~FILENAME.~}{\scriptsize \par}



{\scriptsize By~default,~your~current~login~name~is~used~to~create~the~default}{\scriptsize \par}

{\scriptsize admin~user.~This~can~be~overridden~using~the~-A|-{}-admin-user}{\scriptsize \par}

{\scriptsize parameter.}{\scriptsize \par}

{\scriptsize Options:}{\scriptsize \par}



{\scriptsize{}~~~-{}-admin-user|-A~USERNAME}{\scriptsize \par}
\end{lyxcode}
\caption{clone details}


\end{figure}


Just like create you can specify the admin user for this clone with an option. The URL for the master repository is of the form:
\begin{lyxcode}
http://<user>:<password>@domain
\end{lyxcode}
Where \textbf{user} and \textbf{password} are for a valid user of the selected repository. It is best to check the path with a browser before doing the clone. Make sure you can reach it, for example the repository for this book is:
\begin{lyxcode}
http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end{lyxcode}
Putting that into a browser should get you the home page for this book. (See Figure \vref{fig:Web-access-to}). After you have verified that, then running the clone command should work. 

Don't forget (as I always do) to put in the file name for the local repository, (see FILENAME above)


\subsection{open\index{open}}

The open command is used to copy the files in a repository to a working directory. Doing this allows you to build or modify the product. The command also links this working directory to the repository so commits will go into the repository.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~open}{\scriptsize \par}

{\scriptsize Usage:~fossil~open~FILENAME~?VERSION?~?-{}-keep?}{\scriptsize \par}



{\scriptsize Open~a~connection~to~the~local~repository~in~FILENAME.~~A~checkout}{\scriptsize \par}

{\scriptsize for~the~repository~is~created~with~its~root~at~the~working~directory.}{\scriptsize \par}

{\scriptsize If~VERSION~is~specified~then~that~version~is~checked~out.~~Otherwise}{\scriptsize \par}

{\scriptsize the~latest~version~is~checked~out.~~No~files~other~than~\textquotedbl{}manifest\textquotedbl{}}{\scriptsize \par}

{\scriptsize and~\textquotedbl{}manifest.uuid\textquotedbl{}~are~modified~if~the~-{}-keep~option~is~present.}{\scriptsize \par}



{\scriptsize See~also~the~\textquotedbl{}close\textquotedbl{}~command.}{\scriptsize \par}
\end{lyxcode}
\caption{open details}


\end{figure}


If you have multiple users or have a branched repository then it is probably wise to specify the particular version you want. When you run this it will create all the files and directories in the repository in your work area. In addition the files \_FOSSIL\_, manifiest and manifest.uuid will be created by Fossil.


\subsection{close\index{close}}

This is the opposite of open, in that it breaks the connection between this working directory and the Fossil repository.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~close}{\scriptsize \par}

{\scriptsize Usage:~fossil~close~?-f|-{}-force?}{\scriptsize \par}



{\scriptsize The~opposite~of~\textquotedbl{}open\textquotedbl{}.~~Close~the~current~database~connection.}{\scriptsize \par}

{\scriptsize Require~a~-f~or~-{}-force~flag~if~there~are~unsaved~changed~in~the}{\scriptsize \par}

{\scriptsize current~check-out.}{\scriptsize \par}
\end{lyxcode}
\caption{close details}


\end{figure}


This is useful if you need to abandon the current working directory. Fossil will not let you do this if there are changes between the current directory and the repository. With the force flag you can explicitly cut the connection even if there are changes.


\subsection{version\index{version}}

This command is used to show the current version of fossil.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~version}{\scriptsize \par}

{\scriptsize Usage:~fossil~version}{\scriptsize \par}

{\scriptsize Print~the~source~code~version~number~for~the~fossil~executable.}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~version}{\scriptsize \par}

{\scriptsize This~is~fossil~version~{[}c56af61e5e{]}~2010-04-22~15:48:25~UTC}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{version details}


\end{figure}


The above figure shows the help and example of running the command. When you have problems with fossil it is very important to have this version information. You can then inquire of the Fossil news group about this problem and with the version information they can easily tell you if the problem is fixed already or is new.


\subsection{rebuild\index{rebuild}}

If you update your copy of Fossil you will want to run this command against all the repositories you have. This will automatically update them to the new version of Fossil.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rebuild}{\scriptsize \par}

{\scriptsize Usage:~fossil~rebuild~?REPOSITORY?}{\scriptsize \par}

{\scriptsize Reconstruct~the~named~repository~database~from~the~core}{\scriptsize \par}

{\scriptsize records.~~Run~this~command~after~updating~the~fossil}{\scriptsize \par}

{\scriptsize executable~in~a~way~that~changes~the~database~schema.}{\scriptsize \par}
\end{lyxcode}
\caption{rebuild details}


\end{figure}



\subsection{all\index{all}}

This command is actually a modifier and when used before certain commands will run them on all the repositories.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~all}{\scriptsize \par}

{\scriptsize Usage:~fossil~all~(list|ls|pull|push|rebuild|sync)}{\scriptsize \par}

{\scriptsize The~\textasciitilde{}/.fossil~file~records~the~location~of~all~repositories~for~a}{\scriptsize \par}

{\scriptsize user.~~This~command~performs~certain~operations~on~all~repositories}{\scriptsize \par}

{\scriptsize that~can~be~useful~before~or~after~a~period~of~disconnection~operation.}{\scriptsize \par}

{\scriptsize Available~operations~are:}{\scriptsize \par}

{\scriptsize{}~~~list~~~~~~~Display~the~location~of~all~repositories}{\scriptsize \par}

{\scriptsize{}~~~ls~~~~~~~~~An~alias~for~\textquotedbl{}list\textquotedbl{}}{\scriptsize \par}

{\scriptsize{}~~~pull~~~~~~~Run~a~\textquotedbl{}pull\textquotedbl{}~operation~on~all~repositories}{\scriptsize \par}

{\scriptsize{}~~~push~~~~~~~Run~a~\textquotedbl{}push\textquotedbl{}~on~all~repositories}{\scriptsize \par}

{\scriptsize{}~~~rebuild~~~~Rebuild~on~all~repositories}{\scriptsize \par}

{\scriptsize{}~~~sync~~~~~~~Run~a~\textquotedbl{}sync\textquotedbl{}~on~all~repositories}{\scriptsize \par}

{\scriptsize Repositories~are~automatically~added~to~the~set~of~known~repositories}{\scriptsize \par}

{\scriptsize when~one~of~the~following~commands~against~the~repository:~clone,~info,}{\scriptsize \par}

{\scriptsize pull,~push,~or~sync}{\scriptsize \par}
\end{lyxcode}
\caption{all details}


\end{figure}



\subsection{push\index{push}}

This command will push changes in the local repository to the master or remote repository.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~push}{\scriptsize \par}

{\scriptsize Usage:~fossil~push~?URL?~?options?}{\scriptsize \par}

{\scriptsize Push~changes~in~the~local~repository~over~into~a~remote~repository.}{\scriptsize \par}

{\scriptsize Use~the~\textquotedbl{}-R~REPO\textquotedbl{}~or~\textquotedbl{}-{}-repository~REPO\textquotedbl{}~command-line~options}{\scriptsize \par}

{\scriptsize to~specify~an~alternative~repository~file.}{\scriptsize \par}

{\scriptsize If~the~URL~is~not~specified,~then~the~URL~from~the~most~recent}{\scriptsize \par}

{\scriptsize clone,~push,~pull,~remote-url,~or~sync~command~is~used.}{\scriptsize \par}

{\scriptsize The~URL~specified~normally~becomes~the~new~\textquotedbl{}remote-url\textquotedbl{}~used~for}{\scriptsize \par}

{\scriptsize subsequent~push,~pull,~and~sync~operations.~~However,~the~\textquotedbl{}-{}-once\textquotedbl{}}{\scriptsize \par}

{\scriptsize command-line~option~makes~the~URL~a~one-time-use~URL~that~is~not}{\scriptsize \par}

{\scriptsize saved.}{\scriptsize \par}

{\scriptsize See~also:~clone,~pull,~sync,~remote-url}{\scriptsize \par}
\end{lyxcode}
\caption{push details}


\end{figure}



\subsection{pull\index{pull}}

This command will copy changes from the remote repository to the local repository. You could then use \textbf{update} to apply these changes to checked out files.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~pull}{\scriptsize \par}

{\scriptsize Usage:~fossil~pull~?URL?~?options?}{\scriptsize \par}

{\scriptsize Pull~changes~from~a~remote~repository~into~the~local~repository.}{\scriptsize \par}

{\scriptsize Use~the~\textquotedbl{}-R~REPO\textquotedbl{}~or~\textquotedbl{}-{}-repository~REPO\textquotedbl{}~command-line~options}{\scriptsize \par}

{\scriptsize to~specify~an~alternative~repository~file.}{\scriptsize \par}

{\scriptsize If~the~URL~is~not~specified,~then~the~URL~from~the~most~recent}{\scriptsize \par}

{\scriptsize clone,~push,~pull,~remote-url,~or~sync~command~is~used.}{\scriptsize \par}

{\scriptsize The~URL~specified~normally~becomes~the~new~\textquotedbl{}remote-url\textquotedbl{}~used~for}{\scriptsize \par}

{\scriptsize subsequent~push,~pull,~and~sync~operations.~~However,~the~\textquotedbl{}-{}-once\textquotedbl{}}{\scriptsize \par}

{\scriptsize command-line~option~makes~the~URL~a~one-time-use~URL~that~is~not}{\scriptsize \par}

{\scriptsize saved.}{\scriptsize \par}

{\scriptsize See~also:~clone,~push,~sync,~remote-url}{\scriptsize \par}


\end{lyxcode}
\caption{pull details}


\end{figure}



\subsection{sync\index{sync}}

This command is used to sync a remote copy with the original copy of the repository, it does both a push and pull. This can also be used to switch a local repository to a different main repository by specifying the URL of a remote repository. If you want to run the update command with -n where it does a dry run, this does not do a sync first so doing fossil sync then fossil update -n will do that for you.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~sync}{\scriptsize \par}

{\scriptsize Usage:~fossil~sync~?URL?~?options?}{\scriptsize \par}

{\scriptsize Synchronize~the~local~repository~with~a~remote~repository.~~This~is}{\scriptsize \par}

{\scriptsize the~equivalent~of~running~both~\textquotedbl{}push\textquotedbl{}~and~\textquotedbl{}pull\textquotedbl{}~at~the~same~time.}{\scriptsize \par}

{\scriptsize Use~the~\textquotedbl{}-R~REPO\textquotedbl{}~or~\textquotedbl{}-{}-repository~REPO\textquotedbl{}~command-line~options}{\scriptsize \par}

{\scriptsize to~specify~an~alternative~repository~file.}{\scriptsize \par}

{\scriptsize If~a~user-id~and~password~are~required,~specify~them~as~follows:}{\scriptsize \par}

{\scriptsize{}~~~~http://userid:password@www.domain.com:1234/path}{\scriptsize \par}

{\scriptsize If~the~URL~is~not~specified,~then~the~URL~from~the~most~recent~successful}{\scriptsize \par}

{\scriptsize clone,~push,~pull,~remote-url,~or~sync~command~is~used.}{\scriptsize \par}

{\scriptsize The~URL~specified~normally~becomes~the~new~\textquotedbl{}remote-url\textquotedbl{}~used~for}{\scriptsize \par}

{\scriptsize subsequent~push,~pull,~and~sync~operations.~~However,~the~\textquotedbl{}-{}-once\textquotedbl{}}{\scriptsize \par}

{\scriptsize command-line~option~makes~the~URL~a~one-time-use~URL~that~is~not}{\scriptsize \par}

{\scriptsize saved.}{\scriptsize \par}

{\scriptsize See~also:~~clone,~push,~pull,~remote-url}{\scriptsize \par}
\end{lyxcode}
\caption{sync details}


\end{figure}



\subsection{clean\index{clean}}

This call can be used to remove all the ``extra'' files in a source tree. This is useful if you wish to tidy up a source tree or to do a clean build.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~clean}{\scriptsize \par}

{\scriptsize Usage:~fossil~clean~?-{}-force?~?-{}-dotfiles?}{\scriptsize \par}

{\scriptsize Delete~all~\textquotedbl{}extra\textquotedbl{}~files~in~the~source~tree.~~\textquotedbl{}Extra\textquotedbl{}~files~are}{\scriptsize \par}

{\scriptsize files~that~are~not~officially~part~of~the~checkout.~~See~also}{\scriptsize \par}

{\scriptsize the~\textquotedbl{}extra\textquotedbl{}~command.~This~operation~cannot~be~undone.~}{\scriptsize \par}

{\scriptsize You~will~be~prompted~before~removing~each~file.~If~you~are}{\scriptsize \par}

{\scriptsize sure~you~wish~to~remove~all~\textquotedbl{}extra\textquotedbl{}~files~you~can~specify~the}{\scriptsize \par}

{\scriptsize optional~-{}-force~flag~and~no~prompts~will~be~issued.}{\scriptsize \par}

{\scriptsize Files~and~subdirectories~whose~names~begin~with~\textquotedbl{}.\textquotedbl{}~are}{\scriptsize \par}

{\scriptsize normally~ignored.~~They~are~included~if~the~\textquotedbl{}-{}-dotfiles\textquotedbl{}~option}{\scriptsize \par}

{\scriptsize is~used.}{\scriptsize \par}
\end{lyxcode}
\caption{clean details}


\end{figure}



\subsection{branch\index{branch}}

This command is used if you want to create or list branches in a repository. Previously we discussed forks ( See Section \vref{sub:Complications}); branches are the same idea but under user control. This would be where you have version 1.0 of something but want to branch off version 2.0 to add new features but want to keep a 1.0 branch for maintenance.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~branch}{\scriptsize \par}

{\scriptsize Usage:~fossil~branch~SUBCOMMAND~...~?-R|-{}-repository~FILE?}{\scriptsize \par}

{\scriptsize Run~various~subcommands~on~the~branches~of~the~open~repository~or}{\scriptsize \par}

{\scriptsize of~the~repository~identified~by~the~-R~or~-{}-repository~option.}{\scriptsize \par}

{\scriptsize{}~~~fossil~branch~new~BRANCH-NAME~BASIS~?-bgcolor~COLOR?~}{\scriptsize \par}

{\scriptsize{}~~~~~~~Create~a~new~branch~BRANCH-NAME~off~of~check-in~BASIS.}{\scriptsize \par}

{\scriptsize{}~~~~~~~You~can~optionally~give~the~branch~a~default~color.}{\scriptsize \par}

{\scriptsize{}~~~fossil~branch~list}{\scriptsize \par}

{\scriptsize{}~~~~~~~List~all~branches}{\scriptsize \par}
\end{lyxcode}
\caption{branch details}


\end{figure}



\subsection{merge\index{merge}}

This command does the opposite of branch, it brings two branches together.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~merge}{\scriptsize \par}

{\scriptsize Usage:~fossil~merge~{[}-{}-cherrypick{]}~{[}-{}-backout{]}~VERSION}{\scriptsize \par}

{\scriptsize The~argument~is~a~version~that~should~be~merged~into~the~current}{\scriptsize \par}

{\scriptsize checkout.~~All~changes~from~VERSION~back~to~the~nearest~common}{\scriptsize \par}

{\scriptsize ancestor~are~merged.~~Except,~if~either~of~the~-{}-cherrypick~or}{\scriptsize \par}

{\scriptsize -{}-backout~options~are~used~only~the~changes~associated~with~the}{\scriptsize \par}

{\scriptsize single~check-in~VERSION~are~merged.~~The~-{}-backout~option~causes}{\scriptsize \par}

{\scriptsize the~changes~associated~with~VERSION~to~be~removed~from~the~current}{\scriptsize \par}

{\scriptsize checkout~rather~than~added.}{\scriptsize \par}

{\scriptsize Only~file~content~is~merged.~~The~result~continues~to~use~the}{\scriptsize \par}

{\scriptsize file~and~directory~names~from~the~current~checkout~even~if~those}{\scriptsize \par}

{\scriptsize names~might~have~been~changed~in~the~branch~being~merged~in.}{\scriptsize \par}

{\scriptsize Other~options:}{\scriptsize \par}

{\scriptsize{}~~-{}-detail~~~~~~~~~~~~~~~~Show~additional~details~of~the~merge}{\scriptsize \par}

{\scriptsize{}~~-{}-binary~GLOBPATTERN~~~~Treat~files~that~match~GLOBPATTERN~as~binary}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~~~~~~~and~do~not~try~to~merge~parallel~changes.~~This}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~~~~~~~option~overrides~the~\textquotedbl{}binary-glob\textquotedbl{}~setting.}{\scriptsize \par}
\end{lyxcode}
\caption{merge details}


\end{figure}



\subsection{tag\index{tag}}

This command can be used to control ``tags'' which are attributes added to any entry in the time line. You can also add/delete/control these tags from the UI by going into the timeline, picking an entry then doing an edit. See Figure \vref{fig:Remove-Leaf}. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~tag}{\scriptsize \par}

{\scriptsize Usage:~fossil~tag~SUBCOMMAND~...}{\scriptsize \par}

{\scriptsize Run~various~subcommands~to~control~tags~and~properties}{\scriptsize \par}

{\scriptsize{}~~~~fossil~tag~add~?-{}-raw?~?-{}-propagate?~TAGNAME~CHECK-IN~?VALUE?}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Add~a~new~tag~or~property~to~CHECK-IN.~The~tag~will}{\scriptsize \par}

{\scriptsize{}~~~~~~~~be~usable~instead~of~a~CHECK-IN~in~commands~such~as}{\scriptsize \par}

{\scriptsize{}~~~~~~~~update~and~merge.~~If~the~-{}-propagate~flag~is~present,}{\scriptsize \par}

{\scriptsize{}~~~~~~~~the~tag~value~propagates~to~all~descendants~of~CHECK-IN}{\scriptsize \par}

{\scriptsize{}~~~~fossil~tag~cancel~?-{}-raw?~TAGNAME~CHECK-IN}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Remove~the~tag~TAGNAME~from~CHECK-IN,~and~also~remove}{\scriptsize \par}

{\scriptsize{}~~~~~~~~the~propagation~of~the~tag~to~any~descendants.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~tag~find~?-{}-raw?~TAGNAME}{\scriptsize \par}

{\scriptsize{}~~~~~~~~List~all~check-ins~that~use~TAGNAME}{\scriptsize \par}

{\scriptsize{}~~~~fossil~tag~list~?-{}-raw?~?CHECK-IN?}{\scriptsize \par}

{\scriptsize{}~~~~~~~~List~all~tags,~or~if~CHECK-IN~is~supplied,~list}{\scriptsize \par}

{\scriptsize{}~~~~~~~~all~tags~and~their~values~for~CHECK-IN.}{\scriptsize \par}

{\scriptsize The~option~-{}-raw~allows~the~manipulation~of~all~types~of~tags}{\scriptsize \par}

{\scriptsize used~for~various~internal~purposes~in~fossil.~It~also~shows}{\scriptsize \par}

{\scriptsize \textquotedbl{}cancel\textquotedbl{}~tags~for~the~\textquotedbl{}find\textquotedbl{}~and~\textquotedbl{}list\textquotedbl{}~subcommands.~You~should}{\scriptsize \par}

{\scriptsize not~use~this~option~to~make~changes~unless~you~are~sure~what}{\scriptsize \par}

{\scriptsize you~are~doing.}{\scriptsize \par}

{\scriptsize If~you~need~to~use~a~tagname~that~might~be~confused~with}{\scriptsize \par}

{\scriptsize a~hexadecimal~baseline~or~artifact~ID,~you~can~explicitly}{\scriptsize \par}

{\scriptsize disambiguate~it~by~prefixing~it~with~\textquotedbl{}tag:\textquotedbl{}.~For~instance:}{\scriptsize \par}

{\scriptsize{}~~fossil~update~decaf}{\scriptsize \par}

{\scriptsize will~be~taken~as~an~artifact~or~baseline~ID~and~fossil~will}{\scriptsize \par}

{\scriptsize probably~complain~that~no~such~revision~was~found.~However}{\scriptsize \par}

{\scriptsize{}~~fossil~update~tag:decaf}{\scriptsize \par}

{\scriptsize will~assume~that~\textquotedbl{}decaf\textquotedbl{}~is~a~tag/branch~name.}{\scriptsize \par}
\end{lyxcode}
\caption{tag details}


\end{figure}



\subsection{settings\index{settings}}

This command is used to set or unset a number of properties for fossil.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~settings}{\scriptsize \par}

{\scriptsize COMMAND:~settings}{\scriptsize \par}

{\scriptsize COMMAND:~unset}{\scriptsize \par}

{\scriptsize fossil~setting~?PROPERTY?~?VALUE?~?-global?}{\scriptsize \par}

{\scriptsize fossil~unset~PROPERTY~?-global?}{\scriptsize \par}

{\scriptsize The~\textquotedbl{}setting\textquotedbl{}~command~with~no~arguments~lists~all~properties~and~their}{\scriptsize \par}

{\scriptsize values.~~With~just~a~property~name~it~shows~the~value~of~that~property.}{\scriptsize \par}

{\scriptsize With~a~value~argument~it~changes~the~property~for~the~current~repository.}{\scriptsize \par}

{\scriptsize The~\textquotedbl{}unset\textquotedbl{}~command~clears~a~property~setting.}{\scriptsize \par}

{\scriptsize{}~~~auto-captcha~~~~~If~enabled,~the~Login~page~will~provide~a~button}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~which~uses~JavaScript~to~fill~out~the~captcha~for}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~the~\textquotedbl{}anonymous\textquotedbl{}~user.~(Most~bots~cannot~use~JavaScript.)}{\scriptsize \par}

{\scriptsize{}~~~autosync~~~~~~~~~If~enabled,~automatically~pull~prior~to~commit}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~or~update~and~automatically~push~after~commit~or}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~tag~or~branch~creation.~~If~the~the~value~is~\textquotedbl{}pullonly\textquotedbl{}}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~then~only~pull~operations~occur~automatically.}{\scriptsize \par}

{\scriptsize{}~~~binary-glob~~~~~~The~VALUE~is~a~comma-separated~list~of~GLOB~patterns}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~that~should~be~treated~as~binary~files~for~merging}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~purposes.~~Example:~~~{*}.xml}{\scriptsize \par}

{\scriptsize{}~~~clearsign~~~~~~~~When~enabled,~fossil~will~attempt~to~sign~all~commits}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~with~gpg.~~When~disabled~(the~default),~commits~will}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~be~unsigned.}{\scriptsize \par}

{\scriptsize{}~~~diff-command~~~~~External~command~to~run~when~performing~a~diff.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~If~undefined,~the~internal~text~diff~will~be~used.}{\scriptsize \par}

{\scriptsize{}~~~dont-push~~~~~~~~Prevent~this~repository~from~pushing~from~client~to}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~server.~~Useful~when~setting~up~a~private~branch.}{\scriptsize \par}

{\scriptsize{}~~~editor~~~~~~~~~~~Text~editor~command~used~for~check-in~comments.}{\scriptsize \par}

{\scriptsize{}~~~gdiff-command~~~~External~command~to~run~when~performing~a~graphical}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~diff.~If~undefined,~text~diff~will~be~used.}{\scriptsize \par}

{\scriptsize{}~~~http-port~~~~~~~~The~TCP/IP~port~number~to~use~by~the~\textquotedbl{}server\textquotedbl{}}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~and~\textquotedbl{}ui\textquotedbl{}~commands.~~Default:~8080}{\scriptsize \par}

{\scriptsize{}~~~ignore-glob~~~~~~The~VALUE~is~a~comma-separated~list~of~GLOB~patterns}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~specifying~files~that~the~\textquotedbl{}extra\textquotedbl{}~command~will~ignore.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~Example:~~{*}.o,{*}.obj,{*}.exe}{\scriptsize \par}

{\scriptsize{}~~~localauth~~~~~~~~If~enabled,~require~that~HTTP~connections~from}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~127.0.0.1~be~authenticated~by~password.~~If}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~false,~all~HTTP~requests~from~localhost~have}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~unrestricted~access~to~the~repository.}{\scriptsize \par}

{\scriptsize{}~~~mtime-changes~~~~Use~file~modification~times~(mtimes)~to~detect~when}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~files~have~been~modified.~~(Default~\textquotedbl{}on\textquotedbl{}.)}{\scriptsize \par}

{\scriptsize{}~~~pgp-command~~~~~~Command~used~to~clear-sign~manifests~at~check-in.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~The~default~is~\textquotedbl{}gpg~-{}-clearsign~-o~\textquotedbl{}.}{\scriptsize \par}

{\scriptsize{}~~~proxy~~~~~~~~~~~~URL~of~the~HTTP~proxy.~~If~undefined~or~\textquotedbl{}off\textquotedbl{}~then}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~the~\textquotedbl{}http\_proxy\textquotedbl{}~environment~variable~is~consulted.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~If~the~http\_proxy~environment~variable~is~undefined}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~then~a~direct~HTTP~connection~is~used.}{\scriptsize \par}

{\scriptsize{}~~~web-browser~~~~~~A~shell~command~used~to~launch~your~preferred}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~web~browser~when~given~a~URL~as~an~argument.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~Defaults~to~\textquotedbl{}start\textquotedbl{}~on~windows,~\textquotedbl{}open\textquotedbl{}~on~Mac,}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~~~~~and~\textquotedbl{}firefox\textquotedbl{}~on~Unix.}{\scriptsize \par}
\end{lyxcode}
\caption{settings details}


\end{figure}



\section{Miscellaneous }

These are commands that don't seem to fit in any category but are useful. 


\subsection{zip\index{zip}}

You can do what this command does from the web based user interface. In Figure \vref{fig:Timeline-Detail} you can download a ZIP archive of the particular version of the files. This command lets you do it from the command line.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~zip}{\scriptsize \par}

{\scriptsize Usage:~fossil~zip~VERSION~OUTPUTFILE~{[}-{}-name~DIRECTORYNAME{]}}{\scriptsize \par}

{\scriptsize Generate~a~ZIP~archive~for~a~specified~version.~~If~the~-{}-name~option~is}{\scriptsize \par}

{\scriptsize used,~it~argument~becomes~the~name~of~the~top-level~directory~in~the}{\scriptsize \par}

{\scriptsize resulting~ZIP~archive.~~If~-{}-name~is~omitted,~the~top-level~directory}{\scriptsize \par}

{\scriptsize named~is~derived~from~the~project~name,~the~check-in~date~and~time,~and}{\scriptsize \par}

{\scriptsize the~artifact~ID~of~the~check-in.}{\scriptsize \par}
\end{lyxcode}
\caption{zip detail}


\end{figure}



\subsection{user\index{user}}

This command lets you modify user information. Again this is a command line duplication of what you can do from the user interface in the browser, see Figure \vref{fig:New-Editor-user}.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~user}{\scriptsize \par}

{\scriptsize Usage:~fossil~user~SUBCOMMAND~...~~?-R|-{}-repository~FILE?}{\scriptsize \par}

{\scriptsize Run~various~subcommands~on~users~of~the~open~repository~or~of}{\scriptsize \par}

{\scriptsize the~repository~identified~by~the~-R~or~-{}-repository~option.}{\scriptsize \par}

{\scriptsize{}~~~fossil~user~capabilities~USERNAME~?STRING?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Query~or~set~the~capabilities~for~user~USERNAME}{\scriptsize \par}

{\scriptsize{}~~~fossil~user~default~?USERNAME?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Query~or~set~the~default~user.~~The~default~user~is~the}{\scriptsize \par}

{\scriptsize{}~~~~~~~user~for~command-line~interaction.}{\scriptsize \par}

{\scriptsize{}~~~fossil~user~list}{\scriptsize \par}

{\scriptsize{}~~~~~~~List~all~users~known~to~the~repository}{\scriptsize \par}

{\scriptsize{}~~~fossil~user~new~?USERNAME?~?CONTACT-INFO?~?PASSWORD?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Create~a~new~user~in~the~repository.~~Users~can~never~be}{\scriptsize \par}

{\scriptsize{}~~~~~~~deleted.~~They~can~be~denied~all~access~but~they~must~continue}{\scriptsize \par}

{\scriptsize{}~~~~~~~to~exist~in~the~database.}{\scriptsize \par}

{\scriptsize{}~~~fossil~user~password~USERNAME~?PASSWORD?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Change~the~web~access~password~for~a~user.}{\scriptsize \par}
\end{lyxcode}
\caption{user detail}


\end{figure}



\subsection{finfo\index{finfo}}

This command will print the history of any particular file. This can be useful if you need this history in some other system. You can pass this text file to the other system which can than parse and use the data.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~finfo}{\scriptsize \par}

{\scriptsize Usage:~fossil~finfo~FILENAME}{\scriptsize \par}

{\scriptsize Print~the~change~history~for~a~single~file.}{\scriptsize \par}

{\scriptsize The~\textquotedbl{}-{}-limit~N\textquotedbl{}~and~\textquotedbl{}-{}-offset~P\textquotedbl{}~options~limits~the~output~to~the~first}{\scriptsize \par}

{\scriptsize N~changes~after~skipping~P~changes.}{\scriptsize \par}
\end{lyxcode}
\caption{finfo detail}


\end{figure}


An example would be to run it on the outline.txt file in our book directory:
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~}\textbf{\scriptsize finfo~outline.txt}{\scriptsize \par}

{\scriptsize History~of~outline.txt}{\scriptsize \par}

{\scriptsize 2010-05-17~{[}0272dc0169{]}~Finished~maintenance~commands~(user:~jim,~artifact:}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~{[}25b6e38e97{]})}{\scriptsize \par}

{\scriptsize 2010-05-12~{[}5e5c0f7d55{]}~End~of~day~commit~(user:~jim,~artifact:~{[}d1a1d31fbd{]})}{\scriptsize \par}

{\scriptsize 2010-05-10~{[}e924ca3525{]}~End~of~day~update~(user:~jim,~artifact:~{[}7cd19079a1{]})}{\scriptsize \par}

{\scriptsize 2010-05-09~{[}0abb95b046{]}~Intermediate~commit,~not~done~with~basic~commands}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~(user:~jim,~artifact:~{[}6f7bcd48b9{]})}{\scriptsize \par}

{\scriptsize 2010-05-07~{[}6921e453cd{]}~Update~outline~\&~book~corrections~(user:~jim,}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~artifact:~{[}4eff85c793{]})}{\scriptsize \par}

{\scriptsize 2010-05-03~{[}158492516c{]}~Moved~to~clone~repository~(user:~jim,~artifact:}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~{[}23b729cb66{]})}{\scriptsize \par}

{\scriptsize 2010-05-03~{[}1a403c87fc{]}~Update~before~moving~to~server~(user:~jim,~artifact:}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~{[}706a9d394d{]})}{\scriptsize \par}

{\scriptsize 2010-04-30~{[}fa5b9247bd{]}~Working~on~chapter~1~(user:~jim,~artifact:}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~{[}7bb188f0c6{]})}{\scriptsize \par}

{\scriptsize 2010-04-29~{[}51be6423a3{]}~Update~outline~(user:~jim,~artifact:~{[}7cd39dfa06{]})}{\scriptsize \par}

{\scriptsize 2010-04-27~{[}39bc728527{]}~{[}1665c78d94{]}~Ticket~Use~(user:~jim,~artifact:}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~{[}1f82aaf41c{]})}{\scriptsize \par}

{\scriptsize 2010-04-26~{[}497b93858f{]}~Update~to~catch~changes~in~outline~(user:~jim,}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~artifact:~{[}b870231e48{]})}{\scriptsize \par}

{\scriptsize 2010-04-25~{[}8fa0708186{]}~Initial~Commit~(user:~jim,~artifact:~{[}34a460a468{]})}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}

\subsection{timeline\index{timeline}}

This prints out the timeline of the project in various ways. The command would be useful if you were building a GUI front end for Fossil and wanted to display the timeline. You could issue this command and get the result back and display it in your UI. There are a number of options in the command to control the listing.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~timeline}{\scriptsize \par}

{\scriptsize Usage:~fossil~timeline~?WHEN?~?BASELINE|DATETIME?~?-n~N?~?-t~TYPE?}{\scriptsize \par}

{\scriptsize Print~a~summary~of~activity~going~backwards~in~date~and~time}{\scriptsize \par}

{\scriptsize specified~or~from~the~current~date~and~time~if~no~arguments}{\scriptsize \par}

{\scriptsize are~given.~~Show~as~many~as~N~(default~20)~check-ins.~~The}{\scriptsize \par}

{\scriptsize WHEN~argument~can~be~any~unique~abbreviation~of~one~of~these}{\scriptsize \par}

{\scriptsize keywords:}{\scriptsize \par}

{\scriptsize{}~~~~before}{\scriptsize \par}

{\scriptsize{}~~~~after}{\scriptsize \par}

{\scriptsize{}~~~~descendants~|~children}{\scriptsize \par}

{\scriptsize{}~~~~ancestors~|~parents}{\scriptsize \par}

{\scriptsize The~BASELINE~can~be~any~unique~prefix~of~4~characters~or~more.}{\scriptsize \par}

{\scriptsize The~DATETIME~should~be~in~the~ISO8601~format.~~For}{\scriptsize \par}

{\scriptsize examples:~\textquotedbl{}2007-08-18~07:21:21\textquotedbl{}.~~You~can~also~say~\textquotedbl{}current\textquotedbl{}}{\scriptsize \par}

{\scriptsize for~the~current~version~or~\textquotedbl{}now\textquotedbl{}~for~the~current~time.}{\scriptsize \par}

{\scriptsize The~optional~TYPE~argument~may~any~types~supported~by~the~/timeline}{\scriptsize \par}

{\scriptsize page.~For~example:}{\scriptsize \par}

{\scriptsize{}~~~~w~~=~wiki~commits~only}{\scriptsize \par}

{\scriptsize{}~~~~ci~=~file~commits~only}{\scriptsize \par}

{\scriptsize{}~~~~t~~=~tickets~only}{\scriptsize \par}
\end{lyxcode}
\caption{timeline detail}


\end{figure}



\subsection{wiki\index{wiki}}

This command allows you to have command line control of the wiki. Again this is useful if you were writing a shell to control Fossil or wanted to add a number of computer generated pages to the Wiki.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~wiki}{\scriptsize \par}

{\scriptsize Usage:~fossil~wiki~(export|create|commit|list)~WikiName}{\scriptsize \par}

{\scriptsize Run~various~subcommands~to~work~with~wiki~entries.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~export~PAGENAME~?FILE?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Sends~the~latest~version~of~the~PAGENAME~wiki}{\scriptsize \par}

{\scriptsize{}~~~~~~~entry~to~the~given~file~or~standard~output.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~commit~PAGENAME~?FILE?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Commit~changes~to~a~wiki~page~from~FILE~or~from~standard}{\scriptsize \par}

{\scriptsize{}~~~~~~~input.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~create~PAGENAME~?FILE?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Create~a~new~wiki~page~with~initial~content~taken~from}{\scriptsize \par}

{\scriptsize{}~~~~~~~FILE~or~from~standard~input.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~list}{\scriptsize \par}

{\scriptsize{}~~~~~~~Lists~all~wiki~entries,~one~per~line,~ordered}{\scriptsize \par}

{\scriptsize{}~~~~~~~case-insentively~by~name.}{\scriptsize \par}

{\scriptsize TODOs:}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~export~?-u~ARTIFACT?~WikiName~?FILE?}{\scriptsize \par}

{\scriptsize{}~~~~~~~Outputs~the~selected~version~of~WikiName.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~delete~?-m~MESSAGE?~WikiName}{\scriptsize \par}

{\scriptsize{}~~~~~~~The~same~as~deleting~a~file~entry,~but~i~don't~know~if~fossil}{\scriptsize \par}

{\scriptsize{}~~~~~~~supports~a~commit~message~for~Wiki~entries.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~?-u?~?-d?~?-s={[}|{]}?~list}{\scriptsize \par}

{\scriptsize{}~~~~~~~Lists~the~artifact~ID~and/or~Date~of~last~change~along~with}{\scriptsize \par}

{\scriptsize{}~~~~~~~each~entry~name,~delimited~by~the~-s~char.}{\scriptsize \par}

{\scriptsize{}~~~~fossil~wiki~diff~?ARTIFACT?~?-f~infile{[}=stdin{]}?~EntryName}{\scriptsize \par}

{\scriptsize{}~~~~~~~Diffs~the~local~copy~of~a~page~with~a~given~version~(defaulting}{\scriptsize \par}

{\scriptsize{}~~~~~~~to~the~head~version).}{\scriptsize \par}
\end{lyxcode}
\caption{wiki detail}


\end{figure}



\section{Advanced}

These are commands that you will rarely have to use. These are functions that are needed to do very complicated things with Fossil. If you have to use these you are probably way beyond the audience for this book.


\subsection{scrub\index{scrub}}

This is used to removed sensitive information like passwords from a repository. This allows you to then send the whole repository to someone else for their use.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~scrub}{\scriptsize \par}

{\scriptsize COMMAND:~scrub}{\scriptsize \par}

{\scriptsize fossil~scrub~{[}-{}-verily{]}~{[}-{}-force{]}~{[}REPOSITORY{]}}{\scriptsize \par}

{\scriptsize The~command~removes~sensitive~information~(such~as~passwords)~from~a}{\scriptsize \par}

{\scriptsize repository~so~that~the~repository~can~be~sent~to~an~untrusted~reader.}{\scriptsize \par}

{\scriptsize By~default,~only~passwords~are~removed.~~However,~if~the~-{}-verily~option}{\scriptsize \par}

{\scriptsize is~added,~then~private~branches,~concealed~email~addresses,~IP}{\scriptsize \par}

{\scriptsize addresses~of~correspondents,~and~similar~privacy-sensitive~fields}{\scriptsize \par}

{\scriptsize are~also~purged.}{\scriptsize \par}

{\scriptsize This~command~permanently~deletes~the~scrubbed~information.~~The~effects}{\scriptsize \par}

{\scriptsize of~this~command~are~irreversible.~~Use~with~caution.}{\scriptsize \par}

{\scriptsize The~user~is~prompted~to~confirm~the~scrub~unless~the~-{}-force~option}{\scriptsize \par}

{\scriptsize is~used.}{\scriptsize \par}
\end{lyxcode}
\caption{scrub detail}


\end{figure}



\subsection{search\index{search}}

This is used to search the timeline entries for a pattern. This can also be done in your browser on the timeline page.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~search}{\scriptsize \par}

{\scriptsize COMMAND:~search}{\scriptsize \par}

{\scriptsize fossil~search~pattern...}{\scriptsize \par}

{\scriptsize Search~for~timeline~entries~matching~the~pattern.}{\scriptsize \par}
\end{lyxcode}
\caption{search detail}


\end{figure}



\subsection{sha1sum\index{sha1sum}}

This can compute the sha1 value for a particular file. These sums are the labels that Fossil uses on all objects and should be unique for any file.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~sha1sum}{\scriptsize \par}

{\scriptsize COMMAND:~sha1sum}{\scriptsize \par}

{\scriptsize fossil~sha1sum~FILE...}{\scriptsize \par}

{\scriptsize Compute~an~SHA1~checksum~of~all~files~named~on~the~command-line.}{\scriptsize \par}

{\scriptsize If~an~file~is~named~\textquotedbl{}-\textquotedbl{}~then~take~its~content~from~standard~input.}{\scriptsize \par}
\end{lyxcode}
\caption{sha1sum detail}


\end{figure}



\subsection{rstats\index{rstats}}

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rstats}{\scriptsize \par}

{\scriptsize Usage:~fossil~rstats}{\scriptsize \par}

{\scriptsize Deliver~a~report~of~the~repository~statistics~for~the}{\scriptsize \par}

{\scriptsize current~checkout.}{\scriptsize \par}
\end{lyxcode}
\caption{rstats detail}


\end{figure}


For example, running it on the Fossil Book checkout:
\begin{lyxcode}
{[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~rstats}

~Number~of~Artifacts:~137

~~59~full~text~+~78~delta~blobs

~278961~bytes~average,~38217738~bytes~total

~~Number~Of~Checkins:~26

~~~~~Number~Of~Files:~37

Number~Of~Wiki~Pages:~2

~~~Number~Of~Tickets:~6

~Duration~Of~Project:~23~days
\end{lyxcode}

\subsection{configuration\index{configuration}}

This command allows you to save or load a custom configuration of Fossil.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~}\textbf{\scriptsize help~configuration}{\scriptsize \par}

{\scriptsize Usage:~fossil~configure~METHOD~...}{\scriptsize \par}

{\scriptsize Where~METHOD~is~one~of:~export~import~merge~pull~push~reset.~~All~methods}{\scriptsize \par}

{\scriptsize accept~the~-R~or~-{}-repository~option~to~specific~a~repository.}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~export~AREA~FILENAME}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Write~to~FILENAME~exported~configuration~information~for~AREA.}{\scriptsize \par}

{\scriptsize{}~~~~~~~~AREA~can~be~one~of:~~all~ticket~skin~project}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~import~FILENAME}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Read~a~configuration~from~FILENAME,~overwriting~the~current}{\scriptsize \par}

{\scriptsize{}~~~~~~~~configuration.}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~merge~FILENAME}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Read~a~configuration~from~FILENAME~and~merge~its~values~into}{\scriptsize \par}

{\scriptsize{}~~~~~~~~the~current~configuration.~~Existing~values~take~priority~over}{\scriptsize \par}

{\scriptsize{}~~~~~~~~values~read~from~FILENAME.}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~pull~AREA~?URL?}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Pull~and~install~the~configuration~from~a~different~server}{\scriptsize \par}

{\scriptsize{}~~~~~~~~identified~by~URL.~~If~no~URL~is~specified,~then~the~default}{\scriptsize \par}

{\scriptsize{}~~~~~~~~server~is~used.~}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~push~AREA~?URL?}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Push~the~local~configuration~into~the~remote~server~identified}{\scriptsize \par}

{\scriptsize{}~~~~~~~~by~URL.~~Admin~privilege~is~required~on~the~remote~server~for}{\scriptsize \par}

{\scriptsize{}~~~~~~~~this~to~work.}{\scriptsize \par}

{\scriptsize{}~~~fossil~configuration~reset~AREA}{\scriptsize \par}

{\scriptsize{}~~~~~~~~Restore~the~configuration~to~the~default.~~AREA~as~above.}{\scriptsize \par}

{\scriptsize WARNING:~Do~not~import,~merge,~or~pull~configurations~from~an~untrusted}{\scriptsize \par}

{\scriptsize source.~~The~inbound~configuration~is~not~checked~for~safety~and~can}{\scriptsize \par}

{\scriptsize introduce~security~vulnerabilities.}{\scriptsize \par}
\end{lyxcode}
\caption{configuration detail}


\end{figure}



\subsection{descendants\index{descendants}}

This is used to find where the checked out files are in the time line.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~descendants}{\scriptsize \par}

{\scriptsize Usage:~fossil~descendants~?BASELINE-ID?}{\scriptsize \par}

{\scriptsize Find~all~leaf~descendants~of~the~baseline~specified~or~if~the~argument}{\scriptsize \par}

{\scriptsize is~omitted,~of~the~baseline~currently~checked~out.}{\scriptsize \par}


\end{lyxcode}
\caption{descendants detail}


\end{figure}

\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
\begin{itemize}
\item Marilyn Noz - Editor
\item Wolfgang Stumvoll - Fossil Merge use and Windows use
\item Paul Ruizendaal - TH 1 Scripting Language manual
\item javalinBCD@gmail.com - found bugs
\item arnel\_legaspi@msn.com - found bugs
\end{itemize}
\newpage{}

\chapter{Forks \& Branches}


\section{Introduction}

This chapter will cover forking and branching in Fossil. Forking is where you unintentially create two places to check into a repository. Branching is where you intentially do this because you want to maintain two or more versions of the code in the same repository. We illustrated forking and it's solutions in Section \vref{sub:Complications}. If, instead of fixing (merging) the file then doing the commit, we forced the commit, Fossil would fork the repository.

Forking is something to avoid because it creates two checkin paths for the code. Thus different users will be on different paths and can check in contradictory changes. Branches on the other hand are forks that you desire. These occur when you want to have two different versions of the code base in development at the same time. This was described in \vref{versioning} where you have a production verison of code under maintenance and a development version both served from the same repository. In this case development changes should only be checked into the development branch. Maintanence changes might have to be checked into both.

Instead of using the book repository for these examples we will use a JSON\cite{JSON}parser program that has a number of files and documentation. This will make it simpler to illustrate branching and tagging.

There is a good discussion of these topics on the Fossil Web site \url{http://www.fossil-scm.org/index.html/doc/tip/www/branching.wiki}.


\section{Forks, Branch \& Merge}

In this case the JSON code has just been placed in Fossil and two developers check out copies to work on. Jim wants to fix a number of compiler warnings that appear and Marilyn wants to fix the documentation. In both cases they proceeed as shown in Chapter \vref{sec:Multiple-Users}. The JSON code has been placed in a distributed location, each of them clones the repository, and opens a working copy of the code.


\subsection{Marilyn's Actions}

She looks through the documentation and finds a number of problems and fixes them (the documentation uses \LyX{} and PDF's). When she is satisfied with what she has done, she checks the current version of the documentation in:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Simple_Merge/sm_Marilyn}

\caption{\label{fig:Marilyn's-work}Marilyn's work}
\end{figure}



\subsection{Jim's Actions}

At the same time, Jim gets a working copy of version {[}6edbaf5fa8{]} of the code, puts in a ticket {[}d23bf4bbbb{]} as shown in Figure \ref{fig:Marilyn's-work}. After fixing the warnings, Jim is done and goes to commit. He does this AFTER Marilyn has done her commit.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize 551~jsonp>~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}d23bf4bbbb{]}~Remove~warnings\textquotedbl{}}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~~874~~~~~~~~~19~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~339~bytes~sent,~771~bytes~received}{\footnotesize \par}

{\footnotesize fossil:~would~fork.~~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\footnotesize \par}

{\footnotesize 552~jsonp>~}{\footnotesize \par}
\end{lyxcode}
\caption{Jim's commit attempt}


\end{figure}


At this point Fossil recognizes that Marilyn has changed the repository (she updated the documentation) but Jim does not have these changes because he checked out an earlier version of the code. Jim says he \textbf{must} get his changes in so he does a FORCE to force fossil to accept the commit.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize 552~jsonp>~}\textbf{\footnotesize fossil}{\footnotesize{}~}\textbf{\footnotesize commit~-m~\textquotedbl{}{[}d23bf4bbbb{]}~Remove~warnings\textquotedbl{}~-f}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~~874~~~~~~~~~19~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~338~bytes~sent,~771~bytes~received}{\footnotesize \par}

{\footnotesize New\_Version:~1beab955418a942ab9953c4865109ff46cbbd691}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~2646~~~~~~~~~25~~~~~~~~~~0~~~~~~~~~~4}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1058~~~~~~~~~23~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1498~bytes~sent,~864~bytes~received}{\footnotesize \par}

{\footnotesize {*}{*}{*}{*}~warning:~a~fork~has~occurred~{*}{*}{*}{*}{*}}{\footnotesize \par}
\end{lyxcode}
\caption{Forcing the commit}


\end{figure}


Looking at the timeline Jim sees this:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Simple_Merge/sm_jim_fork}

\caption{Repository Fork}


\end{figure}


Not good, there are two \textbf{Leaf}'s and Marilyn would commit code to her fork and Jim would be commiting code to his. So Jim must fix this by merging the code. Jim wants to merge versions {[}b72e96832e{]} of Marilyn and his {[}1beab85441{]}.


\subsection{Fixing the fork}

So Jim who's checked out code is from Leaf {[}1beab85441{]} does a merge with Marilyn's leaf {[}b72e96832e{]} like so:

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize 556~jsonp>~}\textbf{\footnotesize fossil~merge~b72e96832e}{\footnotesize \par}

{\footnotesize UPDATE~docs/qdj.lyx}{\footnotesize \par}

{\footnotesize UPDATE~docs/qdj.pdf}{\footnotesize \par}

{\footnotesize 557~jsonp>~}\textbf{\footnotesize fossil~status}{\footnotesize \par}

{\footnotesize repository:~~~/Users/jschimpf/Public/FOSSIL/jsonp.fossil}{\footnotesize \par}

{\footnotesize local-root:~~~/Users/jschimpf/Public/jsonp/}{\footnotesize \par}

{\footnotesize server-code:~~d3e7932b0b0f5e704264ba30adeae14978c08bc6}{\footnotesize \par}

{\footnotesize checkout:~~~~~1beab955418a942ab9953c4865109ff46cbbd691~2010-06-08~10:44:56~UTC}{\footnotesize \par}

{\footnotesize parent:~~~~~~~6edbaf5fa8e4d061c2e04e7fd481e7663b090bd3~2010-06-07~10:45:57~UTC}{\footnotesize \par}

{\footnotesize tags:~~~~~~~~~trunk}{\footnotesize \par}

{\footnotesize UPDATED\_BY\_MERGE~docs/qdj.lyx}{\footnotesize \par}

{\footnotesize UPDATED\_BY\_MERGE~docs/qdj.pdf}{\footnotesize \par}

{\footnotesize MERGED\_WITH~b72e96832e024f235696dcd6c5d0ddcc2cb38238}{\footnotesize \par}
\end{lyxcode}
\caption{\label{fig:Merge-Operation}Merge Operation}


\end{figure}


As shown the two documentation files are updated, there are no merge conflicts as Jim didn't touch these files and Marilyn didn't touch the code files.

Next Jim does a commit to make this new merged set of files the new trunk. Rememeber doing the merge shown in Figure \ref{fig:Merge-Operation} just updates your checked out code and does not change the repository till you check it in.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize 558~jsonp>~fossil~}\textbf{\footnotesize commit~-m~\textquotedbl{}After~merging~in~changes\textquotedbl{}}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1058~~~~~~~~~23~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~340~bytes~sent,~864~bytes~received}{\footnotesize \par}

{\footnotesize New\_Version:~3d73c03edee33cdc2e1bd8a47de57b7a6b6d880a}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~1737~~~~~~~~~26~~~~~~~~~~0~~~~~~~~~~1}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1104~~~~~~~~~24~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1101~bytes~sent,~888~bytes~received}{\footnotesize \par}

{\footnotesize 559~jsonp>~}{\footnotesize \par}
\end{lyxcode}
\caption{Commit after merge}


\end{figure}


When we look at the timeline we have a single leaf for future code commits.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Simple_Merge/sm_after_merge}

\caption{After merge timeline}


\end{figure}


The only other thing remaining is that Marilyn does an Update before proceeding so her checked out code matches the repository.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize WhiteBook:jsonp~marilyn\$~}\textbf{\footnotesize fossil~update}{\footnotesize \par}

{\footnotesize Autosync:~~http://Marilyn@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1150~~~~~~~~~25~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~412~~~~~~~~~~7~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~3274~~~~~~~~~31~~~~~~~~~~1~~~~~~~~~~5}{\footnotesize \par}

{\footnotesize Total~network~traffic:~843~bytes~sent,~2709~bytes~received}{\footnotesize \par}

{\footnotesize UPDATE~json-src/qdj\_token.c}{\footnotesize \par}

{\footnotesize UPDATE~json-src/qdj\_util.c}{\footnotesize \par}

{\footnotesize UPDATE~main.c}{\footnotesize \par}
\end{lyxcode}
\caption{Marilyn's Update}


\end{figure}



\subsection{Commands used}
\begin{itemize}
\item \textbf{fossil merge <fork>} Used to merge a fork (specified by hash value) to current check out. 
\item \textbf{fossil update <version>} Used to update current check out to specified version, if version not present use default tag for check out (see fossil status)
\end{itemize}

\section{Merge without fork}

In this case I will show how to merge in code changes from multiple users without causing a fork. In this case Marilyn has put in a BSD license text into all the code files while Jim is adding a help function to the code. In this case both of them put in tickets saying what they are doing but acting independently.


\subsection{Check in attempt}

Marilyn finished first and checks in her changes. Jim builds, tests and tries to check in his code and gets:

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize 502~jsonp>~}\textbf{\footnotesize make}{\footnotesize \par}

{\footnotesize /usr/bin/gcc~~main.c~-c~-I.~-Ijson-src~-o~obj/main.o}{\footnotesize \par}

{\footnotesize /usr/bin/gcc~~\textbackslash{}}{\footnotesize \par}

{\footnotesize 		obj/main.o\textbackslash{}}{\footnotesize \par}

{\footnotesize 		obj/qdj.o\textbackslash{}}{\footnotesize \par}

{\footnotesize 		obj/qdj\_util.o\textbackslash{}}{\footnotesize \par}

{\footnotesize 		obj/qdj\_token.o\textbackslash{}}{\footnotesize \par}

{\footnotesize 		-o~jsonp}{\footnotesize \par}



{\footnotesize 503~jsonp>~}\textbf{\footnotesize ./jsonp~-v}{\footnotesize \par}

{\footnotesize JSON~Test~Program~Ver:~{[}Jun~~9~2010{]}~{[}10:15:00{]}}{\footnotesize \par}

{\footnotesize SYNTAX:~jsonp~-i~<json~text~file>~{[}-v{]}}{\footnotesize \par}

{\footnotesize -i~<json~text~file>~~~Show~parse~of~JSON}{\footnotesize \par}

{\footnotesize -v~~~~~~~~~~~~~~~~~~~~Show~help}{\footnotesize \par}



{\footnotesize 506~jsonp>~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}fed383fa1a{]}~Add~help~to~cmd~line\textquotedbl{}}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1656~~~~~~~~~36~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~647~~~~~~~~~12~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~14039~~~~~~~~~47~~~~~~~~~~4~~~~~~~~~~7}{\footnotesize \par}

{\footnotesize Total~network~traffic:~942~bytes~sent,~4537~bytes~received}{\footnotesize \par}

{\footnotesize fossil:~would~fork.~~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\footnotesize \par}
\end{lyxcode}
\caption{Jim's check in attempt}


\end{figure}



\subsection{Update}

The next action Jim takes is to do the update but without doing changes, using the -n flag which tells it to just show what's going to happen without making any file changes.

\begin{figure}[H]
\begin{lyxcode}
507~jsonp>~\textbf{fossil~update~-n}

UPDATE~json-src/qdj.c

UPDATE~json-src/qdj.h

UPDATE~json-src/qdj\_token.c

UPDATE~json-src/qdj\_token.h

UPDATE~json-src/qdj\_util.c

MERGE~main.c
\end{lyxcode}
\caption{Update dry run}


\end{figure}


This shows some files will be updated, i.e. be replaced by new text from the repository. The main.c file will be merged with the version from the repository. That is text from the repository will be mixed with the text from Jim's modified file. Note that it says \textbf{MERGE} meaning the two sets of text are a disjoint set. This means the merge can all be done by Fossil with no human intervention.

Jim can just do the update for real then commit the merged files to make a new leaf. So now we have Marilyn's and Jim changes combined in the lastest version. 

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/file_merge/merge}

\caption{Merged repository}


\end{figure}



\subsection{Commands used}
\begin{itemize}
\item \textbf{fossil update -n} Does a dry run of an update to show what files will changed.

\begin{itemize}
\item UPDATE Implies file will be replaced by repository file
\item MERGE Implies file will be mixed text from repository and check out
\end{itemize}
\end{itemize}

\section{Branching}


\subsection{Introduction}

We have discussed this before but branching is the intential splitting of the code in the repository into multiple paths. This will usually be done with production code where we have maintenance branch and a development branch. The maintenance branch is in use and would get bug fixes based on experience. The development branch would get those changes if applicable plus be modified to add features.

The JSON code parser has been tested and works so will be released to general use. Also we wish to modify it to add support for UTF-8 characters so it matches the JSON standard. The current version just works with ASCII 7 bit characters which is not standard. We wish to split the code into a VER\_1.0 branch which is the current code in use and VER\_2.0 branch which will add UTF-8 character support.


\subsection{Branch the repository}

Before proceeding we will make sure we have the current trunk code in our check out. 

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp{]}~jim\%~}\textbf{\footnotesize fossil~status}{\footnotesize \par}

{\footnotesize repository:~/Users/jschimpf/Public/FOSSIL/jsonp.fossil}{\footnotesize \par}

{\footnotesize local-root:~/Users/jschimpf/Public/jsonp/}{\footnotesize \par}

{\footnotesize server-code:~90c80f1a2da7360dae230ccec65ff82fe2eb160d}{\footnotesize \par}

{\footnotesize checkout:~}\textbf{\footnotesize 462156b283}{\footnotesize b694af0b99c9b446b64d3f77436fbb~2010-06-09~14:16:42~UTC}{\footnotesize \par}

{\footnotesize parent:~fbb16491e2ff9f9ca3a98adffa167de1b6903a44~2010-06-09~14:02:28~UTC}{\footnotesize \par}

\textbf{\footnotesize tags:~trunk}{\footnotesize \par}
\end{lyxcode}
\caption{Checking code status}
\end{figure}


Seeing that matches the latest leaf in the time line we can proceed to branch the code.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp{]}~jim\%~}\textbf{\footnotesize fossil~branch~new~VER\_1.0~trunk~-bgcolor~0xFFC0FF}{\footnotesize \par}

{\footnotesize sh:~gpg:~command~not~found}{\footnotesize \par}

{\footnotesize unable~to~sign~manifest.~~continue~(y/N)?~y}{\footnotesize \par}

{\footnotesize New~branch:~65e1f48633d691a5ea738cd51ccbf9a581dfb3c7}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~2391~~~~~~~~~42~~~~~~~~~~0~~~~~~~~~~1}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1840~~~~~~~~~40~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1524~bytes~sent,~1272~bytes~received}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp{]}~jim\%~}\textbf{\footnotesize fossil~branch~new~VER\_2.0~trunk~-bgcolor~0xC0F0FF}{\footnotesize \par}

{\footnotesize sh:~gpg:~command~not~found}{\footnotesize \par}

{\footnotesize unable~to~sign~manifest.~~continue~(y/N)?~y}{\footnotesize \par}

{\footnotesize New~branch:~a1737916ec2df696a0f3a7e36edf9ba4370e48a7}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~2437~~~~~~~~~43~~~~~~~~~~0~~~~~~~~~~1}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~1886~~~~~~~~~41~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1550~bytes~sent,~1271~bytes~received}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp{]}~jim\%~}{\footnotesize \par}
\end{lyxcode}
\caption{Branch commands\label{fig:Branch-commands}}
\end{figure}


What was just done. We used the Fossil branch command to create two branches VER\_1.0 and VER\_2.0 and assigned each of them a color. We can see the timeline is now:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Branching/branch}

\caption{Branch Timeline}
\end{figure}



\subsection{Color Setup}

As you see above the two branches have different colors in the timeline. This was due to the \textbf{-bgcolor} option added when we created each branch. (See Figure \ref{fig:Branch-commands}). But we want this color to appear on subsequent checkins of each of these branches. To make that happen we have to set the options using the UI and picking a particular leaf on the timeline.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Branching/color_setup}

\caption{Setting Timeline color}


\end{figure}


Under the \textbf{Background Color} section I have checked \textbf{Propagate color to descendants }so future checkins will have the same color.


\subsection{Check out the branches}

Now the the repository is branched we can check out the two sets of code into different directories. We create jsonp1 and jsonp2 and proceed to open the different branches into them.

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp1{]}~}\textbf{\footnotesize jim\%~fossil~open~../FOSSIL/jsonp.fossil~VER\_1.0}{\footnotesize \par}

{\footnotesize docs/qdj.lyx}{\footnotesize \par}

{\footnotesize docs/qdj.pdf}{\footnotesize \par}

{\footnotesize json-src/qdj.c}{\footnotesize \par}

{\footnotesize json-src/qdj.h}{\footnotesize \par}

{\footnotesize json-src/qdj\_token.c}{\footnotesize \par}

{\footnotesize json-src/qdj\_token.h}{\footnotesize \par}

{\footnotesize json-src/qdj\_util.c}{\footnotesize \par}

{\footnotesize main.c}{\footnotesize \par}

{\footnotesize makefile}{\footnotesize \par}

{\footnotesize obj/test.txt}{\footnotesize \par}

{\footnotesize test.txt}{\footnotesize \par}

{\footnotesize project-name:~JASONP}{\footnotesize \par}

{\footnotesize repository:~~~/Users/jschimpf/Public/FOSSIL/jsonp.fossil}{\footnotesize \par}

{\footnotesize local-root:~~~/Users/jschimpf/Public/jsonp1/}{\footnotesize \par}

{\footnotesize project-code:~eb6084c8ab115cf2b28a129c7183731002c6143a}{\footnotesize \par}

{\footnotesize server-code:~~90c80f1a2da7360dae230ccec65ff82fe2eb160d}{\footnotesize \par}

{\footnotesize checkout:~~~~~65e1f48633d691a5ea738cd51ccbf9a581dfb3c7~2010-06-13~10:13:55~UTC}{\footnotesize \par}

{\footnotesize parent:~~~~~~~462156b283b694af0b99c9b446b64d3f77436fbb~2010-06-09~14:16:42~UTC}{\footnotesize \par}

{\footnotesize tags:~~~~~~~~~}\textbf{\footnotesize VER\_1.0}{\footnotesize \par}
\end{lyxcode}
\caption{Check out VER\_1.0}
\end{figure}


Checking out VER\_2.0 in the same way

\begin{figure}[H]
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp2{]}~jim\%~}\textbf{\footnotesize fossil~open~../FOSSIL/jsonp.fossil~VER\_2.0}{\footnotesize \par}

{\footnotesize docs/qdj.lyx}{\footnotesize \par}

{\footnotesize docs/qdj.pdf}{\footnotesize \par}

{\footnotesize json-src/qdj.c}{\footnotesize \par}

{\footnotesize json-src/qdj.h}{\footnotesize \par}

{\footnotesize json-src/qdj\_token.c}{\footnotesize \par}

{\footnotesize json-src/qdj\_token.h}{\footnotesize \par}

{\footnotesize json-src/qdj\_util.c}{\footnotesize \par}

{\footnotesize main.c}{\footnotesize \par}

{\footnotesize makefile}{\footnotesize \par}

{\footnotesize obj/test.txt}{\footnotesize \par}

{\footnotesize test.txt}{\footnotesize \par}

{\footnotesize project-name:~JASONP}{\footnotesize \par}

{\footnotesize repository:~~~/Users/jschimpf/Public/FOSSIL/jsonp.fossil}{\footnotesize \par}

{\footnotesize local-root:~~~/Users/jschimpf/Public/jsonp2/}{\footnotesize \par}

{\footnotesize project-code:~eb6084c8ab115cf2b28a129c7183731002c6143a}{\footnotesize \par}

{\footnotesize server-code:~~90c80f1a2da7360dae230ccec65ff82fe2eb160d}{\footnotesize \par}

{\footnotesize checkout:~~~~~a1737916ec2df696a0f3a7e36edf9ba4370e48a7~2010-06-13~10:14:26~UTC}{\footnotesize \par}

{\footnotesize parent:~~~~~~~462156b283b694af0b99c9b446b64d3f77436fbb~2010-06-09~14:16:42~UTC}{\footnotesize \par}

{\footnotesize tags:~~~~~~~~~}\textbf{\footnotesize VER\_2.0}{\footnotesize \par}
\end{lyxcode}
\caption{VER\_2.0 checkout}
\end{figure}


Notice on both of these the tags show which branch we are attached to.


\subsection{Correcting errors (in both)}

After doing this work I found that the main.c file had a warning about an unused variable. I wanted to correct this in both branches. At this point all the files in both branches are the same so correcting the file in either branch and copying it to the other is possible. I put in a ticket for the change and edit main.c. I copy it to both checkouts for the both branches and then check both in.

\begin{figure}
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp1{]}~jim\%~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}2795e6c74d{]}~Fix~unused~variable\textquotedbl{}}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~2116~~~~~~~~~46~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~365~~~~~~~~~~6~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~3601~~~~~~~~~51~~~~~~~~~~5~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~805~bytes~sent,~3464~bytes~received}{\footnotesize \par}

{\footnotesize New\_Version:~3b902585d0e8849399286139d27676c5a349de7b}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~3034~~~~~~~~~50~~~~~~~~~~0~~~~~~~~~~2}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~2208~~~~~~~~~48~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1848~bytes~sent,~1444~bytes~received}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp1{]}~jim\%~}\textbf{\footnotesize cd~..}{\footnotesize \par}

{\footnotesize {[}Pandora-2:/Users/jschimpf/Public{]}~jim\%~}\textbf{\footnotesize cd~jsonp2}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp2{]}~jim\%~}\textbf{\footnotesize cp~../jsonp1/main.c~.}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp2{]}~jim\%~}\textbf{\footnotesize fossil~status}{\footnotesize \par}

{\footnotesize repository:~~~/Users/jschimpf/Public/FOSSIL/jsonp.fossil}{\footnotesize \par}

{\footnotesize local-root:~~~/Users/jschimpf/Public/jsonp2/}{\footnotesize \par}

{\footnotesize server-code:~~90c80f1a2da7360dae230ccec65ff82fe2eb160d}{\footnotesize \par}

{\footnotesize checkout:~~~~~a1737916ec2df696a0f3a7e36edf9ba4370e48a7~2010-06-13~10:14:26~UTC}{\footnotesize \par}

{\footnotesize parent:~~~~~~~462156b283b694af0b99c9b446b64d3f77436fbb~2010-06-09~14:16:42~UTC}{\footnotesize \par}

{\footnotesize tags:~~~~~~~~~VER\_2.0}{\footnotesize \par}

{\footnotesize EDITED~~~~~main.c}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp2{]}~jim\%~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}2795e6c74d{]}~Fix~unused~variable\textquotedbl{}}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~2392~~~~~~~~~52~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~~318~~~~~~~~~~5~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~3320~~~~~~~~~56~~~~~~~~~~4~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~781~bytes~sent,~3508~bytes~received}{\footnotesize \par}

{\footnotesize New\_Version:~762a31854d708080678598c8d4ce28465cbee8c5}{\footnotesize \par}

{\footnotesize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi}{\footnotesize \par}

{\footnotesize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\footnotesize \par}

{\footnotesize Send:~~~~~~~~~~~~3253~~~~~~~~~55~~~~~~~~~~0~~~~~~~~~~2}{\footnotesize \par}

{\footnotesize Received:~~~~~~~~2438~~~~~~~~~53~~~~~~~~~~0~~~~~~~~~~0}{\footnotesize \par}

{\footnotesize Total~network~traffic:~1972~bytes~sent,~1573~bytes~received}{\footnotesize \par}

{\footnotesize {[}Pandora-2:jschimpf/Public/jsonp2{]}~jim\%~}{\footnotesize \par}
\end{lyxcode}
\caption{Fixing both branches}


\end{figure}


Now the timeline looks like this:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Advanced/Branching/current_state}

\caption{Correcting both branches}


\end{figure}



\subsection{Commands used}
\begin{itemize}
\item \textbf{fossil branch }Used to generate a branch of the repository. The command can optionally color the branch in the display.
\end{itemize}

\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.
\item [{Fork}] In Fossil an involuntary split in the code path, occurs when a file in the repository has changes not in a file to be committed.
\end{description}

\chapter{\label{sec:Multiple-Users}Multiple Users}

\section{Introduction}
In the previous chapter I went through using Fossil with just one user (me). In this chapter we will get into using it with multiple users. Thanks to Fossil's distributed design once the set up is done using it is not much different than the single user case with Fossil managing automatically the multiple user details.

\section{Setup}
In the previous chapter the Fossil repository was a file on our system and we did commits to it and pulled copies of the source from it. Fossil is a distributed source control system; what this means is that there is a master repository in a place that all users can access. Each user has their own ``cloned'' copy of the repository and Fossil will automatically synchronize the users repository with the master. From a each user's perspective you have your local repository and work with it using the same commands shown in Chapter \ref{sec:Single-User-Fossil}. It's just that now Fossil will keep your repository in sync with the master.

\subsection{Server Setup\label{sub:Server-Setup}}
I have the FossilBook.fossil repository and now have to put it in place so multiple users can access it. There are two ways, the first is using fossil's built in webserver to host the file and the second is using the operating systems supported web server (if present) and a cgi type access.

\paragraph{Self hosted}
This is quite simply the easiest way to do it. The downside is that you are responsible for keeping the machine available and the webserver up. That is, don't turn the machine off when you quit for the day or some other user is going to be upset. All I have to do is this:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:/Users/jschimpf/Public{]}~jim\%~cd~FOSSIL/}{\scriptsize \par}
{\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}\textbf{\scriptsize fossil~ui~-port~8081~FossilBook.fossil~\&}{\scriptsize{}~}{\scriptsize \par}
{\scriptsize {[}1{]}~310}{\scriptsize \par}
{\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{Self-hosted Fossil repository}
\end{figure}

This is on UNIX system, the ``\&'' at then end of the second line runs the fossil webserver in the background. If I know this machine has an IP address of 192.168.1.200 then from any other machine in the network I can say:

\textbf{http://192.168.1.200:8081} to the browser and I can access the Fossil web server. 

As you can see this is simple and works on any system that runs Fossil. As long as you carefully make sure it's always running and available for others this can be a very easy way to make the master repository available. 

The problems with this method are:
\begin{enumerate}
\item If you have multiple repositories you have to use the \textbf{server} not the \textbf{ui} command, have all your repositories in the same directory, and have them all use the extension .fossil.
\item If the machine goes off line (i.e. for OS update) or other reason it might not automatically restart the Fossil servers.
\item Backup of the repositories might be not be done.
\end{enumerate}
This method does work, and if you only have one repository and a diligent owner of the master machine, it will work and work well.


\paragraph{Server hosted}

If you have a server type machine available (i.e., a Linux or UNIX box) that is running Apache or a Windows machine running IIS you can let it be the webserver for your repository. This has a number of advantages: this machine will be up all the time, it will probably be automatically backed up, and it can easily support multiple Fossil repositories.

I am not going into how to set up the webserver or how to enable (Common Gateway Interface) CGI. See the following sites.
\begin{itemize}
\item For IIS see here \url{http://www.boutell.com/newfaq/creating/iiscgihowto.html} and just ensure that your fossil.exe is in the path to be run by the cgi script.
\item For Apache see here \url{http://httpd.apache.org/docs/2.0/howto/cgi.html} and ensure you know the directory where the CGI scripts are stored.
\end{itemize}
If you are not in control of the webserver you will need the help of the server admin to enable CGI and to copy your CGI scripts to correct location.


\paragraph{CGI Script for hosted server}

If we assume an Apache server and, in my case, the cgi directory path is /Library/Webserver/CGI-Executables, then we have to write a script of the form:

\begin{figure}[H]
\begin{lyxcode}
\#!<Fossil~executable~location>
repository:~<Fossil~repository~location>
\end{lyxcode}
\caption{Fossil CGI script}
\end{figure}

and put it into the cgi script directory. I have put my Fossil executable into /usr/local/bin and I am putting my Fossil shared repository into /Users/Shared/FOSSIL. My script then becomes:

\begin{figure}[H]
\begin{lyxcode}
\#!/usr/local/bin/fossil
\#~Put~the~book~repository~on~the~web
repository:~/Users/Shared/FOSSIL/Fossilbook.fossil
\end{lyxcode}
\caption{My Fossil CGI script}
\end{figure}


After making the script I then copy it to the CGI directory and allow anyone to execute it.

\begin{figure}[H]
\begin{lyxcode}
\textbf{\scriptsize sudo~cp~Book.cgi~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par}
\textbf{\scriptsize sudo~chmod~a+x~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par}
\end{lyxcode}
\caption{Copying script into place}
\end{figure}

\subsection{The test (either self hosted or server hosted)}

If all is in place then I should be able to access the webserver and get to this:
\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Multiple_user/test_access}
\caption{\label{fig:Web-access-to}Web access to Fossil CGI hosted site}
\end{figure}

\section{User Accounts}

Serving a repository, either self hosting or the more complicated CGI method gets you to the same place as shown in Figure \vref{fig:Web-access-to}. Now I have to set up user accounts for the other contributors to this book. Remember Fossil has automatically created an Anonymous user (see Figure \vref{fig:User-Configuration}) thus others can access the site in a limited way, that is they can download the book but cannot commit changes. In this case I want to create a new account (Marilyn) that can make changes and commit changes as she is my editor.

To accomplish all this first I have to login by going to the log in page and entering my ID (jim) and my password. Now since I'm super-user I then go back to the User-Configuration page, Figure \eqref{fig:User-Configuration} and add a new user:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Multiple_user/mul_new_user}
\caption{New Editor user\label{fig:New-Editor-user}}
\end{figure}

Since she is going to be an editor, this will be similar to a developer if we were doing code, so I picked the Developer privilege level. This way she can get the repository, check-in, check-out, and write and update tickets. I also added the attachments since she might need that to put on an image or other comment on actions she is doing. I also gave her a password so her access can be secured.

I could add other users at this point but don't need any others for this project, but you can see how easily this can be done. When you assign the user privileges just read carefully and don't give them any more than you think they need. If they have problems, you can easily modify their account in the future.


\section{Multiple User Operation}

With the server set up and the user established the next thing to do is clone the repository. That is make copy from the webserver repository to my local machine. Once that is done this local repository uses the same commands and is very much like single user use discussed in Section \vref{sec:Single-User-Fossil}. Fossil will synchronize your local repository with the one on the server.


\subsection{Cloning}

To clone a Fossil repository you have to know four things:
\begin{enumerate}
\item It's web address, for our repository it is \textbf{http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}
\item Your account name in my case it's \textbf{jim}
\item Your password (which I'm keeping to myself thank you...)
\item The local name of the repository, in this case I'm calling it Fossilbook.fossil
\end{enumerate}
You then go to where you want to keep the Repository (in my case the FOSSIL directory) and use the clone command:

\begin{figure}[H]
\begin{lyxcode}
{\tiny {[}Pandora-2:jschimpf/Public/FOSSIL{]}}\textbf{\tiny{}~fossil~clone~http://jim:}{\tiny <passwd>}\textbf{\tiny @pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi~FossilBook.fossil}{\tiny \par}

\textbf{\scriptsize \#\#\#~NOTE:~<passwd>~}{\scriptsize -~Stands~in~for~real~password}{\scriptsize \par}



{\scriptsize{}~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\scriptsize \par}

{\scriptsize Send:~~~~~~~~~~~~~~49~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Received:~~~~~~~~~120~~~~~~~~~~2~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Send:~~~~~~~~~~~~~625~~~~~~~~~25~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Received:~~~~~~~~4704~~~~~~~~~72~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Send:~~~~~~~~~~~~3104~~~~~~~~~72~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Received:~~~~~5129052~~~~~~~~131~~~~~~~~~10~~~~~~~~~~5}{\scriptsize \par}

{\scriptsize Send:~~~~~~~~~~~~2399~~~~~~~~~51~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Received:~~~~~4381170~~~~~~~~116~~~~~~~~~22~~~~~~~~~28}{\scriptsize \par}

{\scriptsize Total~network~traffic:~4117~bytes~sent,~6913068~bytes~received}{\scriptsize \par}

{\scriptsize Rebuilding~repository~meta-data...}{\scriptsize \par}

{\scriptsize 65~(100\%)...}{\scriptsize \par}

{\scriptsize project-id:~2b0d35831c1a5b315d74c4fd8d532b100b822ad7}{\scriptsize \par}

{\scriptsize server-id:~~3e67da6d6212494456c69b1c5406a277d7e50430}{\scriptsize \par}

{\scriptsize admin-user:~jim~(password~is~\textquotedbl{}d07222\textquotedbl{})}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{Clone command}


\end{figure}


At this point I can go through the steps outlined in Section \vref{sec:Single-User-Fossil} to set my user password and then open the Fossil Repository on a working directory.

Now that I've moved everything to the new cloned repository I do a check in a the end of the day which looks like this:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}Moved~to~clone~repository\textquotedbl{}}{\scriptsize \par}

{\scriptsize Autosync:~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}{\scriptsize \par}

{\scriptsize Bytes~Cards~Artifacts~Deltas}{\scriptsize \par}

{\scriptsize Send:~130~1~0~0}{\scriptsize \par}

{\scriptsize Received:~2990~65~0~0}{\scriptsize \par}

{\scriptsize Total~network~traffic:~334~bytes~sent,~1876~bytes~received}{\scriptsize \par}

{\scriptsize New\_Version:~158492516c640d055bc0720684a05e797b88165a}{\scriptsize \par}

{\scriptsize Autosync:~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}{\scriptsize \par}

{\scriptsize Bytes~Cards~Artifacts~Deltas}{\scriptsize \par}

{\scriptsize Send:~618798~74~1~2}{\scriptsize \par}

{\scriptsize Received:~3222~70~0~0}{\scriptsize \par}

{\scriptsize Send:~268138~73~1~0}{\scriptsize \par}

{\scriptsize Received:~3221~70~0~0}{\scriptsize \par}

{\scriptsize Send:~3977~72~0~1}{\scriptsize \par}

{\scriptsize Received:~3220~70~0~0}{\scriptsize \par}

{\scriptsize Total~network~traffic:~457995~bytes~sent,~6011~bytes~received}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{\label{fig:Cloned-repository-checkin}Cloned repository checkin}


\end{figure}


As you see the files were committed locally and then the local repository was automatically synchronized with the repository on the server.


\subsection{Keeping in sync}

After doing all the setup described above I now have a distributed source control system. My co-worker, Marilyn has also cloned the repository and begun work. She is editing the book correcting my clumsy phrasing and fixing spelling mistakes. She is working independently and on the same files I use. We must use Fossil to prevent us from both modifying FossilBook.lyx but in different ways. Remember Fossil has no file locking, there is nothing to prevent her from editing and changing the file while I work on it.

This is where we both must follow procedures to prevent this sort of problem. Even though she edits files I cannot see the changes till they are committed. Two different versions of the same file won't be a problem till I try to commit with my version and her version is in the current leaf.

\label{There-are-two}There are two problems:
\begin{enumerate}
\item Before I do any work I must be sure I have the current versions of all the files.
\item When I commit I must make sure what I am committing has only my changes and is not stepping on changes she has done.
\end{enumerate}
The first is pretty obvious, make sure you have the latest before you do anything. We do that with the update command. In Figure \ref{fig:Cloned-repository-checkin} I had done my latest check in. Before starting any more work I should ensure that Marilyn hasn't checked in something else. I could check the timeline but instead I'll do an update to my repository and source files. When I do the update I specify it should be updated from the \textbf{trunk. }This ensures I get it from the latest and greatest not some branch.

\begin{figure}
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~update~trunk}{\scriptsize \par}

{\scriptsize Autosync:~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}{\scriptsize \par}

{\scriptsize Bytes~Cards~Artifacts~Deltas}{\scriptsize \par}

{\scriptsize Send:~130~1~0~0}{\scriptsize \par}

{\scriptsize Received:~3588~78~0~0}{\scriptsize \par}

{\scriptsize Send:~365~6~0~0}{\scriptsize \par}

{\scriptsize Received:~136461~83~2~3}{\scriptsize \par}

{\scriptsize Total~network~traffic:~796~bytes~sent,~131582~bytes~received}{\scriptsize \par}

{\scriptsize UPDATE~fossilbook.lyx}{\scriptsize \par}

{\scriptsize UPDATE~fossilbook.pdf}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}~
\end{lyxcode}
\caption{Update action}


\end{figure}


Ah ha ! Marilyn has been at work and updated the book source and pdf. If I check the timeline from the webserver I see she has even documented it:

\begin{figure}[H]
\includegraphics[scale=0.4]{Images/Multiple_user/mul_timeline}

\caption{Updated Timeline}


\end{figure}


Now I know I have the current state of the world and I can proceed to add in new sections.


\subsection{Complications\label{sub:Complications}}

In\vref{There-are-two} the second case is much harder. In this case I have diligently done my fossil update and started working. In the mean time Marilyn has also done her update and also started working. Now she is done and checks in her changes. I obviously don't know this since I am happily working on my changes. What happens next....

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}Commit~that~might~fork\textquotedbl{}}{\scriptsize \par}

{\scriptsize Autosync:~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}{\scriptsize \par}

{\scriptsize Bytes~Cards~Artifacts~Deltas}{\scriptsize \par}

{\scriptsize Send:~130~1~0~0}{\scriptsize \par}

{\scriptsize Received:~4002~87~0~0}{\scriptsize \par}

{\scriptsize Send:~365~6~0~0}{\scriptsize \par}

{\scriptsize Received:~110470~92~2~3}{\scriptsize \par}

{\scriptsize Total~network~traffic:~797~bytes~sent,~104567~bytes~received}{\scriptsize \par}

\textbf{\scriptsize fossil:~would~fork.~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}{\scriptsize \par}
\end{lyxcode}
\caption{Forking commit}


\end{figure}


Ah ha, that very thing has happened and fossil warned me that my copy of the file differs from the master copy. If I did a --force then the repository would generate a fork and Marilyn's future commits would be to her fork and my commits would be to mine. That would not be what we want since I want her to edit\textbf{ }my copy of the book.

The next step would be to do as Fossil says and do an update. At this point you have to be careful since blindly updating the changed files could overwrite the stuff I've just done. So we do a trial update by using the -n and -v options to say``do a dry run'' and show me the results.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~update~-n~-v}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Multiple\_user/mul\_new\_user.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Multiple\_user/mul\_timeline.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Multiple\_user/test\_access.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/config\_initial.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/initial\_page.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/jim\_setup.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/ticket\_done.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/ticket\_form.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/ticket\_initial.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/ticket\_list.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/ticket\_submit.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/timeline.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/timeline\_detail.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/user\_config.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/wiki\_blankhome.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/wiki\_formating.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/wiki\_home.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/wiki\_homeedit.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Images/Single\_user/wiki\_page.epsf}{\scriptsize \par}

{\scriptsize UNCHANGED~Layout/fossil.png}{\scriptsize \par}

{\scriptsize UNCHANGED~Research/History/CVS-grune.pdf}{\scriptsize \par}

{\scriptsize UNCHANGED~Research/History/RCS\textemdash{}A~System~for~Version~Control.webloc}{\scriptsize \par}

{\scriptsize UNCHANGED~Research/History/SCCS-Slideshow.pdf}{\scriptsize \par}

{\scriptsize UNCHANGED~Research/History/VCSHistory~-~pysync~-~A~Brief~History~of~Version~Control~Systems~-~Project~Hosting~on~Google~Code.webloc}{\scriptsize \par}

{\scriptsize UNCHANGED~Research/fossilbib.bib}{\scriptsize \par}

{\scriptsize MERGE~fossilbook.lyx}{\scriptsize \par}

{\scriptsize UPDATE~fossilbook.pdf}{\scriptsize \par}

{\scriptsize UNCHANGED~outline.txt}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}{\scriptsize \par}
\end{lyxcode}
\caption{Update dry run}


\end{figure}


That's a little more than I wanted as you can see almost everything is UNCHANGED but it shows that fossilbook.lyx needs a MERGE and fossilbook.pdf needs an UPDATE. This is what I should expect, Marilyn has done edits to the fossilbook.lyx file and so have I so we have to merge the changes. But she has also updated the fossilbook.pdf which I have not. Before we go on if you are running on Linux or UNIX you can simplify this dry run by doing:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}\textbf{\scriptsize fossil~update~-n~-v~|~grep~-v~UNCHANGED}{\scriptsize \par}

{\scriptsize MERGE~fossilbook.lyx}{\scriptsize \par}

{\scriptsize UPDATE~fossilbook.pdf}{\scriptsize \par}
\end{lyxcode}
\caption{Update dry run, shorter}


\end{figure}


By using the pipe and grep I can eliminate all those extra UNCHANGED lines.


\subsection{Fixing the Update file}

First we fix the easy file, the fossilbook.pdf I can just update by itself so it matches the current repository. It doesn't need merged so just replace it. Before I do that I have to look at the repository time line

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Multiple_user/mul_timeline}

\caption{Current Timeline}


\end{figure}


I see that the current\textbf{ Leaf} is {[}d44769cc23{]} and it is tagged as\textbf{ trunk}. I want to update the fossilbook.pdf from there. So I say:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}\textbf{\scriptsize fossil~update~trunk~fossilbook.pdf}{\scriptsize \par}

{\scriptsize Autosync:~~http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi}{\scriptsize \par}

{\scriptsize{}~~~~~~~~~~~~~~~~Bytes~~~~~~Cards~~Artifacts~~~~~Deltas}{\scriptsize \par}

{\scriptsize Send:~~~~~~~~~~~~~130~~~~~~~~~~1~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Received:~~~~~~~~4002~~~~~~~~~87~~~~~~~~~~0~~~~~~~~~~0}{\scriptsize \par}

{\scriptsize Total~network~traffic:~334~bytes~sent,~2412~bytes~received}{\scriptsize \par}

{\scriptsize UPDATE~fossilbook.pdf}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}{\scriptsize \par}
\end{lyxcode}
\caption{Update fossilbook.pdf}


\end{figure}


and it's done.


\subsection{Fixing the Merge file}

We can use the tools built into Fossil. In this case noticing that commit will cause a fork Jim will use the -force option to cause the fork and will handle the merge later.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-m~\textquotedbl{}adding~some~changes~of~jim\textquotedbl{}}{\scriptsize \par}

{\scriptsize fossil:~would~fork.0~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\scriptsize \par}

{\scriptsize }{\scriptsize \par}

{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-f~-m~\textquotedbl{}adding~some~other~changes~of~jim\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~df9f2ff6b14ef65a9dd2162f8bd20c78e1628165}{\scriptsize \par}
\end{lyxcode}
\caption{Forcing a commit under Windows}
\end{figure}


Now the timeline looks like:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Multiple_user/Windows/forked_timeline}

\caption{Windows Forked timeline}
\end{figure}


To remove this fork (i.e. get the changes Marilyn did into the trunk) we use the Fossil merge command. We can use the merge because fossilbook.lyx is a text file and the merge markers are designed to work with text files. If it was a binary file we might have to use an external file or copy and paste between the two file versions using the handler program for the file.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~merge~a91582b699}{\scriptsize \par}

{\scriptsize MERGE~fossilbook.lyx}{\scriptsize \par}

{\scriptsize {*}{*}{*}{*}{*}~2~merge~conflicts~in~fossilbook.lyx}{\scriptsize \par}
\end{lyxcode}
\caption{Fossil Merge}
\end{figure}


Looking at the file (fossilbook.lyx) in a text editor (not \LyX{}) we find:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize >\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>~BEGIN~MERGE~CONFLICT}{\scriptsize \par}

{\scriptsize Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~it}{\scriptsize \par}

{\scriptsize with~multiple~users~is~not~much~different~than~the~single~user~case.}{\scriptsize \par}

{\scriptsize Fossil~will~automatically~manage~the~most~multiple~user~details.}{\scriptsize \par}

{\scriptsize ============================}{\scriptsize \par}

{\scriptsize }{\scriptsize \par}

{\scriptsize Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~is}{\scriptsize \par}

{\scriptsize not~much~different~than~the~single~user~case~with~Fossil~managing~automatically}{\scriptsize \par}

{\scriptsize the~multiple~user~details.}{\scriptsize \par}

{\scriptsize <\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<~END~MERGE~CONFLICT}{\scriptsize \par}



\textbf{<Here~edit~in~the~changes>}



{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-m~\textquotedbl{}merging~marilyn's~fork~back\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~acdd676d3ab157769496f6845ccc7652985c1d03}{\scriptsize \par}
\end{lyxcode}
\caption{Text differences}
\end{figure}


After the commit the timeline shows how the merge brought the fork back into the main trunk. Marilyn will then have to update to this new trunk. (See Section \vref{sub:Updating-by-others})

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Multiple_user/Windows/merged_timeline}

\caption{Merged timeline}
\end{figure}

\chapter{Single Users}
\section{Introduction}

If you have read this far and are at least persuaded to try, you will want to put one of your projects under software control using Fossil. This chapter is set up to lead you through that task and show you how to adapt your development to using this tool. The assumption is made in this section that you will be the only person using the repository, you are the designer, developer, and maintainer of this project. After you are comfortable using the tool, the next section will show how you use it when you have multiple people working on a project.


\section{Creating a repository }


\subsection{Introduction}

In the spirit of ``eating one's own dog food'' we will use this book as the project we are going to manage with Fossil. The book is a directory of text files (we are writing it using \LyX{} \cite{LyX}) and my working area looks like this:
\begin{lyxcode}
{\scriptsize FOSSIL/}{\scriptsize \par}
\begin{lyxcode}
{\scriptsize This~directory~holds~all~my~Fossil~repositories}{\scriptsize \par}
\end{lyxcode}
{\scriptsize FossilBook/}{\scriptsize \par}
\begin{lyxcode}
{\scriptsize outline.txt~~~~-~Book~design}{\scriptsize \par}

{\scriptsize fossilbook.lyx~-~The~book}{\scriptsize \par}

{\scriptsize Layout}{\scriptsize \par}
\begin{lyxcode}
{\scriptsize fossil.png~~-~The~Fossil~logo~(image~on~title~page)}{\scriptsize \par}
\end{lyxcode}
{\scriptsize Research}{\scriptsize \par}
\begin{lyxcode}
{\scriptsize fossilbib.bib~-~Working~bibliography}{\scriptsize \par}

{\scriptsize History}{\scriptsize \par}
\begin{lyxcode}
{\scriptsize CVC-grune.pdf~-~Historical~paper~about~CVS}{\scriptsize \par}

{\scriptsize RCS-A~System~for~Version~Control.webloc~-~RCS~bookmark}{\scriptsize \par}

{\scriptsize SCCS-Slideshow.pdf~-~Historical~paper~about~SCCS}{\scriptsize \par}

{\scriptsize VCSHistory~-pysync~...~.webloc~-~History~of~version~control}{\scriptsize \par}
\end{lyxcode}
\end{lyxcode}
\end{lyxcode}
\end{lyxcode}
This took just an hour or so to start preliminary research and build the framework. Since that's about all I'm going to do today I want to build a repository and put all this stuff under Fossil control.


\subsection{Create Repository}

I have a directory called FOSSIL in which I keep all my repositories, Fossil doesn't care but it helps me to keep them all in one place so I can back them up. First I need to create a new repository for the book. This is done using the command line after I move into the Fossil book directory.
\begin{lyxcode}
{\scriptsize }
\begin{figure}[H]
\begin{lyxcode}


{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~new~../FOSSIL/FossilBook.fossil}{\scriptsize \par}

{\scriptsize project-id:~2b0d35831c1a5b315d74c4fd8d532b100b822ad7}{\scriptsize \par}

{\scriptsize server-id:~~0149388e5a3109a867332dd8439ac7b454f3f9dd}{\scriptsize \par}

{\scriptsize admin-user:~jim~(initial~password~is~\textquotedbl{}}\textbf{\scriptsize ec3773}{\scriptsize \textquotedbl{})}{\scriptsize \par}
\end{lyxcode}
\caption{Create Repository\label{fig:Create-Repository}}


\end{figure}
{\scriptsize \par}
\end{lyxcode}
I create my repositories with the extension .fossil, this will be useful later with the server command (See Figure \vref{fig:server-detail}). When the create happened it assigned an initial password with an admin user of ``jim'' (i.e., me). 


\subsection{Connect Repository}

The repository is created but is empty and has no connection to the book directory. The next step is to open the repository to the book directory with the \textbf{open} command.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~open~../FOSSIL/FossilBook.fossil}{\scriptsize{}~}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~status}{\scriptsize \par}

{\scriptsize repository:~~~/Users/jschimpf/Public/FOSSIL/FossilBook.fossil}{\scriptsize \par}

{\scriptsize local-root:~~~/Users/jschimpf/Public/FossilBook/}{\scriptsize \par}

{\scriptsize server-code:~~0149388e5a3109a867332dd8439ac7b454f3f9dd}{\scriptsize \par}

{\scriptsize checkout:~~~~~279dfecd3f0322f236a92a9a8f3c96acf327d8c1~2010-04-25~12:40:39~UTC}{\scriptsize \par}

{\scriptsize tags:~~~~~~~~~trunk}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~extra}{\scriptsize \par}

{\scriptsize Layout/fossil.png}{\scriptsize \par}

{\scriptsize Research/History/CVS-grune.pdf}{\scriptsize \par}

{\scriptsize Research/History/RCS\textemdash{}A~System~for~Version~Control.webloc}{\scriptsize \par}

{\scriptsize Research/History/SCCS-Slideshow.pdf}{\scriptsize \par}

{\scriptsize Research/History/VCSHistory~-~pysync~-~....webloc}{\scriptsize \par}

{\scriptsize Research/fossilbib.bib}{\scriptsize \par}

{\scriptsize fossilbook.lyx}{\scriptsize \par}

{\scriptsize outline.txt}{\scriptsize \par}
\end{lyxcode}
\caption{Open Repository \& Check}


\end{figure}


The \textbf{open} command seemingly did nothing but checking with the \textbf{status} command shows the repository, the directory it's linked to and that we are hooked to the trunk of the store. 

The \textbf{extra} command shows all the files in the directory that are NOT under control of Fossil. In this case that's all of them since we have not checked in anything.


\subsection{Add and Initial Commit}

I must now add all the relevant files into the repository with the \textbf{add} command. The Fossil add is recursive so if I add the top level files it will automatically recurse into the subdirectories like Layout and Research and get those files too. Before you do an add it pays to tidy up your directory so you don't accidentally add a bunch of transient files (like object files from a compile). It's easy to remove them later but a little tidying before hand can save you some work.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~add~.}{\scriptsize \par}

{\scriptsize ADDED~~Layout/fossil.png}{\scriptsize \par}

{\scriptsize ADDED~~Research/History/CVS-grune.pdf}{\scriptsize \par}

{\scriptsize ADDED~~Research/History/RCS\textemdash{}A~System~for~Version~Control.webloc}{\scriptsize \par}

{\scriptsize ADDED~~Research/History/SCCS-Slideshow.pdf}{\scriptsize \par}

{\scriptsize ADDED~~Research/History/VCSHistory~-~pysync~....webloc}{\scriptsize \par}

{\scriptsize ADDED~~Research/fossilbib.bib}{\scriptsize \par}

{\scriptsize fossil:~cannot~add~\_FOSSIL\_}{\scriptsize \par}

{\scriptsize ADDED~~fossilbook.lyx}{\scriptsize \par}

{\scriptsize ADDED~~outline.txt}{\scriptsize \par}
\end{lyxcode}
\caption{Initial file add}
\end{figure}


I simply told fossil to do an add of the current directory (.) so it got all those files and all the files in the subdirectory. Note the \_FOSSIL\_ that it didn't add. This is the tag file that fossil keeps in a directory so it knows what repository it belongs to. Fossil won't add this file since it manages it, but everything else is fair game.

One final thing before I can quit for the day, these files have been added or rather they will be added to the repository when I commit it. That must be done and then we can relax and let Fossil manage things. 

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}Initial~Commit\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~8fa070818679e1744374bc5302a621490276d739}{\scriptsize \par}
\end{lyxcode}
\caption{Initial Commit}


\end{figure}


I added a comment on the commit and it's a good idea to always do this. When later we see the timeline of the commits you will have notes to tell you what was done.


\subsection{Fossil start up summary}
\begin{itemize}
\item \textbf{fossil new <name> }Creates a new fossil repository
\item \textbf{fossil open <repository> }While in a source directory connects this directory to the fossil repository
\item \textbf{fossil add .} Will add (recursively) all the files in the current directory and all subdirectories to the repository
\item \textbf{fossil addremove} Will (recursively) add any files that have been added in the current working directory and delete any files that have been deleted in the current working directory.
\item \textbf{fossil commit -m ``Initial Commit''} Will put all the currently added files into the repository.
\end{itemize}

\section{Set Up User interface}

One of the surprising features of Fossil is the webserver. This allows it to have a GUI type user interface with no operating system specific code, the GUI is the web browser supplied by your OS. In the previous steps I checked my project in to a Fossil repository, next I have to prep the web interface for production use. 
\begin{description}
\item [{NOTE}] The Fossil web server uses port 8080 instead of the standard port 80 for all HTTP access. When run it will automatically start your Web browser and open the repository home page. Unfortunately my book work is done on a machine that already has Apache running on port 8080 so I will be using port 8081. I will always have to add an extra parameter on the UI command line to do this.
\end{description}
\begin{figure}[H]
\begin{lyxcode}
{\footnotesize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\footnotesize fossil~ui~-port~8081}{\footnotesize \par}
\end{lyxcode}
\caption{\label{fig:Starting-Webserver}Starting Webserver}
\end{figure}

\begin{description}
\item [{NOTE:}] Newer versions of Fossil automatically find an open port and will give a message on the command line telling you what port number is used. You can still use the -port option if you want to control the port \#.
\end{description}
This shows how it's started, as you can see I have picked port 8081 since I am locked out of port 8080. When I do this my browser starts and I am presented with the following home page.

\begin{figure}[H]
\noindent \begin{raggedright}
\includegraphics[scale=0.5]{Images/Single_user/initial_page}
\par\end{raggedright}

\caption{\label{fig:Initial-Webserver-page}Initial webserver page}


\end{figure}


Following the advice on the page I go to \textbf{setup/config}. I am going to do the minimum setup that you should do on all projects. As you get familiar with Fossil you will probably have many more things that you will customize for your taste but what follows are the only things you HAVE to do.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/config_initial}

\caption{\label{fig:Initial-Configuration}Initial Configuration}


\end{figure}


I have entered in a project name and put in a description, the project name will be the name of the initial Wiki page (see \vref{sub:Wiki-Use}) and the description is useful for others to see what you are doing here. Then I go to the bottom of the page and pick the \textbf{Apply Changes }button.

Next I pick the Admin tab (you can see it in the header bar) and the pick Users from that page. I am presented with the users and will use this to set the password of the project.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/user_config}

\caption{\label{fig:User-Configuration}User Configuration}


\end{figure}


As you can see Fossil automatically configures a number of users beyond just the creator. The anonymous user you have already seen if you went to the Fossil web site to download the code. This user can view and get code but cannot commit code. On the right side of the page are the many options you can give to a user, it's worth reading it all when you set up your repository. The important one is me (jim) which has ``s'' or Super User Capabilities. This means I can do anything with the repository.

I will now edit the user Jim to make sure it has the settings I want. In this case you MUST set the password. Remember way back where Fossil set it during the create (Figure\vref{fig:Create-Repository}), it's a very good idea to change this to something you can remember rather than the original random one.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/jim_setup}

\caption{Super User Setup}


\end{figure}


I have put in my contact information (e-mail address) and while you cannot see it I have typed in a password that I will remember. Then I applied the changes.

Now the repository is ready for further work, it's rather bare bones at this point but the most important things are set up.


\subsection{User interface summary}
\begin{itemize}
\item \textbf{fossil ui} run in the source directory will start a browser based user interface to fossil.
\item \textbf{fossil ui -port <IP port \#>} Can be used if port 8080 if already in use on your system.
\item On the first run it is important to configure your project with a name and set the password for yourself.
\end{itemize}

\section{Update Repository}

After writing the above section of the book I now have created a bunch of new files and changed some of the existing files in the repository. Before quitting for the day I should add these new files into the repository and commit the changes saving this milestone in the project.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~extra}{\scriptsize \par}

{\scriptsize \#fossilbook.lyx\#}{\scriptsize \par}

{\scriptsize Images/Single\_user/config\_initial.epsf}{\scriptsize \par}

{\scriptsize Images/Single\_user/initial\_page.epsf}{\scriptsize \par}

{\scriptsize Images/Single\_user/jim\_setup.epsf}{\scriptsize \par}

{\scriptsize Images/Single\_user/user\_config.epsf}{\scriptsize \par}

{\scriptsize fossilbook.lyx\textasciitilde{}}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~status}{\scriptsize \par}

{\scriptsize repository:~~~/Users/jschimpf/Public/FOSSIL/FossilBook.fossil}{\scriptsize \par}

{\scriptsize local-root:~~~/Users/jschimpf/Public/FossilBook/}{\scriptsize \par}

{\scriptsize server-code:~~0149388e5a3109a867332dd8439ac7b454f3f9dd}{\scriptsize \par}

{\scriptsize checkout:~~~~~8fa070818679e1744374bc5302a621490276d739~2010-04-25~13:09:02~UTC}{\scriptsize \par}

{\scriptsize parent:~~~~~~~279dfecd3f0322f236a92a9a8f3c96acf327d8c1~2010-04-25~12:40:39~UTC}{\scriptsize \par}

{\scriptsize tags:~~~~~~~~~trunk}{\scriptsize \par}

{\scriptsize EDITED~~~~~fossilbook.lyx}{\scriptsize \par}


\end{lyxcode}
\caption{Project Status}


\end{figure}


I run \textbf{fossil extra} to see these new files. The image files (those in Images/Single\_user) I want to add, the other two files, \#fossilbook.lyx\# and fossilbook.lyx\textasciitilde{}, I don't want to add since they are temporary artifacts of \LyX{}. I also ran \textbf{fossil status}. This shows changes to files that are already in the repository. There the only file changed is the book text itself, \textbf{fossilbook.lyx}.

All I have to do now is add in the directory Images which will add in the image files I want in the repository. Then I commit the changes to the repository and we can move on to other tasks of the day.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~add~Images}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/config\_initial.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/initial\_page.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/jim\_setup.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/user\_config.epsf}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}Initial~setup~with~pictures\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~a2d12bf532a089ee53578e3e17c6e732c0442f49}{\scriptsize \par}
\end{lyxcode}
\caption{\label{fig:Update-for-new}Update for new files}


\end{figure}


After doing this commit I can bring up the Fossil ui (see Figure \vref{fig:Starting-Webserver}) and view the project Timeline by picking that tab on the Fossil header. We get this:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/timeline}
\caption{Timeline}


\end{figure}


You can see all my check-ins thus far and you can see after the check-in from Figure \vref{fig:Update-for-new} I did another check-in because I missed some changes in the outline. The check-ins are labeled with the first 10 digits of their hash value and these are active links which you can click to view in detail what was changed in that version. 

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/timeline_detail}

\caption{Timeline Detail\label{fig:Timeline-Detail}}
\end{figure}


I clicked on the very last check-in (the \textbf{LEAF) }and the display is shown above. There are many things you can do at this point. From the list of changed files you can pick the diff link and it will show in text form the changes made in that particular file. The ``Other Links'' section has a very useful ZIP Archive. Clicking this will download a ZIP of this version to your browser. You will find this useful if you want to get a particular version, in fact this is normally how you get a new version of Fossil from the \url{http://www.fossil-scm.org/}. The edit link will be used later to modify a leaf.


\subsection{Update Summary}
\begin{itemize}
\item \textbf{fossil status} and \textbf{fossil extra} will tell you the updated files and files not in the repository before you commit.
\item \textbf{fossil commit - m ``Commit comment'' }Commits a change (or changes). It is very important to have a descriptive comment on your commit.
\end{itemize}

\section{Tickets}

Besides managing your code Fossil has a trouble ticket system. This means you can create a ticket for a problem or feature you are going to add to your system then track your progress. Also you can tie the tickets to specific check-ins of your files. For software this is very useful for bug fixes and feature additions. For example you can look for a bug in the ticket list then have it take you to the change that fixed the problem. Then you know exactly what you did and not have to be confused by other changes you might have made.

When you pick Tickets it will bring up this window. You can create a new ticket, look at the list, or generate a new report. Keeping things simple I will just use the All Tickets list for now.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/ticket_initial}
\caption{Initial Ticket Window}
\end{figure}

Picking ``New Ticket'' I get a form that I fill out like so:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/ticket_form}
\caption{Ticket Form}
\end{figure}


Pretty simple actually. You can put as much or as little detail in here as you wish, but remember this stuff might be really vital 6 weeks or 6 months from now so think of what you would want to know then. When I press Submit I get this showing what I entered.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/ticket_submit}
\caption{Viewing a Ticket}
\end{figure}

Finally picking Tickets then ``All Tickets'' I can see my new ticket in the list marked as Open and in a distinctive color. 

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/ticket_list}
\caption{\label{fig:viewticket}Ticket List with open ticket}

\end{figure}

I try, in handling tickets, to have links from ticket to the commit that addressed the problem and a link from the commit back to the offending ticket. This way looking at the ticket I can get to the changes made and from the timeline I can get the the ticket and its resolution. To do this I will make sure and put the 10 digit hash label from the ticket into the check-in comment and put a link in the resolved ticket to the check-in.

Since I have now written the chapter and put in all these images of what to do I can now add in all the new images to the repository and check this in as another completed operation. And I do that like this:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~add~Images/Single\_user}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/config\_initial.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/initial\_page.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/jim\_setup.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/ticket\_form.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/ticket\_initial.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/ticket\_list.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/ticket\_submit.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/timeline.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/timeline\_detail.epsf}{\scriptsize \par}

{\scriptsize ADDED~~Images/Single\_user/user\_config.epsf}{\scriptsize \par}



{\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}{[}1665c78d94{]}~Ticket~Use\textquotedbl{}}{\scriptsize \par}
\end{lyxcode}
\caption{\label{fig:checkin}Ticket resolving check-in}


\end{figure}


First I added in all the new image files. I am lazy and just told it to add in all the files in the Single\_user directory. I have previously added some of those like \textbf{config\_initial.epsf} but Fossil is smart and knows this and won't add that one twice. Even though it shows it ADDED, it really didn't.

The commit line is very important, as you can see I put 10 digit hash code for the ticket in brackets in the comment. As we will see in the Wiki section this is a link to the Ticket, so when viewing the comment in the Timeline or elsewhere you can click the bracketed item and you would go to the ticket.

Now that I have the items checked in I have to close the ticket. I do that by clicking on its link in the ticket list, that will go the the View Ticket window as shown in Figure \vref{fig:viewticket}. From there I pick edit and fill it in as shown:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/ticket_done}

\caption{Ticket Finish}


\end{figure}


I mark it as ``Closed''. If you have code you can mark this as fixed, tested, or a number of other choices. Another very important step, I brought up the Timeline and copied the link for the commit I had just done in Figure \vref{fig:checkin}. By doing this my ticket is now cross linked with the commit and the commit has a link back to the ticket.


\subsection{Ticket Summary}
\begin{itemize}
\item Tickets are a useful way of reminding you what needs done or bugs fixed
\item When you commit a change that affects a ticket put the 10 digit hash label of the ticket into the commit comment surrounded by brackets, e.g. {[}<10 digit hash>{]} so you can link to the ticket
\item When you close the ticket put in the hash label of the commit that fixed it.
\end{itemize}

\section{\label{sub:Wiki-Use}Wiki Use}

As we saw in Figure \vref{fig:Starting-Webserver} Fossil has a browser based user interface. In addition to the pages that are built in you can add pages to web site via a wiki. This allows you to add code descriptions, user manuals, or other documentation. Fossil keeps all that stuff in one place under version control. A wiki is a web site where you can add pages and links from within your browser. You are given an initial page then if you type {[}newpage{]} this text will turn into a link and if clicked will take you to a new blank page. Remember in Figure \vref{fig:Initial-Webserver-page} that is the initial page for your project and from there you can add new pages. These pages are automatically managed by the Fossil version control system; you don't have to add or commit.

Since I did the setup on repository (see Figure \vref{fig:Initial-Configuration}) the home page has changed to this:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/wiki_blankhome}

\caption{Blank Home Page}


\end{figure}


Not very helpful so the in rest of this chapter I will use the Wiki functions of Fossil to make this more useful. If I pick the Wiki item from the menu bar I get:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/wiki_page}

\caption{\label{fig:Wiki-controls}Wiki controls}


\end{figure}


These are the controls that let you control and modify the wiki. Most important for now is the Formatting rules link. This link takes you to a page that describes what you can do to format a wiki page. If you just type text on a page it will appear but be formatted by your browser. You can type HTML commands to control this formating. It's worth your time to carefully read this page and note what you can and cannot do. The page just lists the valid HTML commands, and if you don't know what they mean I would suggest you find a page like this \url{http://www.webmonkey.com/2010/02/html\_cheatsheet/} and keep it handy. 

Besides the HTML markup the most powerful command for the Wiki is {[}page{]} where it links to a new page. This is how you add pages and how you build your web site of documentation for the repository.

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/wiki_formating}\caption{Wiki Formating}


\end{figure}


I now begin work. What I want to do is change the home page to be non-empty and also put a link on the home page to the PDF of this book. In Figure \vref{fig:Wiki-controls} I click on the first item, the FossilBook home page. This takes me to the home page again but now I have an Edit option. We also have a History option so I could look at older versions of the page. 

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/wiki_homeedit}

\caption{Home page with edit}


\end{figure}


This shows my initial edit and a preview:

\begin{figure}[H]
\includegraphics[scale=0.5]{Images/Single_user/wiki_home}

\caption{Initial Home page}


\end{figure}


The bottom section is an edit window where I type things I want displayed and the top is a preview of what the page will be. As you can see I typed some simple HTML to make a large and centered title. The body of the text I just typed and as you see the browser fits the text to the screen. You can have multiple paragraphs by just putting blank lines between your text. Next I wanted a bulleted list and this is done by typing two spaces, a '{*}' then two more spaces. On each of these lines I have a link to a new (not yet created page). If you look I put these in the form {[} <new page> | <title> {]}. This way I can have a long string that describes the link but have a nice short (no embedded spaces) page name. 

One mistake I usually make at this point is to click one of those new links which takes me to a new blank page. \textbf{OOPS}, if I have not saved this page yet then I find I've lost my changes so far. 

OK, I will save my changes and then go to the new pages. I am doing some complicated things here. The first link is to the book PDF. This will be a file I create in the repository. The \LyX{} program I'm using creates the PDF. I will do that, save it, and add it to the repository. But I don't want to link to a static file, that is I want the most current version of the PDF, the one I save each time I quit for the day. To do this we have to put in a link that looks like this:
\begin{lyxcode}
{[}http:doc/tip/FossilBook.pdf~|~Book~(pdf)~{]}
\end{lyxcode}
This is a special link the Fossil wiki understands, \textbf{doc }says this is documentation. \textbf{tip }says use the most current version; you could put a version link here. And finally since I am going to put the book PDF at the top level I only need the file name. If it was in a subdirectory I would have to say \textbf{doc/tip/subdir/filename. }

The second link is just to a regular page and I can just edit that one just like I did this the main page.


\subsection{Wiki Summary}
\begin{itemize}
\item Format your text using HTML commands like <h1>Title</h1> for page headings
\item Create and link pages using {[} <page> | <Link text> {]}
\item The page designation http:doc/tip/<document path relative to repository> will display any document in the repository that your browser can handle (i.e. pdf, http etc)
\item Never click on a link till AFTER you have saved the page
\end{itemize}

\chapter{Fossil Customization - the TH Scripting language}

\section{Introduction to TH}

\subsection{TH is a Tcl-like language}

TH is a string-based command language closely based on the Tcl language. The language has only a few fundamental constructs and relatively little syntax which is meant to be simple. TH is designed to be the scripting language of the \textquotedblleft{}Fossil\textquotedblright{} source code management system. TH is an interpreted language and it is parsed, compiled and executed when the script runs. In Fossil, TH scripts are typically run to build web pages, often in response to web form submissions.

The basic mechanisms of TH are all related to strings and string substitutions. The TH/Tcl way of doing things is a little different from some other programming languages with which you may already be familiar, so it is worth making sure you understand the basic concepts.


\section{The \textquotedblleft{}Hello, world\textquotedblright{} program}

The traditional starting place for a language introduction is the classic \textquotedbl{}Hello, World\textquotedbl{} program. In TH this program has only a single line:
\begin{lyxcode}
puts~\textquotedblleft{}Hello,~world\textbackslash{}n\textquotedblright{}
\end{lyxcode}
The command to output a string in TH is the puts command. A single unit of text after the puts command will be printed to the output stream. If the string has more than one word, you must enclose the string in double quotes or curly brackets. A set of words enclosed in quotes or curly brackets is treated as a single unit, while words separated by white space are treated as multiple arguments to the command.


\section{TH structure and syntax}


\subsection{Datatypes}

TH has at its core only a single data type which is string. All values in TH are strings, variables hold strings and the procedures return strings. Strings in TH consist of single byte characters and are zero terminated. Characters outside of the ASCII range, i.e. characters in the 0x80-0xff range have no TH meaning at all: they are not considered digits or letters, nor are they considered white space.

Depending on context, TH can interpret a string in four different ways. First of all, strings can be just that: text consisting of arbitrary sequences of characters. Second, a string can be considered a list, an ordered sequence of words separated by white space. Third, a string can be a command. A command is a list where the first word is interpreted as the name of a command, optionally followed by further argument words. Fourth, and last, a string can be interpreted as an expression.

The latter three interpretations of strings are discussed in more detail below. 


\subsection{Lists}

A list in TH is an ordered sequence of items, or words separated by white space. In TH the following characters constitute white space:
\begin{lyxcode}

logo
FossilBook
Artifact Content
Logged in as frans
Home Timeline Files Branches Tags Tickets Wiki Admin Logout
Download Hex Shun
Artifact 7b03c1c83fcd092b090ada102ed76356e9496f2d

    File fossilbook.lyx
        2010-06-26 12:28:12 - part of checkin [9ad19c40d6] on branch trunk - Added section on TH scripting [b832f46d31] (user: jim) [annotate] 

 
logo
FossilBook
Artifact Content
Logged in as frans
Home Timeline Files Branches Tags Tickets Wiki Admin Logout
Download Hex Shun
Artifact 7b03c1c83fcd092b090ada102ed76356e9496f2d

    File fossilbook.lyx
        2010-06-26 12:28:12 - part of checkin [9ad19c40d6] on branch trunk - Added section on TH scripting [b832f46d31] (user: jim) [annotate] 

 ~~~~~'~'~~~~0x20

~~~~~'\textbackslash{}t'~~~0x09

~~~~~'\textbackslash{}n'~~~0x0A

~~~~~'\textbackslash{}v'~~~0x0B

~~~~~'\textbackslash{}f'~~~0x0C

~~~~~'\textbackslash{}r'~~~0x0D
\end{lyxcode}
A word can be any sequence of characters delimited by white space. It is not necessary that a word is alphanumeric at all: \textquotedblleft{}.\%{*}\textquotedblright{} is a valid word in TH. If a word needs to contain embedded white space characters, it needs to be quoted, with either a double quotes or with opening/closing curly brackets. Quoting has the effect of grouping the quoted content into a single list element.

Words cannot start with one of the TH special characters \{ \} {[} {]} \textbackslash{} ; and \textquotedbl{}. Note that a single quote \textquoteleft{} is not a special character in TH. To use one of these characters to start a word it must be escaped, which is discussed further later on.

TH offers several built-in commands for working with lists, such as counting the number of words in a list, retrieving individual words from the list by index and appending new items to a list. These commands are discussed in the section \textquotedblleft{}Working with lists\textquotedblright{}.


\subsection{Commands}

TH casts everything into the mold of a command, even programming constructs like variable assignment and procedure definition. TH adds a tiny amount of syntax needed to properly invoke commands, and then it leaves all the hard work up to the command implementation.

Commands are a special form of list. The basic syntax for a TH command is:
\begin{lyxcode}
command~arg1~arg2~arg3~...
\end{lyxcode}
The command is either the name of a built-in command or a TH procedure.

White space is used to separate the command name and its arguments, and a newline character or semicolon is used to terminate a command. TH comments are lines with a \textquotedblleft{}\#\textquotedblright{} character at the beginning of the line, or with a \textquotedblleft{}\#\textquotedblright{} character after the semicolon terminating a command.


\subsection{Grouping \& substitution}

TH does not interpret the arguments to the commands except to perform grouping, which allows multiple words in one argument, and substitution, which is used to deal with special characters, to fetch variables and to perform nested command calls. Hence, the behavior of the TH command processor can be summarized in three basic steps:
\begin{enumerate}
\item Argument grouping.
\item Value substitution of backslash escapes, variables and nested commands
\item Command invocation.
\end{enumerate}
Note that there is no step to evaluate the arguments to a command. After substitution, arguments are passed verbatim to the command and it is up to the command to evaluate its arguments as needed.


\subsubsection{Argument grouping}

TH has two mechanisms for grouping multiple words into a single item:
\begin{itemize}
\item Double quotes, \textquotedblleft{} \textquotedblright{}
\item Curly brackets, \{ \}
\end{itemize}
Whilst both have the effect of grouping a set of words, they have different impact on the next phase of substitution. In brief, double quotes only group their content and curly brackets group and prevent all substitution on their content.

Grouping proceeds from left to right in the string and is not affected by the subsequent substitution. If a substitution leads to a string which would be grouped differently, it has no effect, as the grouping has already been decided in the preceding grouping phase.


\subsubsection{Value substitutions}

TH performs three different substitutions (see the th.c/thSubstWord code for details)
\begin{itemize}
\item Backslash escape substitution
\item Variable substitution
\item Nested command substitution
\end{itemize}
Like grouping, substitution proceeds from left to right and is performed only once: if a substitution leads to a string which could again be substituted such this not happen. 


\subsubsection{Backslash escape substitution.}

In general, the backslash (\textbackslash{}) disables substitution for the single character immediately following the backslash. Any character immediately following the backslash will stand as literal. This is useful to escape the special meaning of the characters \{ \} {[} {]} \textbackslash{} ; and \textquotedbl{}.

There are two specific strings which are replaced by specific values during the substitution phase. A backslash followed by the letter \textquoteleft{}n\textquoteright{} gets replaced by the newline character, as in C. A backslash followed by the letter \textquoteleft{}x\textquoteright{} and two hexadecimal digits gets replaced by the character with that value, i.e. writing \textquotedblleft{}\textbackslash{}x20\textquotedblright{} is the same as writing a space. Note that the \textbackslash{}x substitution does not \textquotedbl{}keep going\textquotedbl{} as long as it has hex digits as in Tcl, but insists on two digits. The word \textbackslash{}x2121 is not a single exclamation mark, but the 3 letter word !21.


\subsubsection{Variable substitution}

Like any programming language, TH has a concept of variables. TH variables are named containers that hold string values. Variables are discussed in more detail later in this document, for now we limit ourselves to variable substitution.

The dollar sign (\$) may be used as a special shorthand form for substituting variable values. If \$ appears in an argument that isn't enclosed in curly brackets then variable substitution will occur. The characters after the \$, up to the first character that isn't a number, letter, or underscore, are taken as a variable name and the string value of that variable is substituted for the name. For example, if variable foo has the value test, then the command \textquotedblleft{}puts \$foo.c\textquotedblright{} is equivalent to the command:
\begin{lyxcode}
\textquotedblright{}puts~test.c\textquotedblright{}
\end{lyxcode}
There are two special forms for variable substitution. If the next character after the name of the variable is an open parenthesis, then the variable is assumed to be an array name, and all of the characters between the open parenthesis and the next close parenthesis are taken as an index into the array. Command substitutions and variable substitutions are performed on the information between the parentheses before it is used as an index. For example, if the variable x is an array with one element named first and value 87 and another element named 14 and value more, then the command 
\begin{lyxcode}
puts~xyz\$x(first)zyx
\end{lyxcode}
is equivalent to the command 
\begin{lyxcode}
puts~xyz87zyx
\end{lyxcode}
If the variable index has the value `14', then the command 
\begin{lyxcode}
puts~xyz\$x(\$index)zyx
\end{lyxcode}
is equivalent to the command 
\begin{lyxcode}
puts~xyzmorezyx
\end{lyxcode}
See the section Variables and arrays below for more information on arrays. 

The second special form for variables occurs when the dollar sign is followed by an open curly bracket. In this case the variable name consists of all the characters up to the next curly bracket. Array references are not possible in this form: the name between curly brackets is assumed to refer to a scalar variable. For example, if variable foo has the value `test', then the command 
\begin{lyxcode}
set~a~abc\$\{foo\}bar
\end{lyxcode}
is equivalent to the command
\begin{lyxcode}
set~a~abctestbar
\end{lyxcode}
A dollar sign followed by something other than a letter, digit, underscore, or left parenthesis is treated as a literal dollar sign. The following prints a single character \$.
\begin{lyxcode}
puts~x~\$
\end{lyxcode}

\subsubsection{Command Substitution}

The last form of substitution is command substitution. A nested command is delimited by square brackets, {[} {]}. The TH interpreter takes everything between the brackets and evaluates it as a command. It rewrites the outer command by replacing the square brackets and everything between them with the result of the nested command. 

Example:
\begin{lyxcode}
puts~{[}string~length~foobar{]}

=>~6
\end{lyxcode}
In the example, the nested command is: string length foobar. This command returns the length of the string foobar. The nested command runs first. Then, command substitution causes the outer command to be rewritten as if it were:
\begin{lyxcode}
puts~6
\end{lyxcode}
If there are several cases of command substitution within a single command, the interpreter processes them from left to right. As each right bracket is encountered, the command it delimits is evaluated. This results in a sensible ordering in which nested commands are evaluated first so that their result can be used in arguments to the outer command.


\subsubsection{Argument grouping revisited}

During the substitution phase of command evaluation, the two grouping operators, the curly bracket and the double quote are treated differently by the TH interpreter. 

Grouping words with double quotes allows substitutions to occur within the double quotes. A double quote is only used for grouping when it comes after white space. The string a\textquotedblright{}b\textquotedblright{} is a normal 4 character string, and not the two character string ab.
\begin{lyxcode}
puts~a\textquotedblright{}b\textquotedblright{}

=>~a\textquotedblright{}b\textquotedblright{}
\end{lyxcode}
Grouping words within curly brackets disables substitution within the brackets. Again, A opening curly bracket is only used for grouping when it comes after white space. Characters within curly brackets are passed to a command exactly as written, and not even backslash escapes are processed.

Note that curly brackets have this effect only when they are used for grouping (i.e. at the beginning and end of a sequence of words). If a string is already grouped, either with double quotes or curly brackets, and the curly brackets occur in the middle of the grouped string (e.g. \textquotedbl{}foo\{bar\textquotedbl{}), then the curly brackets are treated as regular characters with no special meaning. If the string is grouped with double quotes, substitutions will occur within the quoted string, even between the brackets.

The square bracket syntax used for command substitution does not provide grouping. Instead, a nested command is considered part of the current group. In the command below, the double quotes group the last argument, and the nested command is just part of that group:
\begin{lyxcode}
puts~\textquotedbl{}The~length~of~\$s~is~{[}string~length~\$s{]}.\textquotedbl{}
\end{lyxcode}
If an argument is made up of only a nested command, you do not need to group it with double-quotes because the TH parser treats the whole nested command as part of the group. A nested command is treated as an unbroken sequence of characters, regardless of its internal structure. It is included with the surrounding group of characters when collecting arguments for the main command.


\subsection{Summary}

The following rules summarize the fundamental mechanisms of grouping and substitution that are performed by the TH interpreter before it invokes a command:
\begin{itemize}
\item Command arguments are separated by white space, unless arguments are grouped with curly brackets or double quotes as described below.
\item Grouping with curly brackets, \{\}, prevents substitutions. Curly brackets nest. The interpreter includes all characters between the matching left and right brace in the group, including newlines, semicolons, and nested curly brackets. The enclosing (i.e., outermost) curly brackets are not included in the group\textquoteright{}s value.
\item Grouping with double quotes, \textquotedbl{} \textquotedbl{}, allows substitutions. The interpreter groups everything until another double quote is found, including newlines and semicolons. The enclosing quotes are not included in the group of characters. A double-quote character can be included in the group by quoting it with a backslash, (i.e. \textbackslash{}\textquotedbl{}).
\item Grouping decisions are made before substitutions are performed, which means that the values of variables or command results do not affect grouping.
\item A dollar sign, \$, causes variable substitution. Variable names can be any length, and case is significant. If variable references are embedded into other strings, or if they include characters other than letters, digits, and the underscore, they can be distinguished with the \$\{varname\} syntax.
\item Square brackets, {[}{]}, cause command substitution. Everything between the brackets is treated as a command, and everything including the brackets is replaced with the result of the command. Nesting is allowed.
\item The backslash character, \textbackslash{}, is used to quote special characters. You can think of this as another form of substitution in which the backslash and the next character or group of characters is replaced with a new character.
\item Substitutions can occur anywhere unless prevented by curly bracket grouping. Part of a group can be a constant string, and other parts of it can be the result of substitutions. Even the command name can be affected by substitutions.
\item A single round of substitutions is performed before command invocation. The result of a substitution is not interpreted a second time. This rule is important if you have a variable value or a command result that contains special characters such as spaces, dollar signs, square brackets, or curly brackets. Because only a single round of substitution is done, you do not have to worry about special characters in values causing extra substitutions.
\end{itemize}

\subsubsection{Caveats}
\begin{itemize}
\item A common error is to forget a space between arguments when grouping with curly brackets or quotes. This is because white space is used as the separator, while the curly brackets or quotes only provide grouping. If you forget the space, you will get syntax errors about the wrong number of arguments being applied. The following is an error because of the missing space between \} and \{:

\begin{lyxcode}
if~\{\$x~>~1\}\{puts~\textquotedbl{}x~=~\$x\textquotedbl{}\}
\end{lyxcode}
\item When double quotes are used for grouping, the special effect of curly brackets is turned off. Substitutions occur everywhere inside a group formed with double quotes. In the next command, the variables are still substituted:

\begin{lyxcode}
set~x~xvalue

set~y~\textquotedbl{}foo~\{\$x\}~bar\textquotedbl{}

=>~foo~\{xvalue\}~bar
\end{lyxcode}
\item Spaces are not required around the square brackets used for command substitution. For the purposes of grouping, the interpreter considers everything between the square brackets as part of the current group.
\end{itemize}

\section{TH expressions}

The TH interpreter itself does not evaluate math expressions. TH just does grouping, substitutions and command invocations. However, several built-in commands see one of more of their arguments as expressions and request the interpreter to calculate the value of such expressions.

The \textbf{expr command} is the simplest such command and is used to parse and evaluate expressions:
\begin{lyxcode}
puts~{[}expr~7.4/2{]}

=>~3.7
\end{lyxcode}
Note that an expression can contain white space, but if it does it must be grouped in order to be recognized as a single argument.

Within the context of expression evaluation TH works with three datatypes: two types of number, integer and floating point, and string. Integer values are promoted to floating point values as needed. The Boolean values True and False are represented by the integer values 1 and 0 respectively. The implementation of expr is careful to preserve accurate numeric values and avoid unnecessary conversions between numbers and strings. 

Before expression evaluation takes place, both variable and command substitution is performed on the expression string. Hence, you can include variable references and nested commands in math expressions, even if the expression string was originally quoted with curly brackets. Note that backslash escape substitution is not performed by the expression evaluator.

A TH expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression processor. Where possible, operands are interpreted as integer values. If an operand is not in integer format, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler. For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no numeric interpretation is possible, then an operand is left as a string (and only a limited set of operators may be applied to it). 

Operands may be specified in any of the following ways: 
\begin{itemize}
\item As a numeric value, either integer or floating-point.
\item As a string enclosed in curly brackets. The characters between the opening bracket and matching closing bracket are used as the operand without any substitutions. 
\item As a string enclosed in double quotes. The expression parser performs variable and command substitutions on the information between the quotes, and uses the resulting value as the operand. 
\item As a TH variable, using standard \$ notation. The variable's value is used as the operand. 
\item As a TH command enclosed in square brackets. The command will be executed and its result will be used as the operand. 
\end{itemize}
Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. However, an additional layer of substitution may already have been performed by the command parser before the expression processor was called. As discussed below, it is usually best to enclose expressions in curly brackets to prevent the command parser from performing substitutions on the contents. 

The valid operators are listed below, grouped in decreasing order of precedence: 

\noindent \begin{center}
\begin{tabular}{|c|>{\raggedright}p{3.5in}|}
\hline 
\textbf{Operators} & \textbf{Action}\tabularnewline
\hline 
\hline 
+ - \textasciitilde{} ! & Unary plus, unary minus, bit-wise NOT, logical NOT. None of these operands may be applied to string operands, and bit-wise NOT may be applied only to integers.\tabularnewline
\hline 
{*} / \% & Multiply, divide, remainder. None of these operands may be applied to string operands, and remainder may be applied only to integers.\tabularnewline
\hline 
+ - & Add and subtract. Valid for numeric operands only.\tabularnewline
\hline 
<\textcompwordmark{}< >\textcompwordmark{}>  & Left and right shift. Valid for integer operands only\tabularnewline
\hline 
< > <= >= & Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise. These operators may be applied to strings as well as numeric operands, in which case string comparison is used.\tabularnewline
\hline 
== !=  & Boolean equal and not equal. Each operator produces a zero/one result as per above. Valid for all operand types. \tabularnewline
\hline 
eq ne & Compare two strings for equality (eq) or inequality (ne). These operators return 1 (true) or 0 (false). Using these operators ensures that the operands are regarded exclusively as strings, not as possible numbers: \tabularnewline
\hline 
\& & Bit-wise AND. Valid for integer operands only.\tabularnewline
\hline 
\textasciicircum{} &  Bit-wise XOR. Valid for integer operands only\tabularnewline
\hline 
| & Bit-wise OR. Valid for integer operands only\tabularnewline
\hline 
\&\& & Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise Valid for integer operands only. Note: there is no \textquotedblleft{}shortcut evaluation\textquotedblright{}: the right hand is evaluated even if the left hand evaluated to false.\tabularnewline
\hline 
|| &  Logical OR. Produces a 1 result if either operand is non-zero, 0 otherwise Valid for integer operands only. Note: there is no \textquotedblleft{}shortcut evaluation\textquotedblright{}: the right hand is evaluated even if the left hand evaluated to true\tabularnewline
\hline 
\end{tabular}
\par\end{center}

All of the binary operators group left-to-right within the same precedence level. For example, the expression `4{*}2 < 7' evaluates to 0. 

All internal computations involving integers are done with the C type int, and all internal computations involving floating-point are done with the C type double. Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. 

String values may be used as operands of the comparison operators, although the expression evaluator tries to do comparisons as integer or floating-point when it can. If one of the operands of a comparison is a string and the other has a numeric value, the numeric operand is converted back to a string. 


\section{TH variables}

Like almost all programming languages TH has the concept of variables. TH variables bind a name to a string value. A variable name must be unique in its scope, either the global scope or a local scope. TH supports two types of variables: scalars and arrays. 

TH allows the definition of variables and the use of their values either through `\$'-style variable substitution, the set command, or a few other mechanisms. Variables need not be declared: a new variable will automatically be created each time a new variable name is used. 


\subsection{Working with variables}

TH has two key commands for working with variables, set and unset:
\begin{lyxcode}
set~varname~?value?

unset~varname

info~exists~varname
\end{lyxcode}
The\textbf{ set command} returns the value of variable varname. If the variable does not exist, then an error is thrown. If the optional argument value is specified, then the set command sets the value of varname to value, creating a new variable in the current scope if one does not already exist, and returns its value. 

The \textbf{unset command} removes a variable from its scope. The argument varname is a variable name. If varname refers to an element of an array, then that element is removed without affecting the rest of the array. If varname consists of an array name with no parenthesized index, then the entire array is deleted. The unset command returns an empty string as result. An error occurs if the variable doesn't exist. 

The \textbf{info exists command} returns `1' if the variable named varname exists in the current scope, either the global scope or the current local scope, and returns `0' otherwise. 


\subsubsection{Scalar variables and array variables}

TH supports two types of variables: scalars and arrays. A scalar variable has a single value, whereas an array variable can have any number of elements, each with a name (called its \textquotedbl{}index\textquotedbl{}) and a value. TH arrays are one-dimensional associative arrays, i.e. the index can be any single string. 

If varname contains an open parenthesis and ends with a close parenthesis, then it refers to an array element: the characters before the open parenthesis are the name of the array, and the characters between the parentheses are the index within the array. Otherwise varname refers to a scalar variable. 

For example, the command set {[}x(first) 44{]} will modify the element of x whose index is first so that its new value is 44. Two-dimensional arrays can be simulated in TH by using indices that contain multiple concatenated values. For example, the commands 
\begin{lyxcode}
set~a(2,3)~1

set~a(3,6)~2
\end{lyxcode}
set the elements of a whose indices are 2,3 and 3,6. 

In general, array elements may be used anywhere in TH that scalar variables may be used. If an array is defined with a particular name, then there may not be a scalar variable with the same name. Similarly, if there is a scalar variable with a particular name then it is not possible to make array references to the variable. To convert a scalar variable to an array or vice versa, remove the existing variable with the unset command. 


\subsubsection{Variable scope}

Variables exist in a scope. The TH interpreter maintains a global scope that is available to and shared by all commands executed by it. Each invocation of a user defined command creates a new local scope. This local scope holds the arguments and local variables of that user command invocation and only exists as long a the user command is executing. 

If not in the body of user command, then references to varname refer to a global variable, i.e. a variable in the global scope. In contrast, in the body of a user defined command references to varname refer to a parameter or local variable of the command. However, in the body of a user defined command, a global variable can be explicitly referred to by preceding its name by ::. 

TH offers a special command to access variables not in the local scope of the current command but in the local scope of the call chain of commands that leas to the current command. This is the upvar command: 
\begin{lyxcode}
upvar~?frame?~othervar~myvar~?othervar~myvar~...?
\end{lyxcode}
The \textbf{upvar command} arranges for one or more local variables in the current procedure to refer to variables in an enclosing procedure call, or to global variables. If frame is an integer, then it gives a distance (up the command calling stack) to move. The argument frame may be omitted if othervar is not an integer (frame then defaults to `1'). For each othervar argument, the upvar command makes the variable by that name in the local scope identified by the frame offset accessible in the current procedure by the name given in the corresponding myvar argument. The variable named by othervar need not exist at the time of the call; it will be created the first time myvar is referenced, just like an ordinary variable. The upvar command is only meaningful from within user defined command bodies. Neither othervar nor myvar may refer to an element of an array. The upvar command returns an empty string. The upvar command simplifies the implementation of call-by-name procedure calling and also makes it easier to build new control constructs as TH commands. For example, consider the following procedure: 
\begin{lyxcode}
proc~incr~\{name\}~\{

~~~~upvar~\$name~x

~~~~set~x~{[}expr~\$x+1{]}

\}
\end{lyxcode}
incr is invoked with an argument giving the name of a variable, and it adds one to the value of that variable. 


\section{TH commands, scripts and program flow}

In TH there is actually no distinction between commands (often known as \textquoteleft{}statements\textquoteright{} and 'functions' in other languages) and \textquotedbl{}syntax\textquotedbl{}. There are no reserved words (like if and while) as exist in C, Java, Python, Perl, etc. When the TH interpreter starts up there is a list of built-in, known commands that the interpreter uses to parse a line. These commands include for, set, puts, and so on. They are, however, still just regular TH commands that obey the same syntax rules as all TH commands, both built-in, and those that you create yourself with the proc command. 


\subsection{Commands revisited}

Like Tcl, TH is build up around commands. A command does something for you, like outputting a string, computing a math expression, or generating HTML to display a widget on the screen. 

Commands are a special form of list. The basic syntax for a TH command is: 
\begin{lyxcode}
command~arg1~arg2~arg3~...
\end{lyxcode}
The command is either the name of a built-in command or a TH procedure.

White space is used to separate the command name and its arguments, and a newline character or semicolon is used to terminate a command. TH comments are lines with a \textquotedblleft{}\#\textquotedblright{} character at the beginning of the line, or with a \textquotedblleft{}\#\textquotedblright{} character after the semicolon terminating a command. 


\subsection{Scripts}

Normally, control in TH flows from one command to the next. The next command is either in the same list (if the current command is terminated with a semicolon) or in the next input line. A TH program is thus a TH list of commands. 

Such a list of commands is referred to as a \textquotedblleft{}script\textquotedblright{}. A script is hence a self contained code fragment containing one or more commands. The commands in a script are analogous to statements in other programming languages. 

Some commands take one or more scripts as arguments and run those scripts zero or more times depending on the other arguments. For example, the if command executes either the then script or the else script once, depending on the if expression being true or false. The command that takes a script will perform the normal grouping and substitution as part of executing the script. 
\begin{quote}
Note that the script always needs to be enclosed in curly brackets to prevent substitution taking place twice: once as part of the execution of the top level command and once again when preparing the script. Forgetting to enclose a script argument in curly brackets is common source of errors. 
\end{quote}
A few commands (return, error, break and continue) immediately stop execution of the current script instead of passing control to the next command in the list. Control is instead returned to the command that initiated the execution of the current script. 


\subsection{Command result codes}

Each command produces two results: a result code and a string. The code indicates whether the command completed successfully or {\scriptsize not}, and the string gives additional information. The valid codes are defined in `th.h', and are: 

\noindent \begin{center}
\begin{tabular}{|c|c|>{\raggedright}p{3.5in}|}
\hline 
\textbf{Name} & \textbf{Value} & \textbf{Meaning}\tabularnewline
\hline 
\hline 
TH\_OK & 0 & \multicolumn{1}{l|}{This is the normal return code. The string gives the command's return value}\tabularnewline
\hline 
TH\_ERROR & 1 & Indicates that an error occurred; the string gives a message describing the error.\tabularnewline
\hline 
TH\_RETURN & 3 & Indicates that the return command has been invoked. The string gives the return value for the procedure or command.\tabularnewline
\hline 
TH\_BREAK & 2 & Indicates the innermost loop should abort immediately. The string contains \textquotedblleft{}break\textquotedblright{} or the argument of break, if any\tabularnewline
\hline 
TH\_CONTINUE & 4 & Indicates that the innermost loop should go on to the next iteration.. The string contains \textquotedblleft{}break\textquotedblright{} or the argument of break, if any\tabularnewline
\hline 
\end{tabular}
\par\end{center}

TH programmers do not normally need to think about return codes, since TH\_OK is almost always returned. If anything else is returned by a command, then the TH interpreter immediately stops processing commands and returns to its caller. If there are several nested invocations of the TH interpreter in progress, then each nested command will usually return the error to its caller, until eventually the error is reported to the top-level application code. The application will then display the error message for the user. 

In a few cases, some commands will handle certain \textquotedbl{}error\textquotedbl{} conditions themselves and not return them upwards. For example, the for command checks for the TH\_BREAK code; if it occurs, for stops executing the body of the loop and returns TH\_OK to its caller. The for command also handles TH\_CONTINUE codes and the procedure interpreter handles TH\_RETURN codes. The catch command allows TH programs to catch errors and handle them without aborting command interpretation any further. 


\subsection{Flow control commands}

The flow control commands in TH are:
\begin{lyxcode}
if~expr1~body1~?elseif~expr2~body2?~?~?else?~bodyN?

for~init~condition~incr~script

break~~~~?value?

continue~?value?

error~~~~?value?

catch~script~?varname?
\end{lyxcode}
Below each command is discussed in turn

The \textbf{if command} has the following syntax:
\begin{lyxcode}
if~expr1~body1~?elseif~expr2~body2?~?~?else?~bodyN?
\end{lyxcode}
The expr arguments are expressions, the body arguments are scripts and the elsif and else arguments are keyword constant strings. The if command optionally executes one of its body scripts. 

The expr arguments must evaluate to an integer value. If it evaluates to a non-zero value the following body script is executed and upon return from that script processing continues with the command following the if command. If an expr argument evaluates to zero, its body script is skipped and the next option is tried. When there are no more options to try, processing also continues with the next command. 

The if command returns the value of the executed script, or \textquotedblleft{}0\textquotedblright{} when no script was executed. 

The \textbf{for command} has the following syntax:
\begin{lyxcode}
for~init~condition~incr~body
\end{lyxcode}
The init, incr and body arguments are all scripts. The condition argument is an expression yielding an integer result. The for command is a looping command, similar in structure to the C for statement. 

The for command first invokes the TH interpreter to execute init. Then it repeatedly evaluates condition as an expression; if the result is non-zero it invokes the TH interpreter on body, then invokes the TH interpreter on incr, then repeats the loop. The command terminates when test evaluates to zero. 

If a continue command is invoked within execution of the body script then any remaining commands in the current execution of body are skipped; processing continues by invoking the TH interpreter on incr, then evaluating condition, and so on. If a break command is invoked within body or next, then the for command will return immediately. The operation of break and continue are similar to the corresponding statements in C. 

The for command returns an empty string.

The \textbf{break command} has the following syntax:
\begin{lyxcode}
break~?value?
\end{lyxcode}
The break command returns immediately from the current procedure (or top-level command), with value as the return value and TH\_BREAK as the result code. If value is not specified, the string \textquotedblleft{}break\textquotedblright{} will be returned as result. 

The \textbf{continue command} has the following syntax: 
\begin{lyxcode}
continue~?value?
\end{lyxcode}
The continue command returns immediately from the current procedure (or top-level command), with value as the return value and TH\_CONTINUE as the result code. If value is not specified, the string \textquotedblleft{}continue\textquotedblright{} will be returned as result. 

The \textbf{error command} has the following syntax:
\begin{lyxcode}
error~?value?
\end{lyxcode}
The error command returns immediately from the current procedure (or top-level command), with value as the return value and TH\_ERROR as the result code. If value is not specified, the string \textquotedblleft{}error\textquotedblright{} will be returned as result. 

The \textbf{catch command} has the following syntax:
\begin{lyxcode}
catch~script~?varname?
\end{lyxcode}
The catch command may be used to prevent errors from aborting command interpretation. The catch command calls the TH interpreter recursively to execute script, and always returns a TH\_OK code, regardless of any errors that might occur while executing script. 

The return value from catch is a decimal string giving the code returned by the TH interpreter after executing script. This will be `0' (TH\_OK) if there were no errors in command; otherwise it will have a non-zero value corresponding to one of the exceptional result codes. If the varname argument is given, then it gives the name of a variable; catch sets the value of the variable to the string returned from running script (either a result or an error message). 


\subsection{Creating user defined commands}

The \textbf{proc command} creates a new command. The syntax for the proc command is: 
\begin{lyxcode}
proc~name~args~body
\end{lyxcode}
The proc command creates a new TH command procedure, name, replacing any existing command there may have been by that name. Whenever the new command is invoked, the contents of body will be executed by the TH interpreter. 

The parameter args specifies the formal arguments to the procedure. It consists of a list, possibly empty, each of whose elements specifies one argument. Each argument specifier is also a list with either one or two fields. If there is only a single field in the specifier, then it is the name of the argument; if there are two fields, then the first is the argument name and the second is its default value. Curly brackets and backslashes may be used in the usual way to specify complex default values. 

The proc command returns the null string.


\subsection{Execution of user defined commands}

If a command is a user defined command (i.e. a command created with the proc command), then the TH interpreter creates a new local variable context, binds the formal arguments to their actual values (i.e. TH uses call by value exclusively) and loads the body script. Execution then proceeds with the first command in that script. Execution ends when the last command has been executed or when one of the returning commands is executed. When the script ends, the local variable context is deleted and processing continues with the next command after the user defined command.

More in detail, when a user defined command is invoked, a local variable is created for each of the formal arguments to the procedure; its value is the value of corresponding argument in the invoking command or the argument's default value. Arguments with default values need not be specified in a procedure invocation. However, there must be enough actual arguments for all the formal arguments that don't have defaults, and there must not be any extra actual arguments. 

There is one special case to permit procedures with variable numbers of arguments. If the last formal argument has the name args, then a call to the procedure may contain more actual arguments than the procedure has formals. In this case, all of the actual arguments starting at the one that would be assigned to args are combined into a list (as if the list command had been used); this combined value is assigned to the local variable args. 

When body is being executed, variable names normally refer to local variables, which are created automatically when referenced and deleted when the procedure returns. One local variable is automatically created for each of the procedure's arguments. Global variables can be accessed by using the :: syntax.

When a procedure is invoked, the procedure's return value is the value specified in a return command. If the procedure doesn't execute an explicit return, then its return value is the value of the last command executed in the procedure's body. If an error occurs while executing the procedure body, then the procedure as a whole will return that same error.

The syntax for the return command is:
\begin{lyxcode}
return~?-code~code?~?value?
\end{lyxcode}
The optional argument pair \textendash{}code code allows to change the return status code from the default of TH\_OK to another status code. This code has to be specified with its numeric value. 


\subsection{Special commands}

TH includes three core commands that assist with working with commands. They are:
\begin{lyxcode}
breakpoint~args

rename~oldcmd~newcmd

uplevel~?level?~script
\end{lyxcode}
The \textbf{breakpoint command} does nothing. It is used as placeholder to place breakpoints during debugging.

The\textbf{ rename command} renames a user defined or a built-in command. The old name is removed and the new name is inserted in the interpreter\textquoteright{}s command table.

The \textbf{uplevel command} executes a command in the variable scope of a command higher up in the call chain. The script argument is evaluated in the variable scope indicated by level. The uplevel command returns the result of that evaluation. If level is an integer, then it gives a distance (up the procedure calling stack) to move before executing the command. If level is omitted then it defaults to `1'. 

For example, suppose that procedure a was invoked from top-level, and that it called b, and that b called c. Suppose that c invokes the uplevel command. If level is `1' or omitted, then the command will be executed in the variable context of b. If level is `2' then the command will be executed in the variable context of a. If level is `3' then the command will be executed at top-level (i.e. only global variables will be visible).

The uplevel command causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. In the above example, suppose c invokes the command 
\begin{lyxcode}
uplevel~1~\{set~x~43;~d\}
\end{lyxcode}
where d is another TH procedure. The set command will modify the variable x in the context of b, and d will execute at level 3, as if called from b. If it in turn executes the command 
\begin{lyxcode}
uplevel~\{set~x~42\}
\end{lyxcode}
then the set command will modify the same variable x in the context of b context: the procedure c does not appear to be on the call stack when d is executing. 


\section{working with strings}

TH provides the \textbf{string command} to facilitate working with strings. The string command is a single command with seven subcommands, identified by the first argument. The first argument serves no purpose other than to identify the subcommand. If the first argument does not match a subcommand, an error is thrown.

The seven string subcommands are:
\begin{lyxcode}
string~length~string

string~compare~string1~string2

string~first~needle~haystack~?startindex?

string~last~needle~haystack~?startindex?

string~range~string~first~last

string~repeat~string~count

string~is~alnum~string
\end{lyxcode}
The \textbf{string length subcommand} takes one parameter, which is a string. It returns the decimal string with the length of the string. As TH uses a single byte character encoding the string size is both the size in characters and in bytes.

The \textbf{string compare subcommand} performs a character-by-character comparison of argument strings string1 and string2 in the same way as the C strcmp procedure. It returns a decimal string with value -1, 0, or 1, depending on whether string1 is lexicographically less than, equal to, or greater than string2. 

The \textbf{string first subcommand} searches argument haystack for a sequence of characters that exactly match the characters in argument needle. If found, it returns a decimal string with the index of the first character in the first such match within haystack. If not found, it returns return -1. The optional integer argument startindex specifies the position where the search begins; the default value is 0, i.e. the first character in haystack.

The \textbf{string last subcommand} searches argument haystack for a sequence of characters that exactly match the characters in argument needle. If found, it returns a decimal string with the index of the first character in the last such match within haystack. If not found, it returns return -1. The optional integer argument startindex specifies the position where the search begins; the default value is 0, i.e. the first character in haystack.

The \textbf{string range subcommand} returns a range of consecutive characters from argument string, starting with the character whose index is first and ending with the character whose index is last. An index of zero refers to the first character of the string. last may be end to refer to the last character of the string. If first is less than zero then it is treated as if it was zero, and if last is greater than or equal to the length of the string then it is treated as if it were end. If first is greater than last then an empty string is returned.

The \textbf{string repeat subcommand} returns a string that is formed by repeating the argument string for count times. The argument count must be an integer. If count is zero or less the empty string is returned.

The \textbf{string is alnum subcommand} tests whether the argument string is an alphanumeric string, i.e. a string with only alphanumeric characters. It returns a decimal string with value 1 if the string is alphanumeric, and with value 0 it is not.


\section{working with lists}

The list is the basic TH data structure. A list is simply an ordered collection of items, numbers, words, strings, or other lists. For instance, the following string is a list with four items. The third item is a sub-list with two items: 
\begin{lyxcode}
\{first~second~\{a~b\}~fourth\}~
\end{lyxcode}
TH has three core commands to work with lists:
\begin{lyxcode}
list~?arg1~?arg2?~...?

lindex~list~index

llength~list
\end{lyxcode}
The \textbf{list command} returns a list comprising all the args. Braces and backslashes get added as necessary, so that the lindex command may be used on the result to re-extract the original arguments. For example, the command 
\begin{lyxcode}
list~a~b~\{c~d~e\}~\{f~\{g~h\}\}
\end{lyxcode}
will return 
\begin{lyxcode}
a~b~\{c~d~e\}~\{f~\{g~h\}\}
\end{lyxcode}
The \textbf{lindex command} treats argument list as a TH list and returns the element with index number index from it. The argument index must be an integer number and zero refers to the first element of the list. In extracting the element, the lindex command observes the same rules concerning braces and quotes and backslashes as the TH command interpreter; however, variable substitution and command substitution do not occur. If index is negative or greater than or equal to the number of elements in value, an empty string is returned. 

The \textbf{llength command} treats argument list as a list and returns a decimal string giving the number of elements in it.

\chapter{What's next ?}

This book so far has covered how to use the many features of Fossil and has, I hope, interested you in using it. The question \textquotedbl{}what's next\textquotedbl{} now comes up. First go to the Fossil website \url{http://www.fossil-scm.org/}. While there you can go to the Wiki link and then list all Wiki pages. There are all sorts of topics covered there in depth. If that still doesn't help, you can join the Fossil mailing list (see Wiki links) and look at the archives or directly ask a question. I have found the list to be very helpful and have had my questions asked very quickly.

On the mailing lists you will see long discussions of changes to be made to Fossil, some of these are accepted very quickly and will appear within hours in the Fossil source code. Others engender long discussions (in particular discussion of changes to the Wiki) and it is interesting to read the pros and cons of suggested changes. 

Fossil is an evolving program but if you get a version that has all the features you need you can stick with that version as long as you like. Going to a new version though is simple and just requires a \textbf{rebuild} of your current repositories. The developers have been very careful to preserve the basic structure so it is easy and safe to switch versions.

Finally if you wish to contribute to the project there are many things to do (See the To Do List in the Wiki). 

{\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf540
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fswiss\fcharset0 ArialMT;\f2\fmodern\fcharset0 CourierNewPSMT;
}
{\colortbl;\red255\green255\blue255;\red32\green0\blue255;\red72\green255\blue0;\red236\green0\blue0;
\red39\green77\blue175;}
{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc2\leveljcn2\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid0\'02\'05.;}{\levelnumbers\'01;}}{\listname ;}\listid1}}
{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}}
\margl1440\margr1440\vieww14780\viewh17320\viewkind0
\deftab720
\pard\pardeftab720\sa240\ql\qnatural

\f0\fs20 \cf0 Hi\uc0\u8232 \u8232 I've simulated the merges based on files, i downloaded from your repo. I got a conflict while using the backout option to get your editings without marilyn's patches. I solved this conclict by simple choosing one of the variants. Here you can see:
\fs24 \
\pard\pardeftab720\sa240\ql\qnatural
\cf0 {{\NeXTGraphic unknown.bmp \width14235 \height3570
}¬}\pard\pardeftab720\sa240\ql\qnatural
\cf0 \
\pard\tx220\tx720\pardeftab720\li720\fi-720\ql\qnatural
\ls1\ilvl0
\fs20 \cf0 {\listtext	1.	}a commit of marilyn's version at the left fork
\fs24 \
\ls1\ilvl0
\fs20 {\listtext	2.	}a commit of jim's changes including marilyn's patches
\fs24 \
\ls1\ilvl0
\fs20 {\listtext	3.	}a commit of jim's version, without marilyn's patches. I got this by using(fossil merge --backout a91582b699) and manually solving the conflict. I added an additional change to force a new conflict to generate a conflict situation for the fossil-merge-call.
\fs24 \
\pard\pardeftab720\ql\qnatural
\cf0 \'a0\
\'a0\
\pard\pardeftab720\ql\qnatural

\f1\fs20 \cf2 The global timeline displays a line, indicating the backout-merge. In my text, i've removed this line. Attached, you'll find both versions. So this is my proposal:
\f0\fs24 \cf0 \
\'a0\

\f1\fs20 \cf2 1. changing the current\'a0 paragraph by using a 4th level
\f0\fs24 \cf0 \
\'a0\

\f1\fs20 \cf2 3.4.5.1 Using external patch-tools
\f0\fs24 \cf0 \

\f1\fs20 \cf2 ... your stuff\'a0...
\f0\fs24 \cf0 \
\'a0\

\f1\fs20 \cf2 2. adding a new paragraph for the fossil-merge:
\f0\fs24 \cf0 \

\f1\fs20 \cf2 ------------------------------------------------------------------------------------------------------------------------
\f0\fs24 \cf0 \

\f1\fs20 \cf2 3.4.5.2 Using fossil
\f0\fs24 \cf0 \

\f1\fs20 \cf2 It's also possible to do merge by using fossil. Asuming, we have similar situation like above, but jim has commit his changes. In this example, jim as commit his changes in two steps, ignoring the fork by forcing the commit using the -k option with:
\f0\fs24 \cf0 \
\'a0\
\pard\pardeftab720\ql\qnatural

\f2\fs20 \cf2 E:\\Profile\\Ratte\\data\\organize\\fossil-w32\\fossil-book>fossil commit -m "adding some changes of jim"\
fossil: would fork.\'a0 "update" first or use -f or --force.
\f0\fs24 \cf0 \
\'a0\

\f2\fs20 \cf2 E:\\Profile\\Ratte\\data\\organize\\fossil-w32\\fossil-book>fossil commit -f -m "adding some other changes of jim"\
New_Version: df9f2ff6b14ef65a9dd2162f8bd20c78e1628165\
\pard\pardeftab720\ql\qnatural

\f1 \cf2 Now we habve a fork on the timeline:
\f0\fs24 \cf0 \
\pard\pardeftab720\ql\qnatural
\cf0 {{\NeXTGraphic 1__#$!@%!#__unknown.bmp \width14235 \height3570
}¬}\pard\pardeftab720\ql\qnatural
\cf0 \
\pard\pardeftab720\ql\qnatural

\f2\fs20 \cf2 E:\\Profile\\Ratte\\data\\organize\\fossil-w32\\fossil-book>fossil sta\
repository:\'a0\'a0 E:/Profile/Ratte/data/organize/fossil-w32/fossil-book.fossil\
local-root:\'a0\'a0 E:/Profile/Ratte/data/organize/fossil-w32/fossil-book/\
server-code:\'a0 4a0dce6d271bc75b55e7d0c5547128f063b0dbc6\
checkout:\'a0\'a0\'a0\'a0 df9f2ff6b14ef65a9dd2162f8bd20c78e1628165 2010-06-01 17:37:40 UTC\
parent:\'a0\'a0\'a0\'a0\'a0\'a0 f10f68d7175857ae5d39e208d246f281940edaf4 2010-06-01 17:35:31 UTC\
parent:\'a0\'a0\'a0\'a0\'a0\'a0 d9e10e26021f8f76f4bb8259a319ce0a5780c832 2010-06-01 17:21:34 UTC\
tags:\'a0\'a0\'a0\'a0\'a0\'a0\'a0\'a0 trunk\
EDITED\'a0\'a0\'a0\'a0 fossilbook.lyx\
\pard\pardeftab720\ql\qnatural

\f1 \cf2 To solve the fork,, we can simply use the fossil buildin merge command:\
\pard\pardeftab720\ql\qnatural

\f2 \cf2 E:\\Profile\\Ratte\\data\\organize\\fossil-w32\\fossil-book>fossil merge a91582b699\
MERGE fossilbook.lyx\
***** 2 merge conflicts in fossilbook.lyx
\f1 \
\'a0\
The local file now has Marilyn's changes. The merge produced two conflicts, which have to be solved manually. They are shown in the file like this:\

\f2 >>>>>>> BEGIN MERGE CONFLICT\
\pard\pardeftab720\ql\qnatural
\cf3 \'a0Thanks to Fossil's distributed design once the set up is done using it\
\'a0with multiple users is not much different than the single user case.\
\'a0Fossil will automatically manage the most multiple user details.\
\pard\pardeftab720\ql\qnatural
\cf2 ============================
\f1 \
\'a0\
\pard\pardeftab720\ql\qnatural

\f2 \cf4 \'a0Thanks to Fossil's distributed design once the set up is done using is\
\'a0not much different than the single user case with Fossil managing automatically\
\'a0the multiple user details.\
\pard\pardeftab720\ql\qnatural
\cf2 <<<<<<< END MERGE CONFLICT
\f1 \
\'a0\
Edit the file and simply commit your new version:\

\f2 E:\\Profile\\Ratte\\data\\organize\\fossil-w32\\fossil-book>fossil commit -m "merging marilyn's fork back"\
New_Version: acdd676d3ab157769496f6845ccc7652985c1d03\
\pard\pardeftab720\ql\qnatural

\f0\fs24 \cf0 {{\NeXTGraphic 2__#$!@%!#__unknown.bmp \width14310 \height3885
}¬}\pard\pardeftab720\ql\qnatural

\f2\fs20 \cf2 \
\pard\pardeftab720\ql\qnatural

\f1 \cf2 Marilyn can simply update to the new version. If we look at the global timeline, we can see the indicator lines for the merge:\
\pard\pardeftab720\ql\qnatural

\f0\fs24 \cf0 {{\NeXTGraphic 3__#$!@%!#__unknown.bmp \width12855 \height2910
}¬}\pard\pardeftab720\ql\qnatural

\f1\fs20 \cf2 \
\pard\pardeftab720\ql\qnatural

\f2 \cf2 \
\pard\pardeftab720\ql\qnatural

\f1 \cf2 ------------------------------------------------------------------------------------------------------------------------\
I can send additional infos.\
\'a0\
best regards\
Wolfgang\
\pard\pardeftab720\ql\qnatural

\f0 \cf0 \'a0
\fs24 \
\pard\pardeftab720\sa200\ql\qnatural

\fs20 \cf0 \uc0\u8232 \u8232 \u8232 -----Urspr\'fcngliche Nachricht-----\u8232 Von: jim Schimpf [{\field{\*\fldinst{HYPERLINK "mailto:jim.schimpf@gmail.com"}}{\fldrslt \cf5 \ul \ulc5 mailto:jim.schimpf@gmail.com}}]\uc0\u8232 Gesendet: Dienstag, 1. Juni 2010 18:47\u8232 An: Wolfgang Stumvoll\u8232 Betreff: Re: AW: Fossilbook - great jon and...\u8232 \u8232 \u8232 It doesn't have to be the exact files another example is OK.\'a0 But if\'a0\u8232 you want the originals they are in the Fossil timeline on the web site.\u8232 \u8232 \'a0\'a0\'a0\'a0\'a0\'a0\'a0 --jim\u8232 \u8232 On Jun 1, 2010, at 12:39 PM, Wolfgang Stumvoll wrote:\u8232 \u8232 > Hi\u8232 >\u8232 > I can easiely create an example and\'a0 send you screenshots of\u8232 > * the dos box with the commands\u8232 > * the timeline-page of fossil\u8232 >\u8232 > If you can send me the original files, you used for your example, i'll\u8232 > can do the merge in a clean repository with this file. Diffs and file\u8232 > output would match your example, Artefact-id's and OS-screenshot's not\u8232 > :-(\u8232 >\u8232 > Wolfgang\u8232 >\u8232 > -----Urspr\'fcngliche Nachricht-----\u8232 > Von: jim Schimpf [{\field{\*\fldinst{HYPERLINK "mailto:jim.schimpf@gmail.com"}}{\fldrslt \cf5 \ul \ulc5 mailto:jim.schimpf@gmail.com}}]\uc0\u8232 > Gesendet: Dienstag, 1. Juni 2010 18:29\u8232 > An: Wolfgang Stumvoll\u8232 > Betreff: Re: Fossilbook - great jon and...\u8232 >\u8232 >\u8232 > Thank you for the comments (and catching the dumb spelling mistake). I\u8232 > would be interested in your merge examples and would work them into\u8232 > the chapter and also in the command section where merge is define.\'a0 Do\u8232 > you have screen captures (text or pictures) ?\'a0 I did have some trouble\u8232 > with the merge section as I didn't have a huge amount of experience\u8232 > with it.\'a0 Merge is the degenerate case in the example project since\u8232 > there is really only one source file.\'a0 In more diverse code projects\u8232 > it is important but won't happen as often.\u8232 >\u8232 > \'a0\'a0\'a0\'a0\'a0 Thanks again for the comments.\u8232 >\u8232 > \'a0\'a0\'a0\'a0\'a0 --jim schimpf\u8232 >\u8232 > On Jun 1, 2010, at 12:15 PM, Wolfgang Stumvoll wrote:\u8232 >\u8232 >> Hi Jim\u8232 >>\u8232 >> I really like your book. I took a quick look through and came to the\u8232 >> conclusion:\u8232 >>\u8232 >> * it gives a good overview over source code control\u8232 >> * explanies very well the basics of fossil\u8232 >> * gives a overview over the available commands\u8232 >>\u8232 >> I detected some things, i didn't know and which will help me in the\u8232 >> future.\u8232 >>\u8232 >> Up to now, i have to remarks to the book\u8232 >> 1. the chapter 'merge' should also explain the very simple method, of\u8232 >> using the fossil-internal meerge command. Especially on Windows,\u8232 >> their\u8232 >\u8232 >> is no external patch program - i'm running fossil in a windows\u8232 >> environment with a WHS-server machine, WinXP-Pro/WinXP-Home and Win7\u8232 >> clients. In this environment it's a good thing, only to use the\u8232 >> fossil\u8232 >\u8232 >> buildt in features :-) 2. There is a typo in 4.5.6. repositiry sounds\u8232 >> funny :-)\u8232 >>\u8232 >> If you like it, i could send you some missing merge-variant. The only\u8232 >> problem would be, that the examples would not be the same (other rep,\u8232 >> other OS).\u8232 >>\u8232 >> Sincerely\u8232 >> Wolfgang({\field{\*\fldinst{HYPERLINK "mailto:ratwhs@stumvolls.de"}}{\fldrslt \cf5 \ul \ulc5 ratwhs@stumvolls.de}})\uc0\u8232 >>\u8232 >\
\pard\pardeftab720\ql\qnatural

\fs24 \cf0 {{\NeXTGraphic pre-merge.jpg \width14235 \height3570
}¬}\pard\pardeftab720\ql\qnatural
\cf0 {{\NeXTGraphic post-merge.jpg \width14310 \height3885
}¬}\pard\pardeftab720\ql\qnatural
\cf0 {{\NeXTGraphic timeline-post-optimized.jpg \width12855 \height2910
}¬}\pard\pardeftab720\ql\qnatural
\cf0 {{\NeXTGraphic timeline-post-orig.jpg \width12855 \height2910
}¬}}

WhiteBook:jsonp marilyn$ fossil update
Autosync:  http://Marilyn@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:             130          1          0          0
Received:        1150         25          0          0
Send:             412          7          0          0
Received:        3274         31          1          5
Total network traffic: 843 bytes sent, 2709 bytes received
UPDATE json-src/qdj_token.c
UPDATE json-src/qdj_util.c
UPDATE main.c

*** Before commit

551 jsonp> fossil commit -m "[d23bf4bbbb] Remove warnings"
Autosync:  http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:             130          1          0          0
Received:         874         19          0          0
Total network traffic: 339 bytes sent, 771 bytes received
fossil: would fork.  "update" first or use -f or --force.
552 jsonp> 

*** After commit

552 jsonp> fossil commit -m "[d23bf4bbbb] Remove warnings" -f
Autosync:  http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:             130          1          0          0
Received:         874         19          0          0
Total network traffic: 338 bytes sent, 771 bytes received
New_Version: 1beab955418a942ab9953c4865109ff46cbbd691
Autosync:  http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:            2646         25          0          4
Received:        1058         23          0          0
Total network traffic: 1498 bytes sent, 864 bytes received
**** warning: a fork has occurred *****

556 jsonp> fossil merge b72e96832e
UPDATE docs/qdj.lyx
UPDATE docs/qdj.pdf


556 jsonp> fossil merge b72e96832e
UPDATE docs/qdj.lyx
UPDATE docs/qdj.pdf
557 jsonp> fossil status
repository:   /Users/jschimpf/Public/FOSSIL/jsonp.fossil
local-root:   /Users/jschimpf/Public/jsonp/
server-code:  d3e7932b0b0f5e704264ba30adeae14978c08bc6
checkout:     1beab955418a942ab9953c4865109ff46cbbd691 2010-06-08 10:44:56 UTC
parent:       6edbaf5fa8e4d061c2e04e7fd481e7663b090bd3 2010-06-07 10:45:57 UTC
tags:         trunk
UPDATED_BY_MERGE docs/qdj.lyx
UPDATED_BY_MERGE docs/qdj.pdf
MERGED_WITH b72e96832e024f235696dcd6c5d0ddcc2cb38238
558 jsonp> fossil commit -m "After merging in changes"
Autosync:  http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:             130          1          0          0
Received:        1058         23          0          0
Total network traffic: 340 bytes sent, 864 bytes received
New_Version: 3d73c03edee33cdc2e1bd8a47de57b7a6b6d880a
Autosync:  http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
                Bytes      Cards  Artifacts     Deltas
Send:            1737         26          0          1
Received:        1104         24          0          0
Total network traffic: 1101 bytes sent, 888 bytes received
559 jsonp> 

%% This BibTeX bibliography file was created using BibDesk.
%% http://bibdesk.sourceforge.net/


%% Created for Jim at 2010-06-08 07:13:28 -0400 


%% Saved with string encoding Western (ASCII) 



@techreport{JSON,
	Author = {D. Crockford},
	Date-Added = {2010-06-08 07:10:35 -0400},
	Date-Modified = {2010-06-08 07:13:28 -0400},
	Institution = {Network Working Group},
	Keywords = {JSON JavaScript Objects},
	Month = {July},
	Number = {4627},
	Title = {The application/json Media Type for JavaScript Object Notation},
	Type = {Request for Comments},
	Urldate = {8-Jun-2010},
	Year = {2006},
	Bdsk-Url-1 = {http://www.ietf.org/rfc/rfc4627.txt?number=4627}}

@url{subversion,
	Author = {Subversion Software project},
	Date-Added = {2010-05-12 06:40:29 -0400},
	Date-Modified = {2010-05-12 06:43:02 -0400},
	Keywords = {subversion, version control systems},
	Lastchecked = {12-May-2010},
	Title = {Apache Subversion},
	Urldate = {12-May-2010},
	Bdsk-Url-1 = {http://subversion.apache.org/}}

@url{FOSSIL-HOME,
	Author = {D. Richard Hipp},
	Date-Added = {2010-04-30 06:36:02 -0400},
	Date-Modified = {2010-04-30 06:38:54 -0400},
	Keywords = {Fossil wiki},
	Lastchecked = {30-April-2010},
	Title = {Fossil Home Page},
	Urldate = {http://www.fossil-scm.org/index.html/doc/tip/www/index.wiki},
	Bdsk-Url-1 = {http://www.fossil-scm.org/index.html/doc/tip/www/index.wiki}}

@url{USE-SCCS,
	Author = {University of Texas},
	Date-Added = {2010-04-30 06:19:37 -0400},
	Date-Modified = {2010-04-30 06:20:45 -0400},
	Keywords = {SCCS use UTexas},
	Lastchecked = {30-April-2010},
	Title = {How we use SCCS},
	Urldate = {http://www.utexas.edu/cc/unix/OurSCCS.html},
	Bdsk-Url-1 = {http://www.utexas.edu/cc/unix/OurSCCS.html}}

@url{LyX,
	Author = {Mattias Ettrich},
	Date-Added = {2010-04-25 07:23:20 -0400},
	Date-Modified = {2010-04-25 07:25:52 -0400},
	Keywords = {Tex LaTex document processor},
	Lastchecked = {25-Apr-2010},
	Title = {LyX - The Document Processor},
	Urldate = {www.lyx.org},
	Bdsk-Url-1 = {http://www.lyx.org/}}

@url{RCS,
	Author = {Walter F. Tichy},
	Date-Added = {2010-04-25 06:56:56 -0400},
	Date-Modified = {2010-04-25 06:58:43 -0400},
	Keywords = {version control systems},
	Lastchecked = {25-Apr-2010},
	Title = {RCS - A System For Version Control},
	Urldate = {http://www.burlingtontelecom.net/~ashawley/rcs/tichy1985rcs/html/index.html#id2456539},
	Bdsk-Url-1 = {http://www.burlingtontelecom.net/~ashawley/rcs/tichy1985rcs/html/index.html#id2456539}}

@article{CVS,
	Author = {Dick Grune},
	Date-Added = {2010-04-25 06:52:55 -0400},
	Date-Modified = {2010-04-25 06:56:06 -0400},
	Journal = {unpublished},
	Keywords = {concurrency, version control systems, RCS, multiple file update, user interface},
	Title = {Concurrent Versions System, A Method for Independent Cooperation},
	Year = {1986},
	Bdsk-File-1 = {YnBsaXN0MDDUAQIDBAUGCQpYJHZlcnNpb25UJHRvcFkkYXJjaGl2ZXJYJG9iamVjdHMSAAGGoNEHCFRyb290gAFfEA9OU0tleWVkQXJjaGl2ZXKoCwwXGBkdJCVVJG51bGzTDQ4PEBEUViRjbGFzc1dOUy5rZXlzWk5TLm9iamVjdHOAB6ISE4ACgAOiFRaABIAGWWFsaWFzRGF0YVxyZWxhdGl2ZVBhdGjSDRobHFdOUy5kYXRhgAVPEQGsAAAAAAGsAAIAAApCaWdQYW5kb3JhAAAAAAAAAAAAAAAAAAAAAAC8tdhoSCsAAACfNhINQ1ZTLWdydW5lLnBkZgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJ82E8gEKcsAAAAAAAAAAAABAAMAAAkgAAAAAAAAAAAAAAAAAAAAB0hpc3RvcnkAABAACAAAvLYQqAAAABEACAAAyARiCwAAAAEAGACfNhIAnzYRAJ819QAaR7IAGkGdABWopQACAEpCaWdQYW5kb3JhOlVzZXJzOmpzY2hpbXBmOlB1YmxpYzpGb3NzaWxCb29rOlJlc2VhcmNoOkhpc3Rvcnk6Q1ZTLWdydW5lLnBkZgAOABwADQBDAFYAUwAtAGcAcgB1AG4AZQAuAHAAZABmAA8AFgAKAEIAaQBnAFAAYQBuAGQAbwByAGEAEgA/VXNlcnMvanNjaGltcGYvUHVibGljL0Zvc3NpbEJvb2svUmVzZWFyY2gvSGlzdG9yeS9DVlMtZ3J1bmUucGRmAAATAAEvAP//AADSHh8gIVgkY2xhc3Nlc1okY2xhc3NuYW1loyEiI11OU011dGFibGVEYXRhVk5TRGF0YVhOU09iamVjdF8QFUhpc3RvcnkvQ1ZTLWdydW5lLnBkZtIeHyYnoicjXE5TRGljdGlvbmFyeQAIABEAGgAfACkAMgA3ADoAPwBBAFMAXABiAGkAcAB4AIMAhQCIAIoAjACPAJEAkwCdAKoArwC3ALkCaQJuAncCggKGApQCmwKkArwCwQLEAAAAAAAAAgEAAAAAAAAAKAAAAAAAAAAAAAAAAAAAAtE=}}

@article{SCCS,
	Author = {Marc J Rochkind},
	Date-Added = {2010-04-25 06:26:32 -0400},
	Date-Modified = {2010-04-25 06:29:15 -0400},
	Journal = {IEEE Transactions on Software Engineering},
	Keywords = {Source Control, change control},
	Month = {December},
	Number = {4},
	Pages = {364},
	Title = {The Source Control System},
	Volume = {SE-1},
	Year = {1975},
	Bdsk-File-1 = {YnBsaXN0MDDUAQIDBAUGCQpYJHZlcnNpb25UJHRvcFkkYXJjaGl2ZXJYJG9iamVjdHMSAAGGoNEHCFRyb290gAFfEA9OU0tleWVkQXJjaGl2ZXKoCwwXGBkdJCVVJG51bGzTDQ4PEBEUViRjbGFzc1dOUy5rZXlzWk5TLm9iamVjdHOAB6ISE4ACgAOiFRaABIAGWWFsaWFzRGF0YVxyZWxhdGl2ZVBhdGjSDRobHFdOUy5kYXRhgAVPEQHAAAAAAAHAAAIAAApCaWdQYW5kb3JhAAAAAAAAAAAAAAAAAAAAAAC8tdhoSCsAAACfNhISU0NDUy1TbGlkZXNob3cucGRmAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJ82FcgEKcwAAAAAAAAAAAABAAMAAAkgAAAAAAAAAAAAAAAAAAAAB0hpc3RvcnkAABAACAAAvLYQqAAAABEACAAAyARiDAAAAAEAGACfNhIAnzYRAJ819QAaR7IAGkGdABWopQACAE9CaWdQYW5kb3JhOlVzZXJzOmpzY2hpbXBmOlB1YmxpYzpGb3NzaWxCb29rOlJlc2VhcmNoOkhpc3Rvcnk6U0NDUy1TbGlkZXNob3cucGRmAAAOACYAEgBTAEMAQwBTAC0AUwBsAGkAZABlAHMAaABvAHcALgBwAGQAZgAPABYACgBCAGkAZwBQAGEAbgBkAG8AcgBhABIARFVzZXJzL2pzY2hpbXBmL1B1YmxpYy9Gb3NzaWxCb29rL1Jlc2VhcmNoL0hpc3RvcnkvU0NDUy1TbGlkZXNob3cucGRmABMAAS8A//8AANIeHyAhWCRjbGFzc2VzWiRjbGFzc25hbWWjISIjXU5TTXV0YWJsZURhdGFWTlNEYXRhWE5TT2JqZWN0XxAaSGlzdG9yeS9TQ0NTLVNsaWRlc2hvdy5wZGbSHh8mJ6InI1xOU0RpY3Rpb25hcnkACAARABoAHwApADIANwA6AD8AQQBTAFwAYgBpAHAAeACDAIUAiACKAIwAjwCRAJMAnQCqAK8AtwC5An0CggKLApYCmgKoAq8CuALVAtoC3QAAAAAAAAIBAAAAAAAAACgAAAAAAAAAAAAAAAAAAALq}}

\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
\BOOKMARK [1][-]{section.2.1}{2.1 Introduction}{chapter.2}% 11
\BOOKMARK [1][-]{section.2.2}{2.2 Creating a repository}{chapter.2}% 12
\BOOKMARK [2][-]{subsection.2.2.1}{2.2.1 Introduction}{section.2.2}% 13
\BOOKMARK [2][-]{subsection.2.2.2}{2.2.2 Create Repository}{section.2.2}% 14
\BOOKMARK [2][-]{subsection.2.2.3}{2.2.3 Connect Repository}{section.2.2}% 15
\BOOKMARK [2][-]{subsection.2.2.4}{2.2.4 Add and Initial Commit}{section.2.2}% 16
\BOOKMARK [2][-]{subsection.2.2.5}{2.2.5 Fossil start up summary}{section.2.2}% 17
\BOOKMARK [1][-]{section.2.3}{2.3 Set Up User interface}{chapter.2}% 18
\BOOKMARK [2][-]{subsection.2.3.1}{2.3.1 User interface summary}{section.2.3}% 19
\BOOKMARK [1][-]{section.2.4}{2.4 Update Repository}{chapter.2}% 20
\BOOKMARK [2][-]{subsection.2.4.1}{2.4.1 Update Summary}{section.2.4}% 21
\BOOKMARK [1][-]{section.2.5}{2.5 Tickets}{chapter.2}% 22
\BOOKMARK [2][-]{subsection.2.5.1}{2.5.1 Ticket Summary}{section.2.5}% 23
\BOOKMARK [1][-]{section.2.6}{2.6 Wiki Use}{chapter.2}% 24
\BOOKMARK [2][-]{subsection.2.6.1}{2.6.1 Wiki Summary}{section.2.6}% 25
\BOOKMARK [0][-]{chapter.3}{3 Multiple Users}{}% 26
\BOOKMARK [1][-]{section.3.1}{3.1 Introduction}{chapter.3}% 27
\BOOKMARK [1][-]{section.3.2}{3.2 Setup}{chapter.3}% 28
\BOOKMARK [2][-]{subsection.3.2.1}{3.2.1 Server Setup}{section.3.2}% 29
\BOOKMARK [3][-]{paragraph.3.2.1.0.1}{3.2.1.0.1 Self hosted}{subsection.3.2.1}% 30
\BOOKMARK [4][-]{paragraph.3.2.1.0.2}{3.2.1.0.2 Server hosted}{paragraph.3.2.1.0.1}% 31
\BOOKMARK [4][-]{paragraph.3.2.1.0.3}{3.2.1.0.3 CGI Script for hosted server}{paragraph.3.2.1.0.1}% 32
\BOOKMARK [2][-]{subsection.3.2.2}{3.2.2 The test \(either self hosted or server hosted\)}{section.3.2}% 33
\BOOKMARK [1][-]{section.3.3}{3.3 User Accounts}{chapter.3}% 34
\BOOKMARK [1][-]{section.3.4}{3.4 Multiple User Operation}{chapter.3}% 35
\BOOKMARK [2][-]{subsection.3.4.1}{3.4.1 Cloning}{section.3.4}% 36
\BOOKMARK [2][-]{subsection.3.4.2}{3.4.2 Keeping in sync}{section.3.4}% 37
\BOOKMARK [2][-]{subsection.3.4.3}{3.4.3 Complications}{section.3.4}% 38
\BOOKMARK [2][-]{subsection.3.4.4}{3.4.4 Fixing the Update file}{section.3.4}% 39
\BOOKMARK [2][-]{subsection.3.4.5}{3.4.5 Fixing the Merge file}{section.3.4}% 40
\BOOKMARK [0][-]{chapter.4}{4 Forks \046 Branches}{}% 41
\BOOKMARK [1][-]{section.4.1}{4.1 Introduction}{chapter.4}% 42
\BOOKMARK [1][-]{section.4.2}{4.2 Forks, Branch \046 Merge}{chapter.4}% 43
\BOOKMARK [2][-]{subsection.4.2.1}{4.2.1 Marilyn's Actions}{section.4.2}% 44
\BOOKMARK [2][-]{subsection.4.2.2}{4.2.2 Jim's Actions}{section.4.2}% 45
\BOOKMARK [2][-]{subsection.4.2.3}{4.2.3 Fixing the fork}{section.4.2}% 46
\BOOKMARK [2][-]{subsection.4.2.4}{4.2.4 Commands used}{section.4.2}% 47
\BOOKMARK [1][-]{section.4.3}{4.3 Merge without fork}{chapter.4}% 48
\BOOKMARK [2][-]{subsection.4.3.1}{4.3.1 Check in attempt}{section.4.3}% 49
\BOOKMARK [2][-]{subsection.4.3.2}{4.3.2 Update}{section.4.3}% 50
\BOOKMARK [2][-]{subsection.4.3.3}{4.3.3 Commands used}{section.4.3}% 51
\BOOKMARK [1][-]{section.4.4}{4.4 Branching}{chapter.4}% 52
\BOOKMARK [2][-]{subsection.4.4.1}{4.4.1 Introduction}{section.4.4}% 53
\BOOKMARK [2][-]{subsection.4.4.2}{4.4.2 Branch the repository}{section.4.4}% 54
\BOOKMARK [2][-]{subsection.4.4.3}{4.4.3 Color Setup}{section.4.4}% 55
\BOOKMARK [2][-]{subsection.4.4.4}{4.4.4 Check out the branches}{section.4.4}% 56
\BOOKMARK [2][-]{subsection.4.4.5}{4.4.5 Correcting errors \(in both\)}{section.4.4}% 57
\BOOKMARK [2][-]{subsection.4.4.6}{4.4.6 Commands used}{section.4.4}% 58
\BOOKMARK [0][-]{chapter.5}{5 Fossil Commands}{}% 59
\BOOKMARK [1][-]{section.5.1}{5.1 Introduction}{chapter.5}% 60
\BOOKMARK [1][-]{section.5.2}{5.2 Basic Commands}{chapter.5}% 61
\BOOKMARK [2][-]{subsection.5.2.1}{5.2.1 help}{section.5.2}% 62
\BOOKMARK [2][-]{subsection.5.2.2}{5.2.2 add}{section.5.2}% 63
\BOOKMARK [2][-]{subsection.5.2.3}{5.2.3 rm or del}{section.5.2}% 64
\BOOKMARK [2][-]{subsection.5.2.4}{5.2.4 rename or mv}{section.5.2}% 65
\BOOKMARK [2][-]{subsection.5.2.5}{5.2.5 status}{section.5.2}% 66
\BOOKMARK [2][-]{subsection.5.2.6}{5.2.6 changes}{section.5.2}% 67
\BOOKMARK [2][-]{subsection.5.2.7}{5.2.7 extra}{section.5.2}% 68
\BOOKMARK [2][-]{subsection.5.2.8}{5.2.8 revert}{section.5.2}% 69
\BOOKMARK [2][-]{subsection.5.2.9}{5.2.9 update}{section.5.2}% 70
\BOOKMARK [2][-]{subsection.5.2.10}{5.2.10 checkout or co}{section.5.2}% 71
\BOOKMARK [2][-]{subsection.5.2.11}{5.2.11 undo}{section.5.2}% 72
\BOOKMARK [2][-]{subsection.5.2.12}{5.2.12 diff}{section.5.2}% 73
\BOOKMARK [2][-]{subsection.5.2.13}{5.2.13 gdiff}{section.5.2}% 74
\BOOKMARK [2][-]{subsection.5.2.14}{5.2.14 ui}{section.5.2}% 75
\BOOKMARK [2][-]{subsection.5.2.15}{5.2.15 server}{section.5.2}% 76
\BOOKMARK [2][-]{subsection.5.2.16}{5.2.16 commit or ci}{section.5.2}% 77
\BOOKMARK [1][-]{section.5.3}{5.3 Maintenance commands}{chapter.5}% 78
\BOOKMARK [2][-]{subsection.5.3.1}{5.3.1 new}{section.5.3}% 79
\BOOKMARK [2][-]{subsection.5.3.2}{5.3.2 clone}{section.5.3}% 80
\BOOKMARK [2][-]{subsection.5.3.3}{5.3.3 open}{section.5.3}% 81
\BOOKMARK [2][-]{subsection.5.3.4}{5.3.4 close}{section.5.3}% 82
\BOOKMARK [2][-]{subsection.5.3.5}{5.3.5 version}{section.5.3}% 83
\BOOKMARK [2][-]{subsection.5.3.6}{5.3.6 rebuild}{section.5.3}% 84
\BOOKMARK [2][-]{subsection.5.3.7}{5.3.7 all}{section.5.3}% 85
\BOOKMARK [2][-]{subsection.5.3.8}{5.3.8 push}{section.5.3}% 86
\BOOKMARK [2][-]{subsection.5.3.9}{5.3.9 pull}{section.5.3}% 87
\BOOKMARK [2][-]{subsection.5.3.10}{5.3.10 sync}{section.5.3}% 88
\BOOKMARK [2][-]{subsection.5.3.11}{5.3.11 clean}{section.5.3}% 89
\BOOKMARK [2][-]{subsection.5.3.12}{5.3.12 branch}{section.5.3}% 90
\BOOKMARK [2][-]{subsection.5.3.13}{5.3.13 merge}{section.5.3}% 91
\BOOKMARK [2][-]{subsection.5.3.14}{5.3.14 tag}{section.5.3}% 92
\BOOKMARK [2][-]{subsection.5.3.15}{5.3.15 settings}{section.5.3}% 93
\BOOKMARK [1][-]{section.5.4}{5.4 Miscellaneous}{chapter.5}% 94
\BOOKMARK [2][-]{subsection.5.4.1}{5.4.1 zip}{section.5.4}% 95
\BOOKMARK [2][-]{subsection.5.4.2}{5.4.2 user}{section.5.4}% 96
\BOOKMARK [2][-]{subsection.5.4.3}{5.4.3 finfo}{section.5.4}% 97
\BOOKMARK [2][-]{subsection.5.4.4}{5.4.4 timeline}{section.5.4}% 98
\BOOKMARK [2][-]{subsection.5.4.5}{5.4.5 wiki}{section.5.4}% 99
\BOOKMARK [1][-]{section.5.5}{5.5 Advanced}{chapter.5}% 100
\BOOKMARK [2][-]{subsection.5.5.1}{5.5.1 scrub}{section.5.5}% 101
\BOOKMARK [2][-]{subsection.5.5.2}{5.5.2 search}{section.5.5}% 102
\BOOKMARK [2][-]{subsection.5.5.3}{5.5.3 sha1sum}{section.5.5}% 103
\BOOKMARK [2][-]{subsection.5.5.4}{5.5.4 rstats}{section.5.5}% 104
\BOOKMARK [2][-]{subsection.5.5.5}{5.5.5 configuration}{section.5.5}% 105
\BOOKMARK [2][-]{subsection.5.5.6}{5.5.6 descendants}{section.5.5}% 106
\BOOKMARK [0][-]{chapter.6}{6 Fossil Customization - the TH Scripting language}{}% 107
\BOOKMARK [1][-]{section.6.1}{6.1 Introduction to TH}{chapter.6}% 108
\BOOKMARK [2][-]{subsection.6.1.1}{6.1.1 TH is a Tcl-like language}{section.6.1}% 109
\BOOKMARK [1][-]{section.6.2}{6.2 The \215Hello, world\216 program}{chapter.6}% 110
\BOOKMARK [1][-]{section.6.3}{6.3 TH structure and syntax}{chapter.6}% 111
\BOOKMARK [2][-]{subsection.6.3.1}{6.3.1 Datatypes}{section.6.3}% 112
\BOOKMARK [2][-]{subsection.6.3.2}{6.3.2 Lists}{section.6.3}% 113
\BOOKMARK [2][-]{subsection.6.3.3}{6.3.3 Commands}{section.6.3}% 114
\BOOKMARK [2][-]{subsection.6.3.4}{6.3.4 Grouping \046 substitution}{section.6.3}% 115
\BOOKMARK [3][-]{subsubsection.6.3.4.1}{6.3.4.1 Argument grouping}{subsection.6.3.4}% 116
\BOOKMARK [3][-]{subsubsection.6.3.4.2}{6.3.4.2 Value substitutions}{subsection.6.3.4}% 117
\BOOKMARK [3][-]{subsubsection.6.3.4.3}{6.3.4.3 Backslash escape substitution.}{subsection.6.3.4}% 118
\BOOKMARK [3][-]{subsubsection.6.3.4.4}{6.3.4.4 Variable substitution}{subsection.6.3.4}% 119
\BOOKMARK [3][-]{subsubsection.6.3.4.5}{6.3.4.5 Command Substitution}{subsection.6.3.4}% 120
\BOOKMARK [3][-]{subsubsection.6.3.4.6}{6.3.4.6 Argument grouping revisited}{subsection.6.3.4}% 121
\BOOKMARK [2][-]{subsection.6.3.5}{6.3.5 Summary}{section.6.3}% 122
\BOOKMARK [3][-]{subsubsection.6.3.5.1}{6.3.5.1 Caveats}{subsection.6.3.5}% 123
\BOOKMARK [1][-]{section.6.4}{6.4 TH expressions}{chapter.6}% 124
\BOOKMARK [1][-]{section.6.5}{6.5 TH variables}{chapter.6}% 125
\BOOKMARK [2][-]{subsection.6.5.1}{6.5.1 Working with variables}{section.6.5}% 126
\BOOKMARK [3][-]{subsubsection.6.5.1.1}{6.5.1.1 Scalar variables and array variables}{subsection.6.5.1}% 127
\BOOKMARK [3][-]{subsubsection.6.5.1.2}{6.5.1.2 Variable scope}{subsection.6.5.1}% 128
\BOOKMARK [1][-]{section.6.6}{6.6 TH commands, scripts and program flow}{chapter.6}% 129
\BOOKMARK [2][-]{subsection.6.6.1}{6.6.1 Commands revisited}{section.6.6}% 130
\BOOKMARK [2][-]{subsection.6.6.2}{6.6.2 Scripts}{section.6.6}% 131
\BOOKMARK [2][-]{subsection.6.6.3}{6.6.3 Command result codes}{section.6.6}% 132
\BOOKMARK [2][-]{subsection.6.6.4}{6.6.4 Flow control commands}{section.6.6}% 133
\BOOKMARK [2][-]{subsection.6.6.5}{6.6.5 Creating user defined commands}{section.6.6}% 134
\BOOKMARK [2][-]{subsection.6.6.6}{6.6.6 Execution of user defined commands}{section.6.6}% 135
\BOOKMARK [2][-]{subsection.6.6.7}{6.6.7 Special commands}{section.6.6}% 136
\BOOKMARK [1][-]{section.6.7}{6.7 working with strings}{chapter.6}% 137
\BOOKMARK [1][-]{section.6.8}{6.8 working with lists}{chapter.6}% 138
\BOOKMARK [0][-]{chapter.7}{7 What's next ?}{}% 139
\BOOKMARK [0][-]{appendix.A}{A Document Revision History}{}% 140

\documentclass[11pt,letterpaper,english]{scrbook}
\usepackage{mathptmx}
\usepackage{helvet}
\usepackage{courier}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{fancyhdr}
\pagestyle{fancy}
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{4}
\setlength{\parskip}{\medskipamount}
\setlength{\parindent}{0pt}
\usepackage{array}
\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=2in,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}
\fancyhead[R]{\includegraphics[scale=0.3]{Layout/fossil.png}}

% Setup footer:
%------------------------------------------------------------------------------------------
\renewcommand{\footrulewidth}{0.4pt}

\fancyfoot[L]{\emph{Updated for fossil version 1.25}}
%\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}

\mainmatter
\include{Chapters/introduction}
\include{Chapters/single_user}
\include{Chapters/multiple_user}
\include{Chapters/forks_branches}
\include{Chapters/commands}
\include{Chapters/th1_scripting}
\include{Chapters/whats_next}

\pagebreak{}

\printindex{}
\listoffigures

\bibliographystyle{plain}
\bibliography{Research/fossilbib}

\appendix

\include{Appendices/revision_history}


\end{document}