\chapter*{Disclaimer}

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

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

Additional Contributors
\begin{itemize}
\item Marilyn Noz - Editor
\item Wolfgang Stumvoll - Fossil Merge use and Windows use
\item Paul Ruizendaal - TH 1 Scrpting Language manual
\item javalinBCD@gmail.com - found bugs
\item arnel\_legaspi@msn.com - found bugs
\end{itemize}
\newpage{}

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


\section{Introduction}

In the previous chapter I went through using Fossil with just one user (me). In this chapter we will get into using it with multiple users. Thanks to Fossil's distributed design once the set up is done using it is not much different than the single user case with Fossil managing automatically the multiple user details.


\section{Setup}

In the previous chapter the Fossil repository was a file on our system and we did commits to it and pulled copies of the source from it. Fossil is a distributed source control system; what this means is that there is a master repository in a place that all users can access. Each user has their own ``cloned'' copy of the repository and Fossil will automatically synchronize the users repository with the master. From a each user's perspective you have your local repository and work with it using the same commands shown in Chapter \ref{sec:Single-User-Fossil}. It's just that now Fossil will keep your repository in sync with the master.


\subsection{Server Setup\label{sub:Server-Setup}}

I have the FossilBook.fossil repository and now have to put it in place so multiple users can access it. There are two ways, the first is using fossil's built in webserver to host the file and the second is using the operating systems supported web server (if present) and a cgi type access.


\paragraph{Self hosted}

This is quite simply the easiest way to do it. The downside is that you are responsible for keeping the machine available and the webserver up. That is, don't turn the machine off when you quit for the day or some other user is going to be upset. All I have to do is this:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize {[}Pandora-2:/Users/jschimpf/Public{]}~jim\%~cd~FOSSIL/}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}\textbf{\scriptsize fossil~ui~-port~8081~FossilBook.fossil~\&}{\scriptsize{}~}{\scriptsize \par}

{\scriptsize {[}1{]}~310}{\scriptsize \par}

{\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}{\scriptsize \par}
\end{lyxcode}
\caption{Self-hosted Fossil repository}


\end{figure}


This is on UNIX system, the ``\&'' at then end of the second line runs the fossil webserver in the background. If I know this machine has an IP address of 192.168.1.200 then from any other machine in the network I can say:

\textbf{http://192.168.1.200:8081} to the browser and I can access the Fossil web server. 

As you can see this is simple and works on any system that runs Fossil. As long as you carefully make sure it's always running and available for others this can be a very easy way to make the master repository available. 

\paragraph{CGI Script for hosted server}

If we assume an Apache server and, in my case, the cgi directory path is /Library/Webserver/CGI-Executables, then we have to write a script of the form:

\begin{figure}[H]
\begin{lyxcode}
\#!<Fossil~executable~location>

repository:~<Fossil~repository~location>
\end{lyxcode}
\caption{Fossil CGI script}


\end{figure}


and put it into the cgi script directory. I have put my Fossil executable into /usr/local/bin and I am putting my Fossil shared repository into /Users/Shared/FOSSIL. My script then becomes:

\begin{figure}[H]
\begin{lyxcode}
\#!/usr/local/bin/fossil

\#~Put~the~book~repository~on~the~web

repository:~/Users/Shared/FOSSIL/Fossilbook.fossil
\end{lyxcode}
\caption{My Fossil CGI script}


\end{figure}


After making the script I then copy it to the CGI directory and allow anyone to execute it.
\begin{lyxcode}

\end{lyxcode}
\begin{figure}[H]
\begin{lyxcode}
\textbf{\scriptsize sudo~cp~Book.cgi~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par}



\textbf{\scriptsize sudo~chmod~a+x~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par}
\end{lyxcode}
\caption{Copying script into place}


\end{figure}



\subsection{The test (either self hosted or server hosted)}

If all is in place then I should be able to access the webserver and get to this:

\begin{figure}[H]
\includegraphics[scale=0.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}

\caption{New Editor user\label{fig:New-Editor-user}}


\end{figure}


Since she is going to be an editor, this will be similar to a developer if we were doing code, so I picked the Developer privilege level. This way she can get the repository, check-in, check-out, and write and update tickets. I also added the attachments since she might need that to put on an image or other comment on actions she is doing. I also gave her a password so her access can be secured.

I could add other users at this point but don't need any others for this project, but you can see how easily this can be done. When you assign the user privileges just read carefully and don't give them any more than you think they need. If they have problems, you can easily modify their account in the future.


\section{Multiple User Operation}

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

We can use the tools built into Fossil. In this case noticing that commit will cause a fork Jim will use the -force option to cause the fork and will handle the merge later.

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-m~\textquotedbl{}adding~some~changes~of~jim\textquotedbl{}}{\scriptsize \par}

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

{\scriptsize \A0}{\scriptsize \par}

{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-f~-m~\textquotedbl{}adding~some~other~changes~of~jim\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~df9f2ff6b14ef65a9dd2162f8bd20c78e1628165}{\scriptsize \par}
\end{lyxcode}
\caption{Forcing a commit under Windows}
\end{figure}


Now the timeline looks like:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Multiple_user/Windows/forked_timeline}

\caption{Windows Forked timeline}
\end{figure}


To remove this fork (i.e. get the changes Marilyn did into the trunk) we use the Fossil merge command. We can use the merge because fossilbook.lyx is a text file and the merge markers are designed to work with text files. If it was a binary file we might have to use an external file or copy and paste between the two file versions using the handler program for the file.

Looking at the file (fossilbook.lyx) in a text editor (not \LyX{}) we find:

\begin{figure}[H]
\begin{lyxcode}
{\scriptsize >\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>~BEGIN~MERGE~CONFLICT}{\scriptsize \par}

{\scriptsize \A0Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~it}{\scriptsize \par}

{\scriptsize \A0with~multiple~users~is~not~much~different~than~the~single~user~case.}{\scriptsize \par}

{\scriptsize \A0Fossil~will~automatically~manage~the~most~multiple~user~details.}{\scriptsize \par}

{\scriptsize ============================}{\scriptsize \par}

{\scriptsize \A0}{\scriptsize \par}

{\scriptsize \A0Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~is}{\scriptsize \par}

{\scriptsize \A0not~much~different~than~the~single~user~case~with~Fossil~managing~automatically}{\scriptsize \par}

{\scriptsize \A0the~multiple~user~details.}{\scriptsize \par}

{\scriptsize <\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<~END~MERGE~CONFLICT}{\scriptsize \par}



\textbf{<Here~edit~in~the~changes>}



{\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-m~\textquotedbl{}merging~marilyn's~fork~back\textquotedbl{}}{\scriptsize \par}

{\scriptsize New\_Version:~acdd676d3ab157769496f6845ccc7652985c1d03}{\scriptsize \par}
\end{lyxcode}
\caption{Text differences}
\end{figure}


After the commit the timeline shows how the merge brought the fork back into the main trunk. Marilyn will then have to update to this new trunk. (See Section \vref{sub:Updating-by-others})

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Multiple_user/Windows/merged_timeline}

\caption{Merged timeline}
\end{figure}

\begin{description}
\item [{NOTE:}] Newer versions of Fossil automatically find an open port and will give a message on the command line telling you what port number is used. You can still use the -port option if you want to control the port \#.
\end{description}
This shows how it's started, as you can see I have picked port 8081 since I am locked out of port 8080. When I do this my browser starts and I am presented with the following home page.

\begin{figure}[H]
\noindent \begin{raggedright}
\includegraphics[scale=0.4]{Images/Single_user/initial_page}
\par\end{raggedright}

\caption{\label{fig:Initial-Webserver-page}Initial webserver page}


\end{figure}


Following the advice on the page I go to \textbf{setup/config}. I am going to do the minimum setup that you should do on all projects. As you get familiar with Fossil you will probably have many more things that you will customize for your taste but what follows are the only things you HAVE to do.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/config_initial}

\caption{\label{fig:Initial-Configuration}Initial Configuration}


\end{figure}


I have entered in a project name and put in a description, the project name will be the name of the initial Wiki page (see \vref{sub:Wiki-Use}) and the description is useful for others to see what you are doing here. Then I go to the bottom of the page and pick the \textbf{Apply Changes }button.

Next I pick the Admin tab (you can see it in the header bar) and the pick Users from that page. I am presented with the users and will use this to set the password of the project.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/user_config}

\caption{\label{fig:User-Configuration}User Configuration}


\end{figure}


As you can see Fossil automatically configures a number of users beyond just the creator. The anonymous user you have already seen if you went to the Fossil web site to download the code. This user can view and get code but cannot commit code. On the right side of the page are the many options you can give to a user, it's worth reading it all when you set up your repository. The important one is me (jim) which has ``s'' or Super User Capabilities. This means I can do anything with the repository.

I will now edit the user Jim to make sure it has the settings I want. In this case you MUST set the password. Remember way back where Fossil set it during the create (Figure\vref{fig:Create-Repository}), it's a very good idea to change this to something you can remember rather than the original random one.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/jim_setup}

\caption{Super User Setup}


\end{figure}

\end{figure}


After doing this commit I can bring up the Fossil ui (see Figure \vref{fig:Starting-Webserver}) and view the project Timeline by picking that tab on the Fossil header. We get this:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/timeline}

\caption{Timeline}


\end{figure}


You can see all my check-ins thus far and you can see after the check-in from Figure \vref{fig:Update-for-new} I did another check-in because I missed some changes in the outline. The check-ins are labeled with the first 10 digits of their hash value and these are active links which you can click to view in detail what was changed in that version. 

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/timeline_detail}

\caption{Timeline Detail\label{fig:Timeline-Detail}}
\end{figure}


I clicked on the very last check-in (the \textbf{LEAF) }and the display is shown above. There are many things you can do at this point. From the list of changed files you can pick the diff link and it will show in text form the changes made in that particular file. The ``Other Links'' section has a very useful ZIP Archive. Clicking this will download a ZIP of this version to your browser. You will find this useful if you want to get a particular version, in fact this is normally how you get a new version of Fossil from the \url{http://www.fossil-scm.org/}. The edit link will be used later to modify a leaf.

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

\caption{Initial Ticket Window}


\end{figure}


Picking ``New Ticket'' I get a form that I fill out like so:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/ticket_form}

\caption{Ticket Form}


\end{figure}


Pretty simple actually. You can put as much or as little detail in here as you wish, but remember this stuff might be really vital 6 weeks or 6 months from now so think of what you would want to know then. When I press Submit I get this showing what I entered.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/ticket_submit}

\caption{Viewing a Ticket}


\end{figure}


Finally picking Tickets then ``All Tickets'' I can see my new ticket in the list marked as Open and in a distinctive color. 

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/ticket_list}

\caption{\label{fig:viewticket}Ticket List with open ticket}


\end{figure}


I try, in handling tickets, to have links from ticket to the commit that addressed the problem and a link from the commit back to the offending ticket. This way looking at the ticket I can get to the changes made and from the timeline I can get the the ticket and its resolution. To do this I will make sure and put the 10 digit hash label from the ticket into the check-in comment and put a link in the resolved ticket to the check-in.

Since I have now written the chapter and put in all these images of what to do I can now add in all the new images to the repository and check this in as another completed operation. And I do that like this:

\begin{figure}[H]
\begin{lyxcode}

First I added in all the new image files. I am lazy and just told it to add in all the files in the Single\_user directory. I have previously added some of those like \textbf{config\_initial.epsf} but Fossil is smart and knows this and won't add that one twice. Even though it shows it ADDED, it really didn't.

The commit line is very important, as you can see I put 10 digit hash code for the ticket in brackets in the comment. As we will see in the Wiki section this is a link to the Ticket, so when viewing the comment in the Timeline or elsewhere you can click the bracketed item and you would go to the ticket.

Now that I have the items checked in I have to close the ticket. I do that by clicking on its link in the ticket list, that will go the the View Ticket window as shown in Figure \vref{fig:viewticket}. From there I pick edit and fill it in as shown:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/ticket_done}

\caption{Ticket Finish}


\end{figure}

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

\caption{Blank Home Page}


\end{figure}


Not very helpful so the in rest of this chapter I will use the Wiki functions of Fossil to make this more useful. If I pick the Wiki item from the menu bar I get:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/wiki_page}

\caption{\label{fig:Wiki-controls}Wiki controls}


\end{figure}


These are the controls that let you control and modify the wiki. Most important for now is the Formatting rules link. This link takes you to a page that describes what you can do to format a wiki page. If you just type text on a page it will appear but be formatted by your browser. You can type HTML commands to control this formating. It's worth your time to carefully read this page and note what you can and cannot do. The page just lists the valid HTML commands, and if you don't know what they mean I would suggest you find a page like this \url{http://www.webmonkey.com/2010/02/html_cheatsheet/} and keep it handy. 

Besides the HTML markup the most powerful command for the Wiki is {[}page{]} where it links to a new page. This is how you add pages and how you build your web site of documentation for the repository.

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/wiki_formating}\caption{Wiki Formating}


\end{figure}


I now begin work. What I want to do is change the home page to be non-empty and also put a link on the home page to the PDF of this book. In Figure \vref{fig:Wiki-controls} I click on the first item, the FossilBook home page. This takes me to the home page again but now I have an Edit option. We also have a History option so I could look at older versions of the page. 

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/wiki_homeedit}

\caption{Home page with edit}


\end{figure}


This shows my initial edit and a preview:

\begin{figure}[H]
\includegraphics[scale=0.6]{Images/Single_user/wiki_home}

\caption{Initial Home page}


\end{figure}