FossilBook

\section{Fossil Commands}


\subsection{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.


\subsection{Basic Commands}


\subsubsection{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 detail}


\end{figure}



\subsubsection{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}

................................................................................
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.


\subsubsection{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}

................................................................................
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.


\subsubsection{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}

................................................................................
\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.


\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................
\caption{changes details}


\end{figure}



\subsubsection{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}

................................................................................
{[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~extra}

Images/Commands/help1.epsf

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

\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................
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.


\subsubsection{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}

................................................................................
\caption{checkout or co details}


\end{figure}



\subsubsection{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}

................................................................................

\end{figure}


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


\subsubsection{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}
................................................................................
\caption{diff details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{gdiff details}


\end{figure}



\subsubsection{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 various~repositories.}{\scriptsize \par}
\end{lyxcode}
\caption{ui details}
\end{figure}



\subsubsection{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}

................................................................................
\caption{server detail\label{fig:server-detail}}


\end{figure}



\subsubsection{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}

................................................................................

\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.


\subsection{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. 


\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................
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)


\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................

\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.


\subsubsection{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}

................................................................................
\caption{rebuild details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{all details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{push details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{pull details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{sync details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{clean details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{branch details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{merge details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{tag details}


\end{figure}



\subsubsection{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}

................................................................................
\caption{settings details}


\end{figure}



\subsection{Miscellaneous }

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


\subsubsection{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}

................................................................................
\caption{zip detail}


\end{figure}



\subsubsection{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}

................................................................................
\caption{user detail}


\end{figure}



\subsubsection{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{}~~~~~~~~~~~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}

\subsubsection{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}

................................................................................
\caption{timeline detail}


\end{figure}



\subsubsection{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}

................................................................................
\caption{wiki detail}


\end{figure}



\subsection{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.


\subsubsection{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}

................................................................................
\caption{scrub detail}


\end{figure}



\subsubsection{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}

................................................................................
\caption{search detail}


\end{figure}



\subsubsection{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}

................................................................................
\caption{sha1sum detail}


\end{figure}



\subsubsection{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}

................................................................................
Number~Of~Wiki~Pages:~2

~~~Number~Of~Tickets:~6

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

\subsubsection{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}

................................................................................
\caption{configuration detail}


\end{figure}



\subsubsection{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}

\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 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}

................................................................................
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}

................................................................................
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}

................................................................................
\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}

................................................................................

\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}

................................................................................
\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}

................................................................................
{[}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}

................................................................................

\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}

................................................................................
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}

................................................................................
\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}

................................................................................

\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}
................................................................................
\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}

................................................................................
\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 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}

................................................................................
\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}

................................................................................

\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}

................................................................................

\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}

................................................................................
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}

................................................................................

\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}

................................................................................

\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}

................................................................................

\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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{}~~~~~~~~~~~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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
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}

................................................................................
\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}

\chapter{Foreword}

\chapter{Foreword}

\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 javalinBCD@gmail.com - found bugs
\item arnel\_legaspi@msn.com - found bugs
\end{itemize}
\newpage{}

\section{Forks \& Branches}


\subsection{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}.


\subsection{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.


\subsubsection{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}



\subsubsection{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}

................................................................................

\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{]}.


\subsubsection{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}

................................................................................
\caption{Marilyn's Update}


\end{figure}



\subsubsection{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}

\subsection{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.


\subsubsection{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}

................................................................................
\caption{Jim's check in attempt}


\end{figure}



\subsubsection{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}

................................................................................
\caption{Merged repository}


\end{figure}



\subsubsection{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}

\subsection{Branching}


\subsubsection{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.


\subsubsection{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}

................................................................................
\includegraphics[scale=0.6]{Images/Advanced/Branching/branch}

\caption{Branch Timeline}
\end{figure}



\subsubsection{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.


\subsubsection{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}

................................................................................
\caption{VER\_2.0 checkout}
\end{figure}


Notice on both of these the tags show which branch we are attached to.


\subsubsection{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}

................................................................................
\caption{Correcting both branches}


\end{figure}



\subsubsection{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{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}

................................................................................

\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

................................................................................
\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}

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


\subsection{What is it}

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. You then put all these files in a directory and at times subdivide even that with subdirectories. At any particular time this set of files in their present edited state make up a working version of the project. If other people are using the project you give them this and as is usually the case, they find problems and you fix them. This results in another version of the project slightly changed which goes through the cycle again. (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 or 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 bugs were fixed and enhancements made.

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 has say Version 1 which 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 contains 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}). It's home page is here \url{http://www.fossil-scm.org/}.


\subsection{Why do it ?}

Why do you want to use a source control system? To use one restricts your freedom, 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? The biggest answer is freedom (huh ?). By following the procedures of a source control system you gain the freedom to modify your code any way you want. How does that follow ? 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. You have a very helpless feeling of how do you 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. Then, 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. 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.


\subsubsection{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. Also there is a source Tarball from which you can compile from source. This web site is self-hosted by Fossil itself (see Section\vref{sec:Multiple-Users}). 


\subsection{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.


\subsubsection{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. 


\subsubsection{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.


\subsubsection{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.


\subsubsection{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{Source Control \& Why you need it}


\section{What is it}

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. You then put all these files in a directory and at times subdivide even that with subdirectories. At any particular time this set of files in their present edited state make up a working version of the project. If other people are using the project you give them this and as is usually the case, they find problems and you fix them. This results in another version of the project slightly changed which goes through the cycle again. (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 or 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 bugs were fixed and enhancements made.

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 has say Version 1 which 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 contains 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}). It's home page is here \url{http://www.fossil-scm.org/}.


\section{Why do it ?}

Why do you want to use a source control system? To use one restricts your freedom, 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? The biggest answer is freedom (huh ?). By following the procedures of a source control system you gain the freedom to modify your code any way you want. How does that follow ? 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. You have a very helpless feeling of how do you 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. Then, 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. 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. Also there is a source Tarball from which you can compile from source. This web site is self-hosted by Fossil itself (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}

\section{\label{sec:Multiple-Users}Multiple Users}


\subsection{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.


\subsection{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.


\subsubsection{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:
................................................................................
\caption{Copying script into place}


\end{figure}



\subsubsection{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.6]{Images/Multiple_user/test_access}

\caption{\label{fig:Web-access-to}Web access to Fossil CGI hosted site}
\end{figure}



\subsection{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.6]{Images/Multiple_user/mul_new_user}
................................................................................


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.


\subsection{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.


\subsubsection{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{figure}


As you see the files were committed locally and then the local repository was automatically synchronized with the repository on the server.


\subsubsection{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}
................................................................................

\end{figure}


Now I know I have the current state of the world and I can proceed to add in new sections.


\subsubsection{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}

................................................................................

\end{figure}


By using the pipe and grep I can eliminate all those extra UNCHANGED lines.


\subsubsection{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.6]{Images/Multiple_user/mul_timeline}

\caption{Current Timeline}
................................................................................

\end{figure}


and it's done.


\subsubsection{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}

\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:
................................................................................
\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.6]{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.6]{Images/Multiple_user/mul_new_user}
................................................................................


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{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}
................................................................................

\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}

................................................................................

\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.6]{Images/Multiple_user/mul_timeline}

\caption{Current Timeline}
................................................................................

\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}

\subsection{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.


\subsection{Creating a repository }


\subsubsection{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}
................................................................................
\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.


\subsubsection{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}

................................................................................

\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). 


\subsubsection{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}

................................................................................


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.


\subsubsection{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}

................................................................................

\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.


\subsubsection{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 commit -m ``Initial Commit''} Will put all the currently added files into the repository.
\end{itemize}

\subsection{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}
................................................................................


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.


\subsubsection{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}

\subsection{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}

................................................................................
\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.


\subsubsection{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}

\subsection{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.6]{Images/Single_user/ticket_initial}
................................................................................

\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.


\subsubsection{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}

\subsection{\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.6]{Images/Single_user/wiki_blankhome}
................................................................................
{[}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.


\subsubsection{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{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}
................................................................................
\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}

................................................................................

\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}

................................................................................


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}

................................................................................

\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 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}
................................................................................


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}

................................................................................
\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.6]{Images/Single_user/ticket_initial}
................................................................................

\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.6]{Images/Single_user/wiki_blankhome}
................................................................................
{[}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{TH1 Scripting}

\section{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). 

\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). 

\documentclass[11pt,letterpaper,english]{article}
\usepackage{mathptmx}
\usepackage{helvet}
\usepackage{courier}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{fancyhdr}
\pagestyle{fancy}
................................................................................

Fax: 724.539.1276 

Web: http://www.fossil-scm.org/schimpf-book/index

Email: jim.schimpf@gmail.com

\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 javalinBCD@gmail.com - found bugs
\item arnel\_legaspi@msn.com - found bugs
\end{itemize}
\newpage{}




\section*{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 
\end{tabular}
\par\end{center}

\newpage{}\tableofcontents{}

\listoffigures


\newpage{}


\section*{Foreward}

\include{Chapters/foreword}
\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{}

\bibliographystyle{plain}
\bibliography{Research/fossilbib}





\end{document}

\documentclass[11pt,letterpaper,english]{scrbook}
\usepackage{mathptmx}
\usepackage{helvet}
\usepackage{courier}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{fancyhdr}
\pagestyle{fancy}
................................................................................

Fax: 724.539.1276 

Web: http://www.fossil-scm.org/schimpf-book/index

Email: jim.schimpf@gmail.com













\newpage{}




























































\newpage{}\tableofcontents{}

\listoffigures


\newpage{}


\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{}

\bibliographystyle{plain}
\bibliography{Research/fossilbib}

\appendix
\include{Appendices/revision_history}


\end{document}