#LyX 1.6.0 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass article
\begin_preamble
% Include the proper LaTeX packages:
%----------------------------------------------------------------------------------------------------
\usepackage{graphicx}
\usepackage{titling}
\usepackage{ifthen}
\usepackage[absolute]{textpos}
\usepackage[colorlinks=true,
pagecolor=black,
menucolor=black,
linkcolor=black,
citecolor=blue,
pagebordercolor=1 1 1,
urlcolor=red,
plainpages=false,
pdfpagelabels=true,
bookmarksnumbered=true]{hyperref}
\usepackage{lastpage}
\newcommand{\reportTopic}{<reportTopic>}
\newcommand{\revisionNumber}{<rev. no.>}
\newcommand{\documentNumber}{<doc. no.>}
% Setup the right-hand header to display the current doc section:
%----------------------------------------------------------------------------------------------------
\renewcommand{\sectionmark}[1]{\markright{#1}}
\renewcommand{\subsectionmark}[1]{\markright{#1}}
% Setup for roman numeral page numbers until TOC:
%----------------------------------------------------------------------------------------------------
\newboolean{romanpn}
\pagenumbering{roman}
\setboolean{romanpn}{true}
\let\myTOC\tableofcontents
\renewcommand\tableofcontents{%
\myTOC
\clearpage
\pagenumbering{arabic}
\setboolean{romanpn}{false}
}
% Modify titlepage format:
%----------------------------------------------------------------------------------------------------
\setlength{\TPHorizModule}{1in}
\setlength{\TPVertModule}{\TPHorizModule}
\textblockorigin{3.25in}{1in}
\pretitle
{
\begin{flushright}\LARGE\sffamily
\thispagestyle{empty}
\begin{textblock}{4}(0,0)
\includegraphics[width=4in,keepaspectratio=true]{Layout/fossil.png}
\end{textblock}
\vspace{2in}
}
\posttitle{\par\end{flushright}}
\preauthor{\begin{flushright} \large \sffamily \lineskip 0.5em
\begin{tabular}[t]{c}}
\postauthor{\end{tabular} \par\end{flushright}}
\predate{\begin{flushright}\large \sffamily Document Number: \documentNumber \\ Revision Number: \revisionNumber \\}
\postdate{
\vspace{2in}
\\Pandora Products.
\\215 Uschak Road
\\Derry, PA 15627
\par\end{flushright}}
% Setup "fancy" page layout:
%----------------------------------------------------------------------------------------------------
\fancyhf{}
\setlength{\topmargin}{-1in}
\setlength{\headheight}{1in}
\setlength{\headsep}{0.5in}
\setlength{\oddsidemargin}{0.25in}
\setlength{\evensidemargin}{\oddsidemargin}
\setlength{\textwidth}{6in}
\setlength{\headwidth}{\textwidth}
\setlength{\textheight}{8.375in}
\setlength{\footskip}{0.5in}
% Setup header:
%------------------------------------------------------------------------------------------
\fancyhead[L]{\sffamily \bfseries \large Fossil Version Control\\\mdseries \reportTopic}
%\fancyhead[R]{\sffamily \bfseries \large Pandora Products\\ \mdseries \nouppercase{\rightmark}}
% Setup footer:
%------------------------------------------------------------------------------------------
\renewcommand{\footrulewidth}{0.4pt}
\fancyfoot[L]{\sffamily \bfseries \documentNumber \\ \mdseries Revision: \revisionNumber}
\fancyfoot[C]{\sffamily \bfseries\thedate \\ }
\fancyfoot[R]{\ifthenelse{\boolean{romanpn}}{\sffamily \thepage}{\sffamily \bfseries Page \thepage\ of \pageref{LastPage}}}
\end_preamble
\use_default_options false
\language english
\inputencoding auto
\font_roman times
\font_sans helvet
\font_typewriter courier
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\paperfontsize 11
\spacing single
\use_hyperref false
\papersize letterpaper
\use_geometry false
\use_amsmath 1
\use_esint 0
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 4
\tocdepth 4
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle fancy
\tracking_changes false
\output_changes false
\author ""
\author ""
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
renewcommand{
\backslash
documentNumber}{PAN-20100424}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
renewcommand{
\backslash
reportTopic}{A Users Guide}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
renewcommand{
\backslash
revisionNumber}{1.5}
\end_layout
\end_inset
\end_layout
\begin_layout Title
Fossil Version Control
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
\backslash
\backslash
reportTopic
\end_layout
\end_inset
\end_layout
\begin_layout Author
Jim Schimpf
\end_layout
\begin_layout Date
7 June 2010
\end_layout
\begin_layout Standard
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
thispagestyle{empty}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage newpage
\end_inset
2010 Pandora Products.
This work is licensed under the Creative Commons Attribution-Share Alike
3.0 United States License.
To view a copy of this license, visit
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://creativecommons.org/licenses/by-sa/3.0/us/
\end_layout
\end_inset
or send a letter to Creative Commons, 171 Second Street, Suite 300, San
Francisco, California, 94105, USA.
\end_layout
\begin_layout Standard
and
\begin_inset VSpace medskip
\end_inset
Pandora Products
\end_layout
\begin_layout Standard
215 Uschak Road
\end_layout
\begin_layout Standard
Derry, PA 15627
\end_layout
\begin_layout Standard
\begin_inset VSpace medskip
\end_inset
Phone: 724.539.1276
\end_layout
\begin_layout Standard
Fax: 724.539.1276
\end_layout
\begin_layout Standard
Web: http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout Standard
Email: jim.schimpf@gmail.com
\end_layout
\begin_layout Standard
\begin_inset VSpace medskip
\end_inset
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
Additional Contributers
\end_layout
\begin_layout Itemize
Marilyn Noz - Editor
\end_layout
\begin_layout Itemize
Wolfgang Stumvoll - Fossil Merge use and Windows use
\end_layout
\begin_layout Standard
\begin_inset Newpage newpage
\end_inset
\end_layout
\begin_layout Section*
Document Revision History
\end_layout
\begin_layout Standard
\shape italic
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
\shape default
.
\end_layout
\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="16" columns="4">
<features>
<column alignment="center" valignment="top" width="0.5in">
<column alignment="center" valignment="top" width="0.5in">
<column alignment="block" valignment="top" width="3in">
<column alignment="center" valignment="top" width="1in">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Version
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Author
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Description
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Date
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.1
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Initial Version
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
24-Apr-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.2
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Finishing up Single User Chapter
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
27-Apr-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.3
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Working on introduction chapter
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
30-Apr-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.4
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Adding multiuser chapter
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1-May-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.5
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
mn
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Adding editorial corrections [ebf40b842a]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
4-May-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.6
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Adding Command sections [e11399d575]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
8-May-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.7
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
English & spelling corrections
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
19-May-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.8
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Spelling fixes
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
30-May-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
0.9
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
ws
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Using Fossil merge [db6c734300]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
2-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.0
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js/ws
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Put Fossil merge first in handling fork
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
3-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.1
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
mn
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Fixes in multiple user chapter [e8770d3172]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
4-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.2
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Start advanced use chapter [2abc23dae5]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
4-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.3
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
mn
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
English corrections Chapter 1 [8b324dc900]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
5-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.4
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
mn
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Sections 2.1 & 2.2 corrections [0b34cb6f04]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
7-Jun-2010
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
1.5
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
js
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Move close leaf to adv use [2abc23dae5]
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
7-Jun-2010
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
0b34cb6f04
\end_layout
\begin_layout Standard
\begin_inset Newpage newpage
\end_inset
\begin_inset CommandInset toc
LatexCommand tableofcontents
\end_inset
\end_layout
\begin_layout Standard
\begin_inset FloatList figure
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage newpage
\end_inset
\end_layout
\begin_layout Section*
Foreward
\end_layout
\begin_layout Section
Source Control & Why you need it
\end_layout
\begin_layout Subsection
What is it
\end_layout
\begin_layout Standard
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 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 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...)
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
A tool called Source Code Control System
\begin_inset CommandInset citation
LatexCommand cite
key "SCCS"
\end_inset
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
why this was done.
It also limited who could edit the file so conflicting edits would not
be done.
\begin_inset CommandInset citation
LatexCommand cite
key "USE-SCCS"
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "versoning"
\end_inset
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 and having bug reports written against it while the next release
of the software is being developed adding features.
The source control system would have to handle what are now called branches
where you have say Version 1 which is released but having fixes added to
create Version 1.1, 1.2, etc.
While you also have Version 2 with new features added under work.
\end_layout
\begin_layout Standard
In 1986 the open source Concurrent Version Control system CVS
\begin_inset CommandInset citation
LatexCommand cite
key "CVS"
\end_inset
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.
\end_layout
\begin_layout Standard
Fossil which was originally released in 2006
\begin_inset CommandInset citation
LatexCommand cite
key "FOSSIL-HOME"
\end_inset
is an easy to install version control system that also includes a trouble
ticketing system ( Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:viewticket"
\end_inset
), a wiki ( Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Wiki-Use"
\end_inset
) and self hosted web server ( Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Starting-Webserver"
\end_inset
).
It's home page is here
\begin_inset Flex URL
status open
\begin_layout Plain Layout
http://www.fossil-scm.org/
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsection
Why do it ?
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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
\begin_inset Quotes eld
\end_inset
It worked yesterday
\begin_inset Quotes erd
\end_inset
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 yesterdays code and then starting from known
good code you can figure out what happened.
\end_layout
\begin_layout Standard
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 what we had.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
How to get it
\end_layout
\begin_layout Standard
If this has interested you then you can get a copy of the Fossil executable
here
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://www.fossil-scm.org/download.html
\end_layout
\end_inset
.
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Multiple-Users"
\end_inset
).
\end_layout
\begin_layout Subsection
Source control description
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
Check out systems
\end_layout
\begin_layout Standard
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
\begin_inset Quotes eld
\end_inset
checking-out
\begin_inset Quotes erd
\end_inset
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
\begin_inset Quotes eld
\end_inset
owner
\begin_inset Quotes erd
\end_inset
can edit it.
When done editing the
\begin_inset Quotes eld
\end_inset
owner
\begin_inset Quotes erd
\end_inset
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.
\end_layout
\begin_layout Standard
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
\series bold
you
\series default
have to make a change in it.
In a small group setting, just a shout over the cube wall will solve the
problem.
\end_layout
\begin_layout Subsubsection
Merge systems
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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 contributer
s.
\end_layout
\begin_layout Subsubsection
Distributed systems
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
Common Terms
\end_layout
\begin_layout Standard
Following is a list of terms I will use when talking about version control
or Fossil.
\end_layout
\begin_layout Description
Repository This is the store when the version controlled files are kept.
It will be managed by a source control system
\end_layout
\begin_layout Description
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
\end_layout
\begin_layout Description
Commit In Fossil to store the current set of new and changed files into
the repository.
\end_layout
\begin_layout Description
Trunk The main line of code descent in a Fossil repository.
\end_layout
\begin_layout Description
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.
\end_layout
\begin_layout Description
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_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Single-User-Fossil"
\end_inset
Single User Fossil Use
\end_layout
\begin_layout Subsection
Introduction
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsection
Creating a repository
\end_layout
\begin_layout Subsubsection
Introduction
\end_layout
\begin_layout Standard
In the spirit of
\begin_inset Quotes eld
\end_inset
eating one's own dog food
\begin_inset Quotes erd
\end_inset
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
\begin_inset CommandInset citation
LatexCommand cite
key "LyX"
\end_inset
) and my working area looks like this:
\end_layout
\begin_layout LyX-Code
\size scriptsize
FOSSIL/
\end_layout
\begin_deeper
\begin_layout LyX-Code
\size scriptsize
This directory holds all my Fossil repositories
\end_layout
\end_deeper
\begin_layout LyX-Code
\size scriptsize
FossilBook/
\end_layout
\begin_deeper
\begin_layout LyX-Code
\size scriptsize
outline.txt - Book design
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossilbook.lyx - The book
\end_layout
\begin_layout LyX-Code
\size scriptsize
Layout
\end_layout
\begin_deeper
\begin_layout LyX-Code
\size scriptsize
fossil.png - The Fossil logo (image on title page)
\end_layout
\end_deeper
\begin_layout LyX-Code
\size scriptsize
Research
\end_layout
\begin_deeper
\begin_layout LyX-Code
\size scriptsize
fossilbib.bib - Working bibliography
\end_layout
\begin_layout LyX-Code
\size scriptsize
History
\end_layout
\begin_deeper
\begin_layout LyX-Code
\size scriptsize
CVC-grune.pdf - Historical paper about CVS
\end_layout
\begin_layout LyX-Code
\size scriptsize
RCS-A System for Version Control.webloc - RCS bookmark
\end_layout
\begin_layout LyX-Code
\size scriptsize
SCCS-Slideshow.pdf - Historical paper about SCCS
\end_layout
\begin_layout LyX-Code
\size scriptsize
VCSHistory -pysync ...
.webloc - History of version control
\end_layout
\end_deeper
\end_deeper
\end_deeper
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
Create Repository
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout LyX-Code
\size scriptsize
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil new ../FOSSIL/FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
project-id: 2b0d35831c1a5b315d74c4fd8d532b100b822ad7
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-id: 0149388e5a3109a867332dd8439ac7b454f3f9dd
\end_layout
\begin_layout LyX-Code
\size scriptsize
admin-user: jim (initial password is "
\series bold
ec3773
\series default
")
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Create Repository
\begin_inset CommandInset label
LatexCommand label
name "fig:Create-Repository"
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I create my repositories with the extension .fossil, this will be useful
later with the server command (See Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:server-detail"
\end_inset
).
When the create happened it assigned an initial password with an admin
user of
\begin_inset Quotes eld
\end_inset
jim
\begin_inset Quotes erd
\end_inset
(i.e.,me).
\end_layout
\begin_layout Subsubsection
Connect Repository
\end_layout
\begin_layout Standard
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
\series bold
open
\series default
command.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil open ../FOSSIL/FossilBook.fossil
\series default
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil status
\end_layout
\begin_layout LyX-Code
\size scriptsize
repository: /Users/jschimpf/Public/FOSSIL/FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
local-root: /Users/jschimpf/Public/FossilBook/
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-code: 0149388e5a3109a867332dd8439ac7b454f3f9dd
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout: 279dfecd3f0322f236a92a9a8f3c96acf327d8c1 2010-04-25 12:40:39
UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
tags: trunk
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil extra
\end_layout
\begin_layout LyX-Code
\size scriptsize
Layout/fossil.png
\end_layout
\begin_layout LyX-Code
\size scriptsize
Research/History/CVS-grune.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Research/History/RCS—A System for Version Control.webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
Research/History/SCCS-Slideshow.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Research/History/VCSHistory - pysync - ....webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
Research/fossilbib.bib
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
outline.txt
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Open Repository & Check
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The
\series bold
open
\series default
command seemingly did nothing but checking with the
\series bold
status
\series default
command shows the repository, the directory it's linked to and that we
are hooked to the trunk of the store.
\end_layout
\begin_layout Standard
The
\series bold
extra
\series default
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.
\end_layout
\begin_layout Subsubsection
Add and Initial Commit
\end_layout
\begin_layout Standard
I must now add all the relevant files into the repository with the
\series bold
add
\series default
command.
The Fossil add is recursive so if I add the top level files it will automatical
ly 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 accidentall
y 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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil add .
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Layout/fossil.png
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Research/History/CVS-grune.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Research/History/RCS—A System for Version Control.webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Research/History/SCCS-Slideshow.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Research/History/VCSHistory - pysync ....webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Research/fossilbib.bib
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil: cannot add _FOSSIL_
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED outline.txt
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Initial file add
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I simply told fossil to do an add of the current directory (.) so it got
all those files and all the files in the subdirectory.
Note the _FOSSIL_ that it didn't add.
This is the tag file that fossil keeps in a directory so it knows what
repository it belongs to.
Fossil won't add this file since it manages it but everything else is fair
game.
\end_layout
\begin_layout Standard
One final thing before I can quit for the day, these files have been added
or rather they will be added to the repository when I commit it.
That must be done and then we can relax and let Fossil manage things.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil commit -m "Initial Commit"
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: 8fa070818679e1744374bc5302a621490276d739
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Initial Commit
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
Fossil start up summary
\end_layout
\begin_layout Itemize
\series bold
fossil create <name>
\series default
Creates a new fossil repository
\end_layout
\begin_layout Itemize
\series bold
fossil open <repository>
\series default
While in a source directory connects this directory to the fossil repository
\end_layout
\begin_layout Itemize
\series bold
fossil add .
\series default
Will add (recursively) all the files in the current directory and all subdirect
ories to the repository
\end_layout
\begin_layout Itemize
\series bold
fossil commit -m
\begin_inset Quotes eld
\end_inset
Initial Commit
\begin_inset Quotes erd
\end_inset
\series default
Will put all the currently added files into the repository.
\end_layout
\begin_layout Subsection
Set Up User interface
\end_layout
\begin_layout Standard
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 prep the web interface for production use.
\end_layout
\begin_layout Description
\series bold
NOTE
\series default
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_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil ui -port 8081
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Starting-Webserver"
\end_inset
Starting Webserver
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\noindent
\align left
\begin_inset Graphics
filename Images/Single_user/initial_page.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Initial-Webserver-page"
\end_inset
Initial Webserver page
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Following the advice on the page I go to
\series bold
setup/config
\series default
.
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/config_initial.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Initial-Configuration"
\end_inset
Initial Configuration
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Wiki-Use"
\end_inset
) 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
\series bold
Apply Changes
\series default
button.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/user_config.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:User-Configuration"
\end_inset
User Configuration
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Create-Repository"
\end_inset
), it's a very good idea to change this to something you can remember rather
than the original random one.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/jim_setup.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Super User Setup
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
Now the repository is ready for further work, it's rather bare bones at
this point but the most important things are set up.
\end_layout
\begin_layout Subsubsection
User interface summary
\end_layout
\begin_layout Itemize
\series bold
fossil ui
\series default
run in the source directory will start a browser based user interface to
fossil.
\end_layout
\begin_layout Itemize
\series bold
fossil ui -port <IP port #>
\series default
Can be used if port 8080 if already in use on your system.
\end_layout
\begin_layout Itemize
On the first run it is important to configure your project with a name and
set the password for yourself.
\end_layout
\begin_layout Subsection
Update Repository
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil extra
\end_layout
\begin_layout LyX-Code
\size scriptsize
#fossilbook.lyx#
\end_layout
\begin_layout LyX-Code
\size scriptsize
Images/Single_user/config_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Images/Single_user/initial_page.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Images/Single_user/jim_setup.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Images/Single_user/user_config.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossilbook.lyx~
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil status
\end_layout
\begin_layout LyX-Code
\size scriptsize
repository: /Users/jschimpf/Public/FOSSIL/FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
local-root: /Users/jschimpf/Public/FossilBook/
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-code: 0149388e5a3109a867332dd8439ac7b454f3f9dd
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout: 8fa070818679e1744374bc5302a621490276d739 2010-04-25 13:09:02
UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
parent: 279dfecd3f0322f236a92a9a8f3c96acf327d8c1 2010-04-25 12:40:39
UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
tags: trunk
\end_layout
\begin_layout LyX-Code
\size scriptsize
EDITED fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Project Status
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I run
\series bold
fossil extra
\series default
to see these new files.
The image files (those in Images/Single_user) I want to add, the other
two files #fossilbook.lyx# and fossilbook.lyx~ that I don't want to add since
they are temporary artifacts of LyX.
I also ran
\series bold
fossil status
\series default
, this shows changes to files that are already in the repository, there
the only file changed is the book text itself,
\series bold
fossilbook.lyx
\series default
.
\end_layout
\begin_layout Standard
All I have to do now is add in the directory Images which will add in the
image files I want in the repository.
Then I commit the changes to the repository and we can move on to other
tasks of the day.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil add Images
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/config_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/initial_page.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/jim_setup.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/user_config.epsf
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil commit -m "Initial setup with pictures"
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: a2d12bf532a089ee53578e3e17c6e732c0442f49
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Update-for-new"
\end_inset
Update for new files
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
After doing this commit I can bring up the Fossil ui (see Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Starting-Webserver"
\end_inset
) and view the project Timeline by picking that tab on the Fossil header.
We get this:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/timeline.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Timeline
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can see all my check-ins thus far and you can see after the check-in
from Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Update-for-new"
\end_inset
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/timeline_detail.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Timeline Detail
\begin_inset CommandInset label
LatexCommand label
name "fig:Timeline-Detail"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I clicked on the very last check-in (the
\series bold
LEAF)
\series default
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
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://www.fossil-scm.org/
\end_layout
\end_inset
.
The edit link will be used later to modify a leaf.
\end_layout
\begin_layout Subsubsection
Update Summary
\end_layout
\begin_layout Itemize
\series bold
fossil status
\series default
and
\series bold
fossil extra
\series default
will tell you the updated files and files not in the repository before
you commit.
\end_layout
\begin_layout Itemize
\series bold
fossil commit - m
\begin_inset Quotes eld
\end_inset
Commit comment
\begin_inset Quotes erd
\end_inset
\series default
Commits a changes, it is very important to have a descriptive comment on
your commit.
\end_layout
\begin_layout Subsection
Tickets
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/ticket_initial.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Initial Ticket Window
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Picking New Ticket I get a form that I fill out like so:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/ticket_form.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Ticket Form
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/ticket_submit.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Viewing a Ticket
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Finally picking Tickets then All Tickets I can see my new ticket in the
list marked as Open and in a distinctive color.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/ticket_list.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:viewticket"
\end_inset
Ticket List with open ticket
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil add Images/Single_user
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/config_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/initial_page.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/jim_setup.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/ticket_form.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/ticket_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/ticket_list.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/ticket_submit.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/timeline.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/timeline_detail.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADDED Images/Single_user/user_config.epsf
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil commit -m "[1665c78d94] Ticket Use"
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:checkin"
\end_inset
Ticket resolving check-in
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\series bold
config_initial.epsf
\series default
but Fossil is smart and knows this and won't add that one twice.
Even though it shows it ADDED, it really didn't.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:viewticket"
\end_inset
.
From there I pick edit and fill it in as shown:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/ticket_done.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Ticket Finish
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:checkin"
\end_inset
.
By doing this my ticket is now cross linked with the commit and the commit
has a link back to the ticket.
\end_layout
\begin_layout Subsubsection
Ticket Summary
\end_layout
\begin_layout Itemize
Tickets are a useful way of reminding you what needs done or bugs fixed
\end_layout
\begin_layout Itemize
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
\end_layout
\begin_layout Itemize
When you close the ticket put in the hash label of the commit that fixed
it.
\end_layout
\begin_layout Subsection
\begin_inset CommandInset label
LatexCommand label
name "sub:Wiki-Use"
\end_inset
Wiki Use
\end_layout
\begin_layout Standard
As we saw in Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Starting-Webserver"
\end_inset
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Initial-Webserver-page"
\end_inset
that is the initial page for your project and from there you can add new
pages, these are automatically managed by the Fossil version control system,
you don't have to add or commit.
\end_layout
\begin_layout Standard
Since I did the setup on repository (see Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Initial-Configuration"
\end_inset
) the home page has changed to this:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/wiki_blankhome.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Blank Home Page
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/wiki_page.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Wiki-controls"
\end_inset
Wiki controls
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://www.webmonkey.com/2010/02/html_cheatsheet/
\end_layout
\end_inset
and keep it handy.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/wiki_formating.epsf
scale 60
\end_inset
\begin_inset Caption
\begin_layout Plain Layout
Wiki Formating
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Wiki-controls"
\end_inset
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/wiki_homeedit.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Home page with edit
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This shows my initial edit and a preview:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Single_user/wiki_home.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Initial Home page
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The bottom section is an edit window where I type things I want displayed
and the top is a preview of what the page will be.
As you can see I typed some simple HTML to make a large and centered title.
The body of the text I just typed and as you see the browser fits the text
to the screen.
You can have multiple paragraphs by just putting blank lines between your
text.
Next I wanted a bulleted list and this is done by typing two spaces, a
'*' then two more spaces.
On each of these lines I have a link to a new (not yet created page).
If you look I put these in the form [ <new page> | <title> ].
This way I can have a long string that describes the link but have a nice
short (no embedded spaces) page name.
\end_layout
\begin_layout Standard
One mistake I usually make at this point is to click one of those new links
which takes me to a new blank page.
\series bold
OOPS
\series default
, if I have not saved this page yet then I find I've lost my changes so
far.
\end_layout
\begin_layout Standard
OK, I will save my changes and then go to the new pages.
I am doing some complicated things here.
The first link is to the book PDF, this will be a file I create in the
repository.
The LyX program I'm using creates the PDF, I will do that save it and add
it to the repository.
But I don't want to link to a static file, that is I want the most current
version of the PDF, the one I save each time I quit for the day.
To do this we have to put in a link that looks like this:
\end_layout
\begin_layout LyX-Code
[http:doc/tip/FossilBook.pdf | Book (pdf) ]
\end_layout
\begin_layout Standard
This is a special link the Fossil wiki understands,
\series bold
doc
\series default
says this is documentation.
\series bold
tip
\series default
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
\series bold
doc/tip/subdir/filename.
\end_layout
\begin_layout Standard
The second link is just to a regular page and I can just edit that one just
like I did this the main page.
\end_layout
\begin_layout Subsubsection
Wiki Summary
\end_layout
\begin_layout Itemize
Format your text using HTML commands like <h1>Title</h1> for page headings
\end_layout
\begin_layout Itemize
Create and link pages using [ <page> | <Link text> ]
\end_layout
\begin_layout Itemize
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)
\end_layout
\begin_layout Itemize
Never click on a link till AFTER you have saved the page
\end_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Multiple-Users"
\end_inset
Multiple Users
\end_layout
\begin_layout Subsection
Introduction
\end_layout
\begin_layout Standard
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 automatica
lly the multiple user details.
\end_layout
\begin_layout Subsection
Setup
\end_layout
\begin_layout Standard
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 it means is there is
a master repository in a place that all users can access.
Each user has their own
\begin_inset Quotes eld
\end_inset
cloned
\begin_inset Quotes erd
\end_inset
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
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Single-User-Fossil"
\end_inset
.
It's just that now Fossil will keep your repository in sync with the master.
\end_layout
\begin_layout Subsubsection
Server Setup
\begin_inset CommandInset label
LatexCommand label
name "sub:Server-Setup"
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Paragraph
Self hosted
\end_layout
\begin_layout Standard
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.
I.e.
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:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:/Users/jschimpf/Public] jim% cd FOSSIL/
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FOSSIL] jim%
\series bold
fossil ui -port 8081 FossilBook.fossil &
\series default
\end_layout
\begin_layout LyX-Code
\size scriptsize
[1] 310
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FOSSIL] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Self-hosted Fossil repository
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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:
\end_layout
\begin_layout Standard
\series bold
http://192.168.1.200:8081
\series default
to the browser and I can access the Fossil web server.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
The problems with this method are:
\end_layout
\begin_layout Enumerate
If you have multiple repositories you have to use the
\series bold
server
\series default
not the
\series bold
ui
\series default
command, have all your repositories in the same directory and have them
all use the extension .fossil.
\end_layout
\begin_layout Enumerate
If the machine goes off line (i.e.
for OS update) or other reason it might not automatically restart the Fossil
servers.
\end_layout
\begin_layout Enumerate
Backup of the repositories might be not be done.
\end_layout
\begin_layout Standard
This method does work and if you only have one repository and a diligent
owner of the master machine it will work and work well.
\end_layout
\begin_layout Paragraph
Server hosted
\end_layout
\begin_layout Standard
If you have a server type machine available (i.e.
a Linux or UNIX box) that is running Apache or Windows machine running
IIS you can let it be the webserver for your repository.
This has a number of advantages, this machine will be up all the time,
it will probably be automatically backed up and it can easily support multiple
Fossil repositories.
\end_layout
\begin_layout Standard
I am not going into how to set up the webserver or how to enable (Common
Gateway Interface) CGI.
See the following sites.
\end_layout
\begin_layout Itemize
For IIS see here
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://www.boutell.com/newfaq/creating/iiscgihowto.html
\end_layout
\end_inset
and just ensure that your fossil.exe is in the path to be run by the cgi
script.
\end_layout
\begin_layout Itemize
For Apache see here
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
http://httpd.apache.org/docs/2.0/howto/cgi.html
\end_layout
\end_inset
and ensure you know the directory where the CGI scripts are stored.
\end_layout
\begin_layout Standard
If you are not in control of the webserver you will need the help of the
server admin to enable CGI and to copy your CGI scripts to correct location.
\end_layout
\begin_layout Paragraph
CGI Script for hosted server
\end_layout
\begin_layout Standard
If we assume an Apache server and in my case the cgi directory is /Library/Webse
rver/CGI-Executables then we have to write a script of the form:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
#!<Fossil executable location>
\end_layout
\begin_layout LyX-Code
repository: <Fossil repository location>
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Fossil CGI script
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
#!/usr/local/bin/fossil
\end_layout
\begin_layout LyX-Code
# Put the book repository on the web
\end_layout
\begin_layout LyX-Code
repository: /Users/Shared/FOSSIL/Fossilbook.fossil
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
My Fossil CGI script
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
After making the script I then copy it to the CGI directory and allow anyone
to execute it.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\series bold
\size scriptsize
sudo cp Book.cgi /Library/Webserver/CGI-Executables/Book.cgi
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\series bold
\size scriptsize
sudo chmod a+x /Library/Webserver/CGI-Executables/Book.cgi
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Copying script into place
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
The test (either self hosted or server hosted)
\end_layout
\begin_layout Standard
If all is in place then I should be able to access the webserver and get
to this:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Multiple_user/test_access.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Web-access-to"
\end_inset
Web access to Fossil CGI hosted site
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
User Accounts
\end_layout
\begin_layout Standard
Serving a repository, either self hosting or the more complicated CGI method
gets you to the same place as shown in Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Web-access-to"
\end_inset
.
Now I have to set up user accounts for the other contributers to this book.
Remember Fossil has automatically created an Anonymous user (see Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:User-Configuration"
\end_inset
) 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.
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand eqref
reference "fig:User-Configuration"
\end_inset
and add a new user:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Multiple_user/mul_new_user.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
New Editor user
\begin_inset CommandInset label
LatexCommand label
name "fig:New-Editor-user"
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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, 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.
\end_layout
\begin_layout Standard
I could add other users at this point but don't need any others for this
project and 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.
\end_layout
\begin_layout Subsection
Multiple User Operation
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Single-User-Fossil"
\end_inset
.
Fossil will synchronize your local repository with the one on the server.
\end_layout
\begin_layout Subsubsection
Cloning
\end_layout
\begin_layout Standard
To clone a Fossil repository you have to know four things:
\end_layout
\begin_layout Enumerate
It's web address, for our repository it is
\series bold
http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout Enumerate
Your account name in my case it's
\series bold
jim
\end_layout
\begin_layout Enumerate
Your password (which I'm keeping to myself thank you...)
\end_layout
\begin_layout Enumerate
The local name of the repository, in this case I'm calling it Fossilbook.fossil
\end_layout
\begin_layout Standard
You then go to where you want to keep the Repository (in my case the FOSSIL
directory) and use the clone command:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size tiny
[Pandora-2:jschimpf/Public/FOSSIL]
\series bold
fossil clone http://jim:
\series default
<passwd>
\series bold
@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\series bold
\size scriptsize
### NOTE: <passwd>
\series default
- Stands in for real password
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 49 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 120 2 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 625 25 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4704 72 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 3104 72 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 5129052 131 10 5
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 2399 51 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4381170 116 22 28
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 4117 bytes sent, 6913068 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
Rebuilding repository meta-data...
\end_layout
\begin_layout LyX-Code
\size scriptsize
65 (100%)...
\end_layout
\begin_layout LyX-Code
\size scriptsize
project-id: 2b0d35831c1a5b315d74c4fd8d532b100b822ad7
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-id: 3e67da6d6212494456c69b1c5406a277d7e50430
\end_layout
\begin_layout LyX-Code
\size scriptsize
admin-user: jim (password is "d07222")
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FOSSIL] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Clone command
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
At this point I can go through the steps outlined in Section
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Single-User-Fossil"
\end_inset
to set my user password and then open the Fossil Repository on a working
directory.
\end_layout
\begin_layout Standard
Now that I've moved everything to the new cloned repository I do a check
in a the end of the day which looks like this:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil commit -m "Moved to clone repository"
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 2990 65 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 334 bytes sent, 1876 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: 158492516c640d055bc0720684a05e797b88165a
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 618798 74 1 2
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 3222 70 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 268138 73 1 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 3221 70 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 3977 72 0 1
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 3220 70 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 457995 bytes sent, 6011 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Cloned-repository-checkin"
\end_inset
Cloned repository checkin
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
As you see the files were committed locally and then the local repository
was automatically synchronized with the repository on the server.
\end_layout
\begin_layout Subsubsection
Keeping in sync
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "There-are-two"
\end_inset
There are two problems:
\end_layout
\begin_layout Enumerate
Before I do any work I must be sure I have the current versions of all the
files.
\end_layout
\begin_layout Enumerate
When I commit I must make sure what I am committing has only my changes
and not stepping on changes she has done.
\end_layout
\begin_layout Standard
The first is pretty obvious, make sure you have the latest before you do
anything.
We do that with the update command.
In Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Cloned-repository-checkin"
\end_inset
I had done my latest check in.
Before starting any more work I should ensure that Marilyn hasn't checked
in something else.
I could check the timeline but instead I'll do an update to my repository
and source files.
When I do the update I specify it should be updated from the
\series bold
trunk.
\series default
This ensures I get it from the latest and greatest not some branch.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil update trunk
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 3588 78 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 365 6 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 136461 83 2 3
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 796 bytes sent, 131582 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\size default
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Update action
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Ah ha ! Marilyn has been at work and updated the book source and pdf.
If I check the timeline from the webserver I see she has even documented
it:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Multiple_user/mul_timeline.epsf
scale 40
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Updated Timeline
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Now I know I have the current state of the world and I can proceed add in
new sections.
\end_layout
\begin_layout Subsubsection
Complications
\begin_inset CommandInset label
LatexCommand label
name "sub:Complications"
\end_inset
\end_layout
\begin_layout Standard
In
\begin_inset CommandInset ref
LatexCommand vref
reference "There-are-two"
\end_inset
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....
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil commit -m "Commit that might fork"
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4002 87 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 365 6 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 110470 92 2 3
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 797 bytes sent, 104567 bytes received
\end_layout
\begin_layout LyX-Code
\series bold
\size scriptsize
fossil: would fork.
"update" first or use -f or --force.
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Forking commit
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Ah ha, that very thing has happened and fossil warned me that my copy of
the file differs from the master copy.
If I did a --force then the repository would generate a fork and Marilyn's
future commits would be to her fork and my commits would be to mine.
That would not be what we want since I want her to edit
\series bold
\series default
my copy of the book.
\end_layout
\begin_layout Standard
The next step would be to do as Fossil says and do an update.
At this point you have to be careful since blindly updating the changed
files could overwrite the stuff I've just done.
So we do a trial update by using the -n and -v options to say
\begin_inset Quotes eld
\end_inset
do a dry run
\begin_inset Quotes erd
\end_inset
and show me the results.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil update -n -v
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Multiple_user/mul_new_user.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Multiple_user/mul_timeline.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Multiple_user/test_access.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/config_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/initial_page.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/jim_setup.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/ticket_done.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/ticket_form.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/ticket_initial.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/ticket_list.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/ticket_submit.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/timeline.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/timeline_detail.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/user_config.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/wiki_blankhome.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/wiki_formating.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/wiki_home.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/wiki_homeedit.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Images/Single_user/wiki_page.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Layout/fossil.png
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Research/History/CVS-grune.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Research/History/RCS—A System for Version Control.webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Research/History/SCCS-Slideshow.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Research/History/VCSHistory - pysync - A Brief History of Version
Control Systems - Project Hosting on Google Code.webloc
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED Research/fossilbib.bib
\end_layout
\begin_layout LyX-Code
\size scriptsize
MERGE fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UNCHANGED outline.txt
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Update dry run
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
That's a little more than I wanted as you can see almost everything is UNCHANGED
but it shows that fossilbook.lyx needs a MERGE and fossilbook.pdf needs an
UPDATE.
This is what I should expect, Marilyn has done edits to the fossilbook.lyx
file and so have I so we have to merge the changes.
But she has also updated the fossilbook.pdf which I have not.
Before we go on if you are running on Linux or UNIX you can simplify this
dry run by doing:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil update -n -v | grep -v UNCHANGED
\end_layout
\begin_layout LyX-Code
\size scriptsize
MERGE fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.pdf
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Update dry run, shorter
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
By using the pipe and grep I can eliminate all those extra UNCHANGED lines.
\end_layout
\begin_layout Subsubsection
Fixing the Update file
\end_layout
\begin_layout Standard
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
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Multiple_user/mul_timeline.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Current Timeline
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I see that the current
\series bold
Leaf
\series default
is [d55769cc23] and it is tagged as
\series bold
trunk
\series default
.
I want to update the fossilbook.pdf from there.
So I say:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil update trunk fossilbook.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4002 87 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 334 bytes sent, 2412 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Update fossilbook.pdf
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
and it's done.
\end_layout
\begin_layout Subsubsection
Fixing the Merge file
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
E:
\backslash
Profile
\backslash
Ratte
\backslash
data
\backslash
organize
\backslash
fossil-w32
\backslash
fossil-book>fossil commit -m "adding some changes of jim"
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil: would fork. "update" first or use -f or --force.
\end_layout
\begin_layout LyX-Code
\size scriptsize
\end_layout
\begin_layout LyX-Code
\size scriptsize
E:
\backslash
Profile
\backslash
Ratte
\backslash
data
\backslash
organize
\backslash
fossil-w32
\backslash
fossil-book>fossil commit -f -m "adding some other changes of jim"
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: df9f2ff6b14ef65a9dd2162f8bd20c78e1628165
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Forcing a commit under Windows
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Now the timeline looks like:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/Windows/forked_timeline.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Windows Forked timeline
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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 an
paste between the two file versions using the handler program for the file.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
E:
\backslash
Profile
\backslash
Ratte
\backslash
data
\backslash
organize
\backslash
fossil-w32
\backslash
fossil-book>fossil merge a91582b699
\end_layout
\begin_layout LyX-Code
\size scriptsize
MERGE fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
***** 2 merge conflicts in fossilbook.lyx
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Fossil Merge
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Looking at the file (fossilbook.lyx) in a text editor (not LyX) we find:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
>>>>>>> BEGIN MERGE CONFLICT
\end_layout
\begin_layout LyX-Code
\size scriptsize
Thanks to Fossil's distributed design once the set up is done using it
\end_layout
\begin_layout LyX-Code
\size scriptsize
with multiple users is not much different than the single user case.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Fossil will automatically manage the most multiple user details.
\end_layout
\begin_layout LyX-Code
\size scriptsize
============================
\end_layout
\begin_layout LyX-Code
\size scriptsize
\end_layout
\begin_layout LyX-Code
\size scriptsize
Thanks to Fossil's distributed design once the set up is done using is
\end_layout
\begin_layout LyX-Code
\size scriptsize
not much different than the single user case with Fossil managing automatically
\end_layout
\begin_layout LyX-Code
\size scriptsize
the multiple user details.
\end_layout
\begin_layout LyX-Code
\size scriptsize
<<<<<<< END MERGE CONFLICT
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\series bold
<Here edit in the changes>
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
E:
\backslash
Profile
\backslash
Ratte
\backslash
data
\backslash
organize
\backslash
fossil-w32
\backslash
fossil-book>fossil commit -m "merging marilyn's fork back"
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: acdd676d3ab157769496f6845ccc7652985c1d03
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Text differences
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Updating-by-others"
\end_inset
)
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/Windows/merged_timeline.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Merged timeline
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Section
Advanced Use
\end_layout
\begin_layout Subsection
Introduction
\end_layout
\begin_layout Standard
This chapter will introduce some advanced topics for Fossil use such as
tagging and branching.
Also it will show how to merge forks.
Forks appear when you merge in files which include changes and differences
from the repository version.
This was illustrated in Section
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Complications"
\end_inset
.
If instead of fixing the file then doing the commit we forced the merge
then Fossil would fork the repository.
\end_layout
\begin_layout Standard
Forking is something to avoid because it creates two checkin paths for the
code, then different users will be on different paths and can check in
contradictory changes.
Branches on the other hand are forks that you desire, these are when you
want to have two different versions of the code base in development at
the same time.
This was described in
\begin_inset CommandInset ref
LatexCommand vref
reference "versoning"
\end_inset
where you have a production verison of code under maintenance and 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.
\end_layout
\begin_layout Standard
Instead of using the book repository for these examples we will use a JSON
\begin_inset CommandInset citation
LatexCommand cite
key "JSON"
\end_inset
parser program that has a number of files and documentation.
This will make it simpler to illustrate branching and tagging.
\end_layout
\begin_layout Subsection
Simple Merge Case
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Multiple-Users"
\end_inset
.
The JSON code has been placed in distributed location, each of them clones
the repository and opens a working copy of the code.
\end_layout
\begin_layout Subsubsection
Marilyn's Actions
\end_layout
\begin_layout Standard
She looks through the documentation and finds a number of problems and fixes
them (the documentation uses LyX and PDF's).
So she is satisfied with what she has done and checks this in:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Advanced/Simple_Merge/sm_Marilyn.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Marilyn's-work"
\end_inset
Marilyn's work
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Jim's Actions
\end_layout
\begin_layout Standard
At the same time, Jim gets a working copy of version [6edbaf5fa8] of the
code, puts in a ticket [d23bf4bbbb] as shown in Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Marilyn's-work"
\end_inset
.
After fixing the warnings, Jim is done and goes to commit, he does this
AFTER Marilyn has done her commit.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
551 jsonp>
\series bold
fossil commit -m "[d23bf4bbbb] Remove warnings"
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 874 19 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 339 bytes sent, 771 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
fossil: would fork.
"update" first or use -f or --force.
\end_layout
\begin_layout LyX-Code
\size footnotesize
552 jsonp>
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Jim's commit attempt
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
At this point Fossil recognizes that Marilyn has changed the repository
(she updated the documentation) but Jim does not have these changes because
he checked out an earlier version of the code.
Jim says he
\series bold
must
\series default
get his changes in so he does a FORCE to force fossil to accept the commit.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
552 jsonp>
\series bold
fossil
\series default
\series bold
commit -m "[d23bf4bbbb] Remove warnings" -f
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 874 19 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 338 bytes sent, 771 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
New_Version: 1beab955418a942ab9953c4865109ff46cbbd691
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 2646 25 0 4
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 1058 23 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 1498 bytes sent, 864 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
**** warning: a fork has occurred *****
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Forcing the commit
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Looking at the timeline Jim sees this:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Advanced/Simple_Merge/sm_jim_fork.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Repository Fork
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Not good, there are two
\series bold
Leaf
\series default
'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].
\end_layout
\begin_layout Subsubsection
Fixing the fork
\end_layout
\begin_layout Standard
So Jim who's checked out code is from Leaf [1beab85441] does a merge with
Marilyn's leaf [b72e96832e] like so:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
556 jsonp>
\series bold
fossil merge b72e96832e
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATE docs/qdj.lyx
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATE docs/qdj.pdf
\end_layout
\begin_layout LyX-Code
\size footnotesize
557 jsonp>
\series bold
fossil status
\end_layout
\begin_layout LyX-Code
\size footnotesize
repository: /Users/jschimpf/Public/FOSSIL/jsonp.fossil
\end_layout
\begin_layout LyX-Code
\size footnotesize
local-root: /Users/jschimpf/Public/jsonp/
\end_layout
\begin_layout LyX-Code
\size footnotesize
server-code: d3e7932b0b0f5e704264ba30adeae14978c08bc6
\end_layout
\begin_layout LyX-Code
\size footnotesize
checkout: 1beab955418a942ab9953c4865109ff46cbbd691 2010-06-08 10:44:56
UTC
\end_layout
\begin_layout LyX-Code
\size footnotesize
parent: 6edbaf5fa8e4d061c2e04e7fd481e7663b090bd3 2010-06-07 10:45:57
UTC
\end_layout
\begin_layout LyX-Code
\size footnotesize
tags: trunk
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATED_BY_MERGE docs/qdj.lyx
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATED_BY_MERGE docs/qdj.pdf
\end_layout
\begin_layout LyX-Code
\size footnotesize
MERGED_WITH b72e96832e024f235696dcd6c5d0ddcc2cb38238
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Merge-Operation"
\end_inset
Merge Operation
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
As shown the two documentation files are updated, there are no merge conflicts
as Jim didn't touch these files and Marilyn didn't touch the code files.
\end_layout
\begin_layout Standard
Next Jim does a commit to make this new merged set of files the new trunk.
Rememeber doing the merge shown in Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Merge-Operation"
\end_inset
just updates your checked out code and does not change the repository till
you check it in.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
558 jsonp> fossil
\series bold
commit -m "After merging in changes"
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 1058 23 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 340 bytes sent, 864 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
New_Version: 3d73c03edee33cdc2e1bd8a47de57b7a6b6d880a
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 1737 26 0 1
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 1104 24 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 1101 bytes sent, 888 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
559 jsonp>
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Commit after merge
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
When we look at the timeline we have a single leaf for future code commits.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename Images/Advanced/Simple_Merge/sm_after_merge.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
After merge timeline
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The only other thing remaining is that Marilyn does an Update before proceeding
so her checked out code matches the repository.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size footnotesize
WhiteBook:jsonp marilyn$
\series bold
fossil update
\end_layout
\begin_layout LyX-Code
\size footnotesize
Autosync: http://Marilyn@pandora.dyn-o-saur.com:8080/cgi-bin/jsonp.cgi
\end_layout
\begin_layout LyX-Code
\size footnotesize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 1150 25 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Send: 412 7 0 0
\end_layout
\begin_layout LyX-Code
\size footnotesize
Received: 3274 31 1 5
\end_layout
\begin_layout LyX-Code
\size footnotesize
Total network traffic: 843 bytes sent, 2709 bytes received
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATE json-src/qdj_token.c
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATE json-src/qdj_util.c
\end_layout
\begin_layout LyX-Code
\size footnotesize
UPDATE main.c
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Marilyn's Update
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Paragraph
Merge with external tools
\end_layout
\begin_layout Standard
This method is used if the merge between the two files is quite complicated
and you need more tools that just a text editor to do the changes.
Also doing it this way does generate a fork that has to be manually closed.
\end_layout
\begin_layout Standard
We can also use the operating system tools to merge the file.
Here we must compare what is in the repository with what we have done.
Since both Marilyn and I started with the same copy of fossilbook.lyx I
can use the diff function in the fossil UI to show me the changes she made
and update mine to match.
The saving grace here is that LyX files are just text (as are most code
source files) so you would do the same with code.
If the files are binary like DOC files it's a bit harder.
The easiest way in that case would be to open a new copy of the repository
on your machine in another directory and then bring up both copies.
Cut and paste between them.
\end_layout
\begin_layout Standard
So proceeding with the compare we pick Marilyn's last change from the time
line.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_checkin.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Marilyn's change
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Then we pick the diff link on the fossilbook.lyx line.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_diff.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
File Diff
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I see there are a large number of changes, I could manually edit them in
but it's easier to use the Linux/UNIX tools of patch and diff.
We use the Fossil diff command to generate a diff file (called diff.txt).
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil diff fossilbook.lyx > diff.txt
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Generate Fossil Diff
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Now copy the current fossilbook.txt to a temp file (in case I mess up).
But I also revert the fossilbook.lyx file to the one Marilyn did with the
Fossil revert command.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
cp fossilbook.lyx temp.lyx
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil revert fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
REVERTED: fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
"fossil undo" is available to undo the changes shown above.
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Revert to repository version
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Next we patch the repository version (i.e.
Marilyn's) to my edited version with the patch command and then we commit
it.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
patch fossilbook.lyx diff.txt
\end_layout
\begin_layout LyX-Code
\size scriptsize
patching file fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Patching the file
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I look at the file and see that it has my changes and Marilyn's so I can
commit this thing.
When I try the commit it says it's going to fork.
Oh well we just have to force it and we will fix the fork.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil
\series bold
commit -m "Update to fully update book file"
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4002 87 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 337 bytes sent, 2412 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil: would fork.
"update" first or use -f or --force.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil
\series bold
commit -f -m "Updated book with info merging"
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4002 87 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 339 bytes sent, 2412 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
New_Version: 22f5308b2fd4971f04229634420c465c3af0de85
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://jim@pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 256066 93 0 2
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4141 90 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 4753 92 0 1
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 4140 90 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 235163 bytes sent, 4973 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
**** warning: a fork has occurred *****
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Commit with fork
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Handling a fork from the external tool merge
\end_layout
\begin_layout Standard
When I did this last commit it generated a fork.
This was because I was not able to make my fossilbook.lyx match the repository
one.
I have checked and it does have all of Marilyn's changes and mine so I
did want to commit it.
The problem is now we have my commit and Marilyn's.
Hers is now not valid since mine supersedes it.
When we look at the timeline we have:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_fork.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Forked Timeline
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
We have to now kill off the Marilyn Leaf so there is only one copy moving
forward.
We pick Marilyn's leaf and we get:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_leaf_rmv.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Leaf to remove
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Next I pick edit and kill off this leaf.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_close_leaf.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Remove Leaf
\begin_inset CommandInset label
LatexCommand label
name "fig:Remove-Leaf"
\end_inset
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
I do this by picking Leaf Closure also I put in a comment to let me know
I did this and I change the tag to Syntax_edit and remove the trunk tag.
This really removed it from further use.
\end_layout
\begin_layout Standard
Now when I look at the timeline I get:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename /Users/jschimpf/Public/FossilBook/Images/Multiple_user/mul_new_timeline.epsf
scale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Leaf-Removed"
\end_inset
Leaf Removed
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Showing the leaf is removed and we can keep on going.
\end_layout
\begin_layout Subsubsection
Updating by others
\begin_inset CommandInset label
LatexCommand label
name "sub:Updating-by-others"
\end_inset
\end_layout
\begin_layout Standard
The next time Marilyn logs in to work she has to do the following:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
Pandora-2:~ marilyn$
\series bold
cd Documents/
\end_layout
\begin_layout LyX-Code
\size scriptsize
Pandora-2:Documents marilyn$
\series bold
cd FossilBook/
\end_layout
\begin_layout LyX-Code
\size scriptsize
Pandora-2:FossilBook marilyn$
\series bold
fossil update
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://Marilyn@192.168.1.200:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 230 5 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 365 6 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 117772 10 1 4
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 835 16 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 3203524 20 9 6
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 177 2 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 532555 6 1 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 1861 bytes sent, 2252059 bytes received
\end_layout
\begin_layout LyX-Code
\series bold
\size scriptsize
fossil: bad object id: 0
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Pandora-2:FossilBook marilyn$
\series bold
fossil status
\end_layout
\begin_layout LyX-Code
\size scriptsize
repository: /Users/marilyn/Documents/FOSSIL/FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
local-root: /Users/marilyn/Documents/FossilBook/
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-code: 4d9362c1fbe98e0dceed277c16f620ddc024a553
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout: fbb70c6c0b05e7b93e52d945242a2127c277e104 2010-05-05 10:12:12 UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
parent: 0a532b9cbe4394a37c07065424137dbb27b22e72 2010-05-04 13:51:13 UTC
\end_layout
\begin_layout LyX-Code
\series bold
\size scriptsize
tags: Syntax_edit
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Marilyn's update
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Whoops, when the update is done it failed with a
\series bold
bad object id: 0
\series default
which isn't too helpful.
So we try a status and see the tag Syntax_edit which isn't
\series bold
trunk
\series default
.
Looking back in Figure
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Leaf-Removed"
\end_inset
she can see that Syntax_trunk, the path she last updated is now a closed
leaf and the trunk has moved forward.
So she does an update to the trunk:
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
Pandora-2:FossilBook marilyn$
\series bold
fossil update trunk
\end_layout
\begin_layout LyX-Code
\size scriptsize
Autosync: http://Marilyn@192.168.1.200:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout LyX-Code
\size scriptsize
Bytes Cards Artifacts Deltas
\end_layout
\begin_layout LyX-Code
\size scriptsize
Send: 130 1 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Received: 230 5 0 0
\end_layout
\begin_layout LyX-Code
\size scriptsize
Total network traffic: 337 bytes sent, 439 bytes received
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_checkin.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_close_leaf.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_diff.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_fork.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_leaf_rmv.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_new_timeline.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_show_changes.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
ADD Images/Multiple_user/mul_update.epsf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE fossilbook.pdf
\end_layout
\begin_layout LyX-Code
\size scriptsize
UPDATE outline.txt
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Trunk Update
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
and she is ready to go again.
\end_layout
\begin_layout Section
Fossil Commands
\end_layout
\begin_layout Subsection
Introduction
\end_layout
\begin_layout Standard
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 a reference before use.
\end_layout
\begin_layout Standard
The most important command is
\series bold
help
\series default
.
You can always type
\series bold
fossil help
\series default
at the command line and it will list out all the commands it has.
Then typing f
\series bold
ossil help <command>
\series default
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
\end_layout
\begin_layout Subsection
Basic Commands
\end_layout
\begin_layout Subsubsection
help
\begin_inset Index
status open
\begin_layout Plain Layout
help
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is used to dump the current command set and version of Fossil.
It can also be used in the form
\series bold
fossil help <command>
\series default
to get further information on any command.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
filename Images/Commands/help1.epsf
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Help run
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Using it to get further information about a particular command
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help add
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil add FILE...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Make arrangements to add one or more files to the current checkout
\end_layout
\begin_layout LyX-Code
\size scriptsize
at the next commit.
\end_layout
\begin_layout LyX-Code
\size scriptsize
When adding files recursively, filenames that begin with "." are
\end_layout
\begin_layout LyX-Code
\size scriptsize
excluded by default.
To include such files, add the "--dotfiles"
\end_layout
\begin_layout LyX-Code
\size scriptsize
option to the command-line.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
Help detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
add
\begin_inset Index
status open
\begin_layout Plain Layout
add
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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 ???? all files already present in the repository so it is safe
to add all files at any time.
Only new files will be added.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil
\series default
\series bold
help add
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil add FILE...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Make arrangements to add one or more files to the current checkout
\end_layout
\begin_layout LyX-Code
\size scriptsize
at the next commit.
\end_layout
\begin_layout LyX-Code
\size scriptsize
When adding files recursively, filenames that begin with "." are
\end_layout
\begin_layout LyX-Code
\size scriptsize
excluded by default.
To include such files, add the "--dotfiles"
\end_layout
\begin_layout LyX-Code
\size scriptsize
option to the command-line.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
add detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Typing:
\end_layout
\begin_layout LyX-Code
fossil add .
\end_layout
\begin_layout Standard
will add all files in the current directory and subdirectories.
\end_layout
\begin_layout Standard
Note none of these files are put in the repository till a commit is done.
\end_layout
\begin_layout Subsubsection
rm
\begin_inset Index
status open
\begin_layout Plain Layout
rm
\end_layout
\end_inset
or del
\begin_inset Index
status open
\begin_layout Plain Layout
del
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help rm
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil rm FILE...
\end_layout
\begin_layout LyX-Code
\size scriptsize
or: fossil del FILE...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Remove one or more files from the tree.
\end_layout
\begin_layout LyX-Code
\size scriptsize
This command does not remove the files from disk.
It just marks the
\end_layout
\begin_layout LyX-Code
\size scriptsize
files as no longer being part of the project.
In other words, future
\end_layout
\begin_layout LyX-Code
\size scriptsize
changes to the named files will not be versioned.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
rm detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can delete groups of files by wild-carding 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:
\end_layout
\begin_layout LyX-Code
fossil rm com_*.c
\end_layout
\begin_layout Standard
By running a fossil status you can see what files will be deleted on the
next commit.
\end_layout
\begin_layout Subsubsection
rename
\begin_inset Index
status open
\begin_layout Plain Layout
rename
\end_layout
\end_inset
or mv
\begin_inset Index
status open
\begin_layout Plain Layout
mv
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil help rename
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil mv|rename OLDNAME NEWNAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
or: fossil mv|rename OLDNAME...
DIR
\end_layout
\begin_layout LyX-Code
\size scriptsize
Move or rename one or more files within the tree
\end_layout
\begin_layout LyX-Code
\size scriptsize
This command does not rename the files on disk.
All this command does is
\end_layout
\begin_layout LyX-Code
\size scriptsize
record the fact that filenames have changed so that appropriate notations
\end_layout
\begin_layout LyX-Code
\size scriptsize
can be made at the next commit/checkin.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
rename detail
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Just like add or rm you can wild card the names and rename groups of files.
And like them fossil status will show you the current state.
\end_layout
\begin_layout Subsubsection
status
\begin_inset Index
status open
\begin_layout Plain Layout
status
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
you repository is kept.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil status
\end_layout
\begin_layout LyX-Code
\size scriptsize
repository: /Users/jschimpf/Public/FOSSIL/FossilBook.fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
local-root: /Users/jschimpf/Public/FossilBook/
\end_layout
\begin_layout LyX-Code
\size scriptsize
server-code: 3e67da6d6212494456c69b1c5406a277d7e50430
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout: edd5b5fa4277604f365ec09238422c0aa7a28faf 2010-05-08 14:44:21
UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
parent: 3f019cbc730db0eb35f20941533a22635856b2b3 2010-05-08 11:15:19
UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
tags: trunk
\end_layout
\begin_layout LyX-Code
\size scriptsize
EDITED fossilbook.lyx
\end_layout
\begin_layout LyX-Code
\size scriptsize
EDITED outline.txt
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:status-run"
\end_inset
status run
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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, that I am working on two of them.
\end_layout
\begin_layout Subsubsection
changes
\begin_inset Index
status open
\begin_layout Plain Layout
changes
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This lists the changed files like status but does not show the other information
that status does.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help changes
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil changes
\end_layout
\begin_layout LyX-Code
\size scriptsize
Report on the edit status of all files in the current checkout.
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also the "status" and "extra" commands.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
changes details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
extra
\begin_inset Index
status open
\begin_layout Plain Layout
extra
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help extra
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil extras ?--dotfiles? ?--ignore GLOBPATTERN?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Print a list of all files in the source tree that are not part of
\end_layout
\begin_layout LyX-Code
\size scriptsize
the current checkout.
See also the "clean" command.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Files and subdirectories whose names begin with "." are normally
\end_layout
\begin_layout LyX-Code
\size scriptsize
ignored but can be included by adding the --dotfiles option.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
extra details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The --dotfiles option shows you any files starting with .
that are not under Fossil control.
This would be important if you need those files in your repository.
The last option --ignore allows you to ignore certain files you know don't
belong in the repository.
In my case there is a file called fossilbook.lyx~ that is a LyX backup file
that I do not want, it is temporary.
So I can say
\end_layout
\begin_layout LyX-Code
fossil extra --ignore *.lyx~
\end_layout
\begin_layout Standard
and only get:
\end_layout
\begin_layout LyX-Code
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil extra --ignore *.lyx~
\end_layout
\begin_layout LyX-Code
Images/Commands/help1.epsf
\end_layout
\begin_layout Standard
instead of:
\end_layout
\begin_layout LyX-Code
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil extra
\end_layout
\begin_layout LyX-Code
Images/Commands/help1.epsf
\end_layout
\begin_layout LyX-Code
fossilbook.lyx~
\end_layout
\begin_layout Subsubsection
revert
\begin_inset Index
status open
\begin_layout Plain Layout
revert
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help revert
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil revert ?-r REVISION? FILE ...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Revert to the current repository version of FILE, or to
\end_layout
\begin_layout LyX-Code
\size scriptsize
the version associated with baseline REVISION if the -r flag
\end_layout
\begin_layout LyX-Code
\size scriptsize
appears.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If a file is reverted accidently, it can be restored using
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "fossil undo" command.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
revert details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
With no parameters it will revert the file to the current revision, see
Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:status-run"
\end_inset
.
The -r option allows you to pick any revision from the time line.
\end_layout
\begin_layout Subsubsection
update
\begin_inset Index
status open
\begin_layout Plain Layout
update
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help update
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil update ?VERSION? ?FILES...?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Change the version of the current checkout to VERSION.
Any uncommitted
\end_layout
\begin_layout LyX-Code
\size scriptsize
changes are retained and applied to the new checkout.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The VERSION argument can be a specific version or tag or branch name.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the VERSION argument is omitted, then the leaf of the the subtree
\end_layout
\begin_layout LyX-Code
\size scriptsize
that begins at the current version is used, if there is only a single
\end_layout
\begin_layout LyX-Code
\size scriptsize
leaf.
VERSION can also be "current" to select the leaf of the current
\end_layout
\begin_layout LyX-Code
\size scriptsize
version or "latest" to select the most recent check-in.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
If one or more FILES are listed after the VERSION then only the
\end_layout
\begin_layout LyX-Code
\size scriptsize
named files are candidates to be updated.
If FILES is omitted, all
\end_layout
\begin_layout LyX-Code
\size scriptsize
files in the current checkout are subject to be updated.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The -n or --nochange option causes this command to do a "dry run".
It
\end_layout
\begin_layout LyX-Code
\size scriptsize
prints out what would have happened but does not actually make any
\end_layout
\begin_layout LyX-Code
\size scriptsize
changes to the current checkout or the repository.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The -v or --verbose option prints status information about unchanged
\end_layout
\begin_layout LyX-Code
\size scriptsize
files in addition to those file that actually do change.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
update details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Update has a number of options, first you can tie the update to a particular
version, if not picked then it just uses the latest.
Second it can work on a single files or many files at once.
That is you could say
\end_layout
\begin_layout LyX-Code
fossil update *.c
\end_layout
\begin_layout Standard
and it would update all C files.
\end_layout
\begin_layout Standard
Since this is a rather large set of changes it has a special
\begin_inset Quotes eld
\end_inset
dry run
\begin_inset Quotes erd
\end_inset
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.
\end_layout
\begin_layout Subsubsection
checkout
\begin_inset Index
status open
\begin_layout Plain Layout
checkout
\end_layout
\end_inset
or co
\begin_inset Index
status open
\begin_layout Plain Layout
co
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is similar to update.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil help checkout
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil checkout VERSION ?-f|--force? ?--keep?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Check out a version specified on the command-line.
This command
\end_layout
\begin_layout LyX-Code
\size scriptsize
will abort if there are edited files in the current checkout unless
\end_layout
\begin_layout LyX-Code
\size scriptsize
the --force option appears on the command-line.
The --keep option
\end_layout
\begin_layout LyX-Code
\size scriptsize
leaves files on disk unchanged, except the manifest and manifest.uuid
\end_layout
\begin_layout LyX-Code
\size scriptsize
files.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The --latest flag can be used in place of VERSION to checkout the
\end_layout
\begin_layout LyX-Code
\size scriptsize
latest version in the repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also the "update" command.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
checkout or co details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
undo
\begin_inset Index
status open
\begin_layout Plain Layout
undo
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is used to undo the last update, merge, or revert operation.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help undo
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil undo ?FILENAME...?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Undo the most recent update or merge or revert operation.
If FILENAME is
\end_layout
\begin_layout LyX-Code
\size scriptsize
specified then restore the content of the named file(s) but otherwise
\end_layout
\begin_layout LyX-Code
\size scriptsize
leave the update or merge or revert in effect.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
A single level of undo/redo is supported.
The undo/redo stack
\end_layout
\begin_layout LyX-Code
\size scriptsize
is cleared by the commit and checkout commands.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
undo details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
It acts on a single file or files if specified otherwise if no file given
it undoes all of the last changes.
\end_layout
\begin_layout Subsubsection
diff
\begin_inset Index
status collapsed
\begin_layout Plain Layout
diff
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help diff
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil diff|gdiff ?options? ?FILE?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Show the difference between the current version of FILE (as it
\end_layout
\begin_layout LyX-Code
\size scriptsize
exists on disk) and that same file as it was checked out.
Or
\end_layout
\begin_layout LyX-Code
\size scriptsize
if the FILE argument is omitted, show the unsaved changed currently
\end_layout
\begin_layout LyX-Code
\size scriptsize
in the working check-out.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the "--from VERSION" or "-r VERSION" option is used it specifies
\end_layout
\begin_layout LyX-Code
\size scriptsize
the source check-in for the diff operation.
If not specified, the
\end_layout
\begin_layout LyX-Code
\size scriptsize
source check-in is the base check-in for the current check-out.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the "--to VERSION" option appears, it specifies the check-in from
\end_layout
\begin_layout LyX-Code
\size scriptsize
which the second version of the file or files is taken.
If there is
\end_layout
\begin_layout LyX-Code
\size scriptsize
no "--to" option then the (possibly edited) files in the current check-out
\end_layout
\begin_layout LyX-Code
\size scriptsize
are used.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "-i" command-line option forces the use of the internal diff logic
\end_layout
\begin_layout LyX-Code
\size scriptsize
rather than any external diff program that might be configured using
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "setting" command.
If no external diff program is configured, then
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "-i" option is a no-op.
The "-i" option converts "gdiff" into "diff".
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
diff details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
gdiff
\begin_inset Index
status open
\begin_layout Plain Layout
gdiff
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help gdiff
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil diff|gdiff ?options? ?FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Show the difference between the current version of FILE (as it
\end_layout
\begin_layout LyX-Code
\size scriptsize
exists on disk) and that same file as it was checked out.
Or
\end_layout
\begin_layout LyX-Code
\size scriptsize
if the FILE argument is omitted, show the unsaved changed currently
\end_layout
\begin_layout LyX-Code
\size scriptsize
in the working check-out.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the "--from VERSION" or "-r VERSION" option is used it specifies
\end_layout
\begin_layout LyX-Code
\size scriptsize
the source check-in for the diff operation.
If not specified, the
\end_layout
\begin_layout LyX-Code
\size scriptsize
source check-in is the base check-in for the current check-out.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the "--to VERSION" option appears, it specifies the check-in from
\end_layout
\begin_layout LyX-Code
\size scriptsize
which the second version of the file or files is taken.
If there is
\end_layout
\begin_layout LyX-Code
\size scriptsize
no "--to" option then the (possibly edited) files in the current check-out
\end_layout
\begin_layout LyX-Code
\size scriptsize
are used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "-i" command-line option forces the use of the internal diff logic
\end_layout
\begin_layout LyX-Code
\size scriptsize
rather than any external diff program that might be configured using
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "setting" command.
If no external diff program is configured, then
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "-i" option is a no-op.
The "-i" option converts "gdiff" into "diff".
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
gdiff details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
ui
\begin_inset Index
status open
\begin_layout Plain Layout
ui
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The ui command is used to start the Fossil built in webserver.
The --port option is used to specify the port it uses, by default it uses
8080.
It should automatically start the systems 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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil help ui
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil server ?-P|--port TCPPORT? ?REPOSITORY?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Open a socket and begin listening and responding to HTTP requests on
\end_layout
\begin_layout LyX-Code
\size scriptsize
TCP port 8080, or on any other TCP port defined by the -P or
\end_layout
\begin_layout LyX-Code
\size scriptsize
--port option.
The optional argument is the name of the repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The repository argument may be omitted if the working directory is
\end_layout
\begin_layout LyX-Code
\size scriptsize
within an open checkout.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "ui" command automatically starts a web browser after initializing
\end_layout
\begin_layout LyX-Code
\size scriptsize
the web server.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
In the "server" command, the REPOSITORY can be a directory (aka folder)
\end_layout
\begin_layout LyX-Code
\size scriptsize
that contains one or more repositories with names ending in ".fossil".
\end_layout
\begin_layout LyX-Code
\size scriptsize
In that case, the first element of the URL is used to select among the
\end_layout
\begin_layout LyX-Code
\size scriptsize
various repositories.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
ui details
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
server
\begin_inset Index
status open
\begin_layout Plain Layout
server
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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 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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help server
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil server ?-P|--port TCPPORT? ?REPOSITORY?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Or: fossil ui ?-P|--port TCPPORT? ?REPOSITORY?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Open a socket and begin listening and responding to HTTP requests on
\end_layout
\begin_layout LyX-Code
\size scriptsize
TCP port 8080, or on any other TCP port defined by the -P or
\end_layout
\begin_layout LyX-Code
\size scriptsize
--port option.
The optional argument is the name of the repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The repository argument may be omitted if the working directory is
\end_layout
\begin_layout LyX-Code
\size scriptsize
within an open checkout.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "ui" command automatically starts a web browser after initializing
\end_layout
\begin_layout LyX-Code
\size scriptsize
the web server.
\end_layout
\begin_layout LyX-Code
\size scriptsize
In the "server" command, the REPOSITORY can be a directory (aka folder)
\end_layout
\begin_layout LyX-Code
\size scriptsize
that contains one or more repositories with names ending in ".fossil".
\end_layout
\begin_layout LyX-Code
\size scriptsize
In that case, the first element of the URL is used to select among the
\end_layout
\begin_layout LyX-Code
\size scriptsize
various repositories.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
server detail
\begin_inset CommandInset label
LatexCommand label
name "fig:server-detail"
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
commit
\begin_inset Index
status open
\begin_layout Plain Layout
commit
\end_layout
\end_inset
or ci
\begin_inset Index
status open
\begin_layout Plain Layout
ci
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil help commit
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil commit ?OPTIONS? ?FILE...?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Create a new version containing all of the changes in the current
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout.
You will be prompted to enter a check-in comment unless
\end_layout
\begin_layout LyX-Code
\size scriptsize
one of the "-m" or "-M" options are used to specify a comment.
\end_layout
\begin_layout LyX-Code
\size scriptsize
"-m" takes a single string for the commit message and "-M" requires
\end_layout
\begin_layout LyX-Code
\size scriptsize
a filename from which to read the commit message.
If neither "-m"
\end_layout
\begin_layout LyX-Code
\size scriptsize
nor "-M" are specified then the editor defined in the "editor"
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil option (see fossil help set) will be used, or from the
\end_layout
\begin_layout LyX-Code
\size scriptsize
"VISUAL" or "EDITOR" environment variables (in that order) if no
\end_layout
\begin_layout LyX-Code
\size scriptsize
editor is set.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
You will be prompted for your GPG pass phrase in order to sign the
\end_layout
\begin_layout LyX-Code
\size scriptsize
new manifest unless the "--nosign" options is used.
All files that
\end_layout
\begin_layout LyX-Code
\size scriptsize
have changed will be committed unless some subset of files is
\end_layout
\begin_layout LyX-Code
\size scriptsize
specified on the command line.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The --branch option followed by a branch name cases the new check-in
\end_layout
\begin_layout LyX-Code
\size scriptsize
to be placed in the named branch.
The --bgcolor option can be followed
\end_layout
\begin_layout LyX-Code
\size scriptsize
by a color name (ex: '#ffc0c0') to specify the background color of
\end_layout
\begin_layout LyX-Code
\size scriptsize
entries in the new branch when shown in the web timeline interface.
\end_layout
\begin_layout LyX-Code
\size scriptsize
A check-in is not permitted to fork unless the --force or -f
\end_layout
\begin_layout LyX-Code
\size scriptsize
option appears.
A check-in is not allowed against a closed check-in.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The --private option creates a private check-in that is never synced.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Children of private check-ins are automatically private.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Options:
\end_layout
\begin_layout LyX-Code
\size scriptsize
--comment|-m COMMENT-TEXT
\end_layout
\begin_layout LyX-Code
\size scriptsize
--branch NEW-BRANCH-NAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
--bgcolor COLOR
\end_layout
\begin_layout LyX-Code
\size scriptsize
--nosign
\end_layout
\begin_layout LyX-Code
\size scriptsize
--force|-f
\end_layout
\begin_layout LyX-Code
\size scriptsize
--private
\end_layout
\begin_layout LyX-Code
\size scriptsize
--message-file|-M COMMENT-FILE
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
commit details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsection
Maintenance commands
\end_layout
\begin_layout Standard
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
\series bold
fossil help
\series default
will probably be required before use.
Some of them like new or clone are only need when you start a repository.
Others like rebuild or reconstruct are only needed to fix or update a repositor
y.
\end_layout
\begin_layout Subsubsection
new
\begin_inset Index
status open
\begin_layout Plain Layout
new
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is used to create a new repository.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help new
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil new ?OPTIONS? FILENAME
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Create a repository for a new project in the file named FILENAME.
\end_layout
\begin_layout LyX-Code
\size scriptsize
This command is distinct from "clone".
The "clone" command makes
\end_layout
\begin_layout LyX-Code
\size scriptsize
a copy of an existing project.
This command starts a new project.
\end_layout
\begin_layout LyX-Code
\size scriptsize
By default, your current login name is used to create the default
\end_layout
\begin_layout LyX-Code
\size scriptsize
admin user.
This can be overridden using the -A|--admin-user
\end_layout
\begin_layout LyX-Code
\size scriptsize
parameter.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Options:
\end_layout
\begin_layout LyX-Code
\size scriptsize
--admin-user|-A USERNAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
--date-override DATETIME
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
new details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The file name specifies the new repository name.
The options provided allow you to specify the admin user name if you want
it to different than your current login and the starting date if you want
it different than now.
\end_layout
\begin_layout Subsubsection
clone
\begin_inset Index
status open
\begin_layout Plain Layout
clone
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Server-Setup"
\end_inset
), then this command will copy that repository to your machine.
Also it will make a link between your copy and the master, changes made
in your copy will be propagated to the master.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil help clone
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil clone ?OPTIONS? URL FILENAME
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Make a clone of a repository specified by URL in the local
\end_layout
\begin_layout LyX-Code
\size scriptsize
file named FILENAME.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
By default, your current login name is used to create the default
\end_layout
\begin_layout LyX-Code
\size scriptsize
admin user.
This can be overridden using the -A|--admin-user
\end_layout
\begin_layout LyX-Code
\size scriptsize
parameter.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Options:
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
--admin-user|-A USERNAME
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
clone details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Just like create you can specify the admin user for this clone with an option.
The URL for the master repository is of the form:
\end_layout
\begin_layout LyX-Code
http://<user>:<password>@domain
\end_layout
\begin_layout Standard
Where
\series bold
user
\series default
and
\series bold
password
\series default
are for a valid user of the selected repository.
It is best to check the path with a browser before doing the clone.
Make sure you can reach it, for example the repository for this book is:
\end_layout
\begin_layout LyX-Code
http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi
\end_layout
\begin_layout Standard
Putting that into a browser should get you the home page for this book.
(See Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Web-access-to"
\end_inset
).
After you have verified that then running the clone command should work.
\end_layout
\begin_layout Standard
Don't forget (as I always do) to put in the file name for the local repository,
(see FILENAME above)
\end_layout
\begin_layout Subsubsection
open
\begin_inset Index
status open
\begin_layout Plain Layout
open
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help open
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil open FILENAME ?VERSION? ?--keep?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
Open a connection to the local repository in FILENAME.
A checkout
\end_layout
\begin_layout LyX-Code
\size scriptsize
for the repository is created with its root at the working directory.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If VERSION is specified then that version is checked out.
Otherwise
\end_layout
\begin_layout LyX-Code
\size scriptsize
the latest version is checked out.
No files other than "manifest"
\end_layout
\begin_layout LyX-Code
\size scriptsize
and "manifest.uuid" are modified if the --keep option is present.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also the "close" command.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
open details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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 repositor
y in your work area.
In addition the files _FOSSIL_, manifiest and manifest.uuid will be created
by Fossil.
\end_layout
\begin_layout Subsubsection
close
\begin_inset Index
status open
\begin_layout Plain Layout
close
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is the opposite of open, in that it breaks the connection between this
working directory and the Fossil repository.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help close
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil close ?-f|--force?
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
The opposite of "open".
Close the current database connection.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Require a -f or --force flag if there are unsaved changed in the
\end_layout
\begin_layout LyX-Code
\size scriptsize
current check-out.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
close details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
version
\begin_inset Index
status open
\begin_layout Plain Layout
version
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is used to show the current version of fossil.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help version
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil version
\end_layout
\begin_layout LyX-Code
\size scriptsize
Print the source code version number for the fossil executable.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil version
\end_layout
\begin_layout LyX-Code
\size scriptsize
This is fossil version [c56af61e5e] 2010-04-22 15:48:25 UTC
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
version details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Subsubsection
rebuild
\begin_inset Index
status open
\begin_layout Plain Layout
rebuild
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help rebuild
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil rebuild ?REPOSITORY?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Reconstruct the named repository database from the core
\end_layout
\begin_layout LyX-Code
\size scriptsize
records.
Run this command after updating the fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
executable in a way that changes the database schema.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
rebuild details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
all
\begin_inset Index
status open
\begin_layout Plain Layout
all
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is actually a modifier and when used before certain commands
will run them on all the repositories.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help all
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil all (list|ls|pull|push|rebuild|sync)
\end_layout
\begin_layout LyX-Code
\size scriptsize
The ~/.fossil file records the location of all repositories for a
\end_layout
\begin_layout LyX-Code
\size scriptsize
user.
This command performs certain operations on all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
that can be useful before or after a period of disconnection operation.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Available operations are:
\end_layout
\begin_layout LyX-Code
\size scriptsize
list Display the location of all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
ls An alias for "list"
\end_layout
\begin_layout LyX-Code
\size scriptsize
pull Run a "pull" operation on all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
push Run a "push" on all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
rebuild Rebuild on all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
sync Run a "sync" on all repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
Repositories are automatically added to the set of known repositories
\end_layout
\begin_layout LyX-Code
\size scriptsize
when one of the following commands against the repository: clone, info,
\end_layout
\begin_layout LyX-Code
\size scriptsize
pull, push, or sync
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
all details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
push
\begin_inset Index
status open
\begin_layout Plain Layout
push
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command will move current changes from the working directory to the
repository.
Either to the tip or to a specified branch.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help push
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil push ?URL? ?options?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Push changes in the local repository over into a remote repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Use the "-R REPO" or "--repository REPO" command-line options
\end_layout
\begin_layout LyX-Code
\size scriptsize
to specify an alternative repository file.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the URL is not specified, then the URL from the most recent
\end_layout
\begin_layout LyX-Code
\size scriptsize
clone, push, pull, remote-url, or sync command is used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The URL specified normally becomes the new "remote-url" used for
\end_layout
\begin_layout LyX-Code
\size scriptsize
subsequent push, pull, and sync operations.
However, the "--once"
\end_layout
\begin_layout LyX-Code
\size scriptsize
command-line option makes the URL a one-time-use URL that is not
\end_layout
\begin_layout LyX-Code
\size scriptsize
saved.
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also: clone, pull, sync, remote-url
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
push details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
pull
\begin_inset Index
status open
\begin_layout Plain Layout
pull
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command will get changes from either the tip or a specified location
in the repository and apply them to the current directory.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help pull
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil pull ?URL? ?options?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Pull changes from a remote repository into the local repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Use the "-R REPO" or "--repository REPO" command-line options
\end_layout
\begin_layout LyX-Code
\size scriptsize
to specify an alternative repository file.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the URL is not specified, then the URL from the most recent
\end_layout
\begin_layout LyX-Code
\size scriptsize
clone, push, pull, remote-url, or sync command is used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The URL specified normally becomes the new "remote-url" used for
\end_layout
\begin_layout LyX-Code
\size scriptsize
subsequent push, pull, and sync operations.
However, the "--once"
\end_layout
\begin_layout LyX-Code
\size scriptsize
command-line option makes the URL a one-time-use URL that is not
\end_layout
\begin_layout LyX-Code
\size scriptsize
saved.
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also: clone, push, sync, remote-url
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
pull details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
sync
\begin_inset Index
status open
\begin_layout Plain Layout
sync
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help sync
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil sync ?URL? ?options?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Synchronize the local repository with a remote repository.
This is
\end_layout
\begin_layout LyX-Code
\size scriptsize
the equivalent of running both "push" and "pull" at the same time.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Use the "-R REPO" or "--repository REPO" command-line options
\end_layout
\begin_layout LyX-Code
\size scriptsize
to specify an alternative repository file.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If a user-id and password are required, specify them as follows:
\end_layout
\begin_layout LyX-Code
\size scriptsize
http://userid:password@www.domain.com:1234/path
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the URL is not specified, then the URL from the most recent successful
\end_layout
\begin_layout LyX-Code
\size scriptsize
clone, push, pull, remote-url, or sync command is used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The URL specified normally becomes the new "remote-url" used for
\end_layout
\begin_layout LyX-Code
\size scriptsize
subsequent push, pull, and sync operations.
However, the "--once"
\end_layout
\begin_layout LyX-Code
\size scriptsize
command-line option makes the URL a one-time-use URL that is not
\end_layout
\begin_layout LyX-Code
\size scriptsize
saved.
\end_layout
\begin_layout LyX-Code
\size scriptsize
See also: clone, push, pull, remote-url
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
sync details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
clean
\begin_inset Index
status open
\begin_layout Plain Layout
clean
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This call can be used to remove all the
\begin_inset Quotes eld
\end_inset
extra
\begin_inset Quotes erd
\end_inset
files in a source tree.
This is useful if you wish to tidy up a source tree or to do a clean build.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help clean
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil clean ?--force? ?--dotfiles?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Delete all "extra" files in the source tree.
"Extra" files are
\end_layout
\begin_layout LyX-Code
\size scriptsize
files that are not officially part of the checkout.
See also
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "extra" command.
This operation cannot be undone.
\end_layout
\begin_layout LyX-Code
\size scriptsize
You will be prompted before removing each file.
If you are
\end_layout
\begin_layout LyX-Code
\size scriptsize
sure you wish to remove all "extra" files you can specify the
\end_layout
\begin_layout LyX-Code
\size scriptsize
optional --force flag and no prompts will be issued.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Files and subdirectories whose names begin with "." are
\end_layout
\begin_layout LyX-Code
\size scriptsize
normally ignored.
They are included if the "--dotfiles" option
\end_layout
\begin_layout LyX-Code
\size scriptsize
is used.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
clean details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
branch
\begin_inset Index
status open
\begin_layout Plain Layout
branch
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is used if you want to create or list branches in a repository.
Previously we discussed forks ( See Section
\begin_inset CommandInset ref
LatexCommand vref
reference "sub:Complications"
\end_inset
) 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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help branch
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil branch SUBCOMMAND ...
?-R|--repository FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Run various subcommands on the branches of the open repository or
\end_layout
\begin_layout LyX-Code
\size scriptsize
of the repository identified by the -R or --repository option.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil branch new BRANCH-NAME BASIS ?-bgcolor COLOR?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Create a new branch BRANCH-NAME off of check-in BASIS.
\end_layout
\begin_layout LyX-Code
\size scriptsize
You can optionally give the branch a default color.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil branch list
\end_layout
\begin_layout LyX-Code
\size scriptsize
List all branches
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
branch details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
merge
\begin_inset Index
status open
\begin_layout Plain Layout
merge
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command does the opposite of branch, it brings two branches together.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help merge
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil merge [--cherrypick] [--backout] VERSION
\end_layout
\begin_layout LyX-Code
\size scriptsize
The argument is a version that should be merged into the current
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout.
All changes from VERSION back to the nearest common
\end_layout
\begin_layout LyX-Code
\size scriptsize
ancestor are merged.
Except, if either of the --cherrypick or
\end_layout
\begin_layout LyX-Code
\size scriptsize
--backout options are used only the changes associated with the
\end_layout
\begin_layout LyX-Code
\size scriptsize
single check-in VERSION are merged.
The --backout option causes
\end_layout
\begin_layout LyX-Code
\size scriptsize
the changes associated with VERSION to be removed from the current
\end_layout
\begin_layout LyX-Code
\size scriptsize
checkout rather than added.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Only file content is merged.
The result continues to use the
\end_layout
\begin_layout LyX-Code
\size scriptsize
file and directory names from the current checkout even if those
\end_layout
\begin_layout LyX-Code
\size scriptsize
names might have been changed in the branch being merged in.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Other options:
\end_layout
\begin_layout LyX-Code
\size scriptsize
--detail Show additional details of the merge
\end_layout
\begin_layout LyX-Code
\size scriptsize
--binary GLOBPATTERN Treat files that match GLOBPATTERN as binary
\end_layout
\begin_layout LyX-Code
\size scriptsize
and do not try to merge parallel changes.
This
\end_layout
\begin_layout LyX-Code
\size scriptsize
option overrides the "binary-glob" setting.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
merge details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
tag
\begin_inset Index
status open
\begin_layout Plain Layout
tag
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command can be used to control
\begin_inset Quotes eld
\end_inset
tags
\begin_inset Quotes erd
\end_inset
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Remove-Leaf"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help tag
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil tag SUBCOMMAND ...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Run various subcommands to control tags and properties
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil tag add ?--raw? ?--propagate? TAGNAME CHECK-IN ?VALUE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Add a new tag or property to CHECK-IN.
The tag will
\end_layout
\begin_layout LyX-Code
\size scriptsize
be usable instead of a CHECK-IN in commands such as
\end_layout
\begin_layout LyX-Code
\size scriptsize
update and merge.
If the --propagate flag is present,
\end_layout
\begin_layout LyX-Code
\size scriptsize
the tag value propagates to all descendants of CHECK-IN
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil tag cancel ?--raw? TAGNAME CHECK-IN
\end_layout
\begin_layout LyX-Code
\size scriptsize
Remove the tag TAGNAME from CHECK-IN, and also remove
\end_layout
\begin_layout LyX-Code
\size scriptsize
the propagation of the tag to any descendants.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil tag find ?--raw? TAGNAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
List all check-ins that use TAGNAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil tag list ?--raw? ?CHECK-IN?
\end_layout
\begin_layout LyX-Code
\size scriptsize
List all tags, or if CHECK-IN is supplied, list
\end_layout
\begin_layout LyX-Code
\size scriptsize
all tags and their values for CHECK-IN.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The option --raw allows the manipulation of all types of tags
\end_layout
\begin_layout LyX-Code
\size scriptsize
used for various internal purposes in fossil.
It also shows
\end_layout
\begin_layout LyX-Code
\size scriptsize
"cancel" tags for the "find" and "list" subcommands.
You should
\end_layout
\begin_layout LyX-Code
\size scriptsize
not use this option to make changes unless you are sure what
\end_layout
\begin_layout LyX-Code
\size scriptsize
you are doing.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If you need to use a tagname that might be confused with
\end_layout
\begin_layout LyX-Code
\size scriptsize
a hexadecimal baseline or artifact ID, you can explicitly
\end_layout
\begin_layout LyX-Code
\size scriptsize
disambiguate it by prefixing it with "tag:".
For instance:
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil update decaf
\end_layout
\begin_layout LyX-Code
\size scriptsize
will be taken as an artifact or baseline ID and fossil will
\end_layout
\begin_layout LyX-Code
\size scriptsize
probably complain that no such revision was found.
However
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil update tag:decaf
\end_layout
\begin_layout LyX-Code
\size scriptsize
will assume that "decaf" is a tag/branch name.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
tag details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
settings
\begin_inset Index
status open
\begin_layout Plain Layout
settings
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command is used to set or unset a number of properties for fossil.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help settings
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: settings
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: unset
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil setting ?PROPERTY? ?VALUE? ?-global?
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil unset PROPERTY ?-global?
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "setting" command with no arguments lists all properties and their
\end_layout
\begin_layout LyX-Code
\size scriptsize
values.
With just a property name it shows the value of that property.
\end_layout
\begin_layout LyX-Code
\size scriptsize
With a value argument it changes the property for the current repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "unset" command clears a property setting.
\end_layout
\begin_layout LyX-Code
\size scriptsize
auto-captcha If enabled, the Login page will provide a button
\end_layout
\begin_layout LyX-Code
\size scriptsize
which uses JavaScript to fill out the captcha for
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "anonymous" user.
(Most bots cannot use JavaScript.)
\end_layout
\begin_layout LyX-Code
\size scriptsize
autosync If enabled, automatically pull prior to commit
\end_layout
\begin_layout LyX-Code
\size scriptsize
or update and automatically push after commit or
\end_layout
\begin_layout LyX-Code
\size scriptsize
tag or branch creation.
If the the value is "pullonly"
\end_layout
\begin_layout LyX-Code
\size scriptsize
then only pull operations occur automatically.
\end_layout
\begin_layout LyX-Code
\size scriptsize
binary-glob The VALUE is a comma-separated list of GLOB patterns
\end_layout
\begin_layout LyX-Code
\size scriptsize
that should be treated as binary files for merging
\end_layout
\begin_layout LyX-Code
\size scriptsize
purposes.
Example: *.xml
\end_layout
\begin_layout LyX-Code
\size scriptsize
clearsign When enabled, fossil will attempt to sign all commits
\end_layout
\begin_layout LyX-Code
\size scriptsize
with gpg.
When disabled (the default), commits will
\end_layout
\begin_layout LyX-Code
\size scriptsize
be unsigned.
\end_layout
\begin_layout LyX-Code
\size scriptsize
diff-command External command to run when performing a diff.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If undefined, the internal text diff will be used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
dont-push Prevent this repository from pushing from client to
\end_layout
\begin_layout LyX-Code
\size scriptsize
server.
Useful when setting up a private branch.
\end_layout
\begin_layout LyX-Code
\size scriptsize
editor Text editor command used for check-in comments.
\end_layout
\begin_layout LyX-Code
\size scriptsize
gdiff-command External command to run when performing a graphical
\end_layout
\begin_layout LyX-Code
\size scriptsize
diff.
If undefined, text diff will be used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
http-port The TCP/IP port number to use by the "server"
\end_layout
\begin_layout LyX-Code
\size scriptsize
and "ui" commands.
Default: 8080
\end_layout
\begin_layout LyX-Code
\size scriptsize
ignore-glob The VALUE is a comma-separated list of GLOB patterns
\end_layout
\begin_layout LyX-Code
\size scriptsize
specifying files that the "extra" command will ignore.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Example: *.o,*.obj,*.exe
\end_layout
\begin_layout LyX-Code
\size scriptsize
localauth If enabled, require that HTTP connections from
\end_layout
\begin_layout LyX-Code
\size scriptsize
127.0.0.1 be authenticated by password.
If
\end_layout
\begin_layout LyX-Code
\size scriptsize
false, all HTTP requests from localhost have
\end_layout
\begin_layout LyX-Code
\size scriptsize
unrestricted access to the repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
mtime-changes Use file modification times (mtimes) to detect when
\end_layout
\begin_layout LyX-Code
\size scriptsize
files have been modified.
(Default "on".)
\end_layout
\begin_layout LyX-Code
\size scriptsize
pgp-command Command used to clear-sign manifests at check-in.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The default is "gpg --clearsign -o ".
\end_layout
\begin_layout LyX-Code
\size scriptsize
proxy URL of the HTTP proxy.
If undefined or "off" then
\end_layout
\begin_layout LyX-Code
\size scriptsize
the "http_proxy" environment variable is consulted.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If the http_proxy environment variable is undefined
\end_layout
\begin_layout LyX-Code
\size scriptsize
then a direct HTTP connection is used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
web-browser A shell command used to launch your preferred
\end_layout
\begin_layout LyX-Code
\size scriptsize
web browser when given a URL as an argument.
\end_layout
\begin_layout LyX-Code
\size scriptsize
Defaults to "start" on windows, "open" on Mac,
\end_layout
\begin_layout LyX-Code
\size scriptsize
and "firefox" on Unix.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
settings details
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Miscellaneous
\end_layout
\begin_layout Standard
These are commands that don't seem to fit in any category but are useful.
\end_layout
\begin_layout Subsubsection
zip
\begin_inset Index
status open
\begin_layout Plain Layout
zip
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can do what this command does from the web based user interface.
In Figure
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Timeline-Detail"
\end_inset
you can download a ZIP archive of the particular version of the files.
This command lets you do it from the command line.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help zip
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil zip VERSION OUTPUTFILE [--name DIRECTORYNAME]
\end_layout
\begin_layout LyX-Code
\size scriptsize
Generate a ZIP archive for a specified version.
If the --name option is
\end_layout
\begin_layout LyX-Code
\size scriptsize
used, it argument becomes the name of the top-level directory in the
\end_layout
\begin_layout LyX-Code
\size scriptsize
resulting ZIP archive.
If --name is omitted, the top-level directory
\end_layout
\begin_layout LyX-Code
\size scriptsize
named is derived from the project name, the check-in date and time, and
\end_layout
\begin_layout LyX-Code
\size scriptsize
the artifact ID of the check-in.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
zip detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
user
\begin_inset Index
status open
\begin_layout Plain Layout
user
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:New-Editor-user"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help user
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil user SUBCOMMAND ...
?-R|--repository FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Run various subcommands on users of the open repository or of
\end_layout
\begin_layout LyX-Code
\size scriptsize
the repository identified by the -R or --repository option.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil user capabilities USERNAME ?STRING?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Query or set the capabilities for user USERNAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil user default ?USERNAME?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Query or set the default user.
The default user is the
\end_layout
\begin_layout LyX-Code
\size scriptsize
user for command-line interaction.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil user list
\end_layout
\begin_layout LyX-Code
\size scriptsize
List all users known to the repository
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil user new ?USERNAME? ?CONTACT-INFO? ?PASSWORD?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Create a new user in the repository.
Users can never be
\end_layout
\begin_layout LyX-Code
\size scriptsize
deleted.
They can be denied all access but they must continue
\end_layout
\begin_layout LyX-Code
\size scriptsize
to exist in the database.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil user password USERNAME ?PASSWORD?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Change the web access password for a user.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
user detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
finfo
\begin_inset Index
status open
\begin_layout Plain Layout
finfo
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help finfo
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil finfo FILENAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
Print the change history for a single file.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The "--limit N" and "--offset P" options limits the output to the first
\end_layout
\begin_layout LyX-Code
\size scriptsize
N changes after skipping P changes.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
finfo detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
An example would be to run it on the outline.txt file in our book directory:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil
\series bold
finfo outline.txt
\end_layout
\begin_layout LyX-Code
\size scriptsize
History of outline.txt
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-17 [0272dc0169] Finished maintenance commands (user: jim, artifact:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[25b6e38e97])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-12 [5e5c0f7d55] End of day commit (user: jim, artifact: [d1a1d31fbd])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-10 [e924ca3525] End of day update (user: jim, artifact: [7cd19079a1])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-09 [0abb95b046] Intermediate commit, not done with basic commands
\end_layout
\begin_layout LyX-Code
\size scriptsize
(user: jim, artifact: [6f7bcd48b9])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-07 [6921e453cd] Update outline & book corrections (user: jim,
\end_layout
\begin_layout LyX-Code
\size scriptsize
artifact: [4eff85c793])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-03 [158492516c] Moved to clone repository (user: jim, artifact:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[23b729cb66])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-05-03 [1a403c87fc] Update before moving to server (user: jim, artifact:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[706a9d394d])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-04-30 [fa5b9247bd] Working on chapter 1 (user: jim, artifact:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[7bb188f0c6])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-04-29 [51be6423a3] Update outline (user: jim, artifact: [7cd39dfa06])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-04-27 [39bc728527] [1665c78d94] Ticket Use (user: jim, artifact:
\end_layout
\begin_layout LyX-Code
\size scriptsize
[1f82aaf41c])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-04-26 [497b93858f] Update to catch changes in outline (user: jim,
\end_layout
\begin_layout LyX-Code
\size scriptsize
artifact: [b870231e48])
\end_layout
\begin_layout LyX-Code
\size scriptsize
2010-04-25 [8fa0708186] Initial Commit (user: jim, artifact: [34a460a468])
\end_layout
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\end_layout
\begin_layout Subsubsection
timeline
\begin_inset Index
status open
\begin_layout Plain Layout
timeline
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help timeline
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil timeline ?WHEN? ?BASELINE|DATETIME? ?-n N? ?-t TYPE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Print a summary of activity going backwards in date and time
\end_layout
\begin_layout LyX-Code
\size scriptsize
specified or from the current date and time if no arguments
\end_layout
\begin_layout LyX-Code
\size scriptsize
are given.
Show as many as N (default 20) check-ins.
The
\end_layout
\begin_layout LyX-Code
\size scriptsize
WHEN argument can be any unique abbreviation of one of these
\end_layout
\begin_layout LyX-Code
\size scriptsize
keywords:
\end_layout
\begin_layout LyX-Code
\size scriptsize
before
\end_layout
\begin_layout LyX-Code
\size scriptsize
after
\end_layout
\begin_layout LyX-Code
\size scriptsize
descendants | children
\end_layout
\begin_layout LyX-Code
\size scriptsize
ancestors | parents
\end_layout
\begin_layout LyX-Code
\size scriptsize
The BASELINE can be any unique prefix of 4 characters or more.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The DATETIME should be in the ISO8601 format.
For
\end_layout
\begin_layout LyX-Code
\size scriptsize
examples: "2007-08-18 07:21:21".
You can also say "current"
\end_layout
\begin_layout LyX-Code
\size scriptsize
for the current version or "now" for the current time.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The optional TYPE argument may any types supported by the /timeline
\end_layout
\begin_layout LyX-Code
\size scriptsize
page.
For example:
\end_layout
\begin_layout LyX-Code
\size scriptsize
w = wiki commits only
\end_layout
\begin_layout LyX-Code
\size scriptsize
ci = file commits only
\end_layout
\begin_layout LyX-Code
\size scriptsize
t = tickets only
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
timeline detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
wiki
\begin_inset Index
status open
\begin_layout Plain Layout
wiki
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command allow 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 a number of computer generated pages to the Wiki.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help wiki
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil wiki (export|create|commit|list) WikiName
\end_layout
\begin_layout LyX-Code
\size scriptsize
Run various subcommands to work with wiki entries.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki export PAGENAME ?FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Sends the latest version of the PAGENAME wiki
\end_layout
\begin_layout LyX-Code
\size scriptsize
entry to the given file or standard output.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki commit PAGENAME ?FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Commit changes to a wiki page from FILE or from standard
\end_layout
\begin_layout LyX-Code
\size scriptsize
input.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki create PAGENAME ?FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Create a new wiki page with initial content taken from
\end_layout
\begin_layout LyX-Code
\size scriptsize
FILE or from standard input.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki list
\end_layout
\begin_layout LyX-Code
\size scriptsize
Lists all wiki entries, one per line, ordered
\end_layout
\begin_layout LyX-Code
\size scriptsize
case-insentively by name.
\end_layout
\begin_layout LyX-Code
\size scriptsize
TODOs:
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki export ?-u ARTIFACT? WikiName ?FILE?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Outputs the selected version of WikiName.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki delete ?-m MESSAGE? WikiName
\end_layout
\begin_layout LyX-Code
\size scriptsize
The same as deleting a file entry, but i don't know if fossil
\end_layout
\begin_layout LyX-Code
\size scriptsize
supports a commit message for Wiki entries.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki ?-u? ?-d? ?-s=[|]? list
\end_layout
\begin_layout LyX-Code
\size scriptsize
Lists the artifact ID and/or Date of last change along with
\end_layout
\begin_layout LyX-Code
\size scriptsize
each entry name, delimited by the -s char.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil wiki diff ?ARTIFACT? ?-f infile[=stdin]? EntryName
\end_layout
\begin_layout LyX-Code
\size scriptsize
Diffs the local copy of a page with a given version (defaulting
\end_layout
\begin_layout LyX-Code
\size scriptsize
to the head version).
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
wiki detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Advanced
\end_layout
\begin_layout Standard
These are commands that you will rarely have to use and do 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.
\end_layout
\begin_layout Subsubsection
scrub
\begin_inset Index
status open
\begin_layout Plain Layout
scrub
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help scrub
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: scrub
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil scrub [--verily] [--force] [REPOSITORY]
\end_layout
\begin_layout LyX-Code
\size scriptsize
The command removes sensitive information (such as passwords) from a
\end_layout
\begin_layout LyX-Code
\size scriptsize
repository so that the repository can be sent to an untrusted reader.
\end_layout
\begin_layout LyX-Code
\size scriptsize
By default, only passwords are removed.
However, if the --verily option
\end_layout
\begin_layout LyX-Code
\size scriptsize
is added, then private branches, concealed email addresses, IP
\end_layout
\begin_layout LyX-Code
\size scriptsize
addresses of correspondents, and similar privacy-sensitive fields
\end_layout
\begin_layout LyX-Code
\size scriptsize
are also purged.
\end_layout
\begin_layout LyX-Code
\size scriptsize
This command permanently deletes the scrubbed information.
The effects
\end_layout
\begin_layout LyX-Code
\size scriptsize
of this command are irreversible.
Use with caution.
\end_layout
\begin_layout LyX-Code
\size scriptsize
The user is prompted to confirm the scrub unless the --force option
\end_layout
\begin_layout LyX-Code
\size scriptsize
is used.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
scrub detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
search
\begin_inset Index
status open
\begin_layout Plain Layout
search
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is used to search the timeline entries for a pattern.
This can also be done in your browser on the timeline page.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help search
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: search
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil search pattern...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Search for timeline entries matching the pattern.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
search detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
sha1sum
\begin_inset Index
status open
\begin_layout Plain Layout
sha1sum
\end_layout
\end_inset
\end_layout
\begin_layout Standard
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.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help sha1sum
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: sha1sum
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil sha1sum FILE...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Compute an SHA1 checksum of all files named on the command-line.
\end_layout
\begin_layout LyX-Code
\size scriptsize
If an file is named "-" then take its content from standard input.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
sha1sum detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
rstats
\begin_inset Index
status open
\begin_layout Plain Layout
rstats
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help rstats
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil rstats
\end_layout
\begin_layout LyX-Code
\size scriptsize
Deliver a report of the repository statistics for the
\end_layout
\begin_layout LyX-Code
\size scriptsize
current checkout.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
rstats detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
For example, running it on the Fossil Book checkout:
\end_layout
\begin_layout LyX-Code
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil rstats
\end_layout
\begin_layout LyX-Code
Number of Artifacts: 137
\end_layout
\begin_layout LyX-Code
59 full text + 78 delta blobs
\end_layout
\begin_layout LyX-Code
278961 bytes average, 38217738 bytes total
\end_layout
\begin_layout LyX-Code
Number Of Checkins: 26
\end_layout
\begin_layout LyX-Code
Number Of Files: 37
\end_layout
\begin_layout LyX-Code
Number Of Wiki Pages: 2
\end_layout
\begin_layout LyX-Code
Number Of Tickets: 6
\end_layout
\begin_layout LyX-Code
Duration Of Project: 23 days
\end_layout
\begin_layout Subsubsection
configuration
\begin_inset Index
status open
\begin_layout Plain Layout
configuration
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This command allows you to save or load a custom configuration of Fossil.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim% fossil
\series bold
help configuration
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil configure METHOD ...
\end_layout
\begin_layout LyX-Code
\size scriptsize
Where METHOD is one of: export import merge pull push reset.
All methods
\end_layout
\begin_layout LyX-Code
\size scriptsize
accept the -R or --repository option to specific a repository.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration export AREA FILENAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
Write to FILENAME exported configuration information for AREA.
\end_layout
\begin_layout LyX-Code
\size scriptsize
AREA can be one of: all ticket skin project
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration import FILENAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
Read a configuration from FILENAME, overwriting the current
\end_layout
\begin_layout LyX-Code
\size scriptsize
configuration.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration merge FILENAME
\end_layout
\begin_layout LyX-Code
\size scriptsize
Read a configuration from FILENAME and merge its values into
\end_layout
\begin_layout LyX-Code
\size scriptsize
the current configuration.
Existing values take priority over
\end_layout
\begin_layout LyX-Code
\size scriptsize
values read from FILENAME.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration pull AREA ?URL?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Pull and install the configuration from a different server
\end_layout
\begin_layout LyX-Code
\size scriptsize
identified by URL.
If no URL is specified, then the default
\end_layout
\begin_layout LyX-Code
\size scriptsize
server is used.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration push AREA ?URL?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Push the local configuration into the remote server identified
\end_layout
\begin_layout LyX-Code
\size scriptsize
by URL.
Admin privilege is required on the remote server for
\end_layout
\begin_layout LyX-Code
\size scriptsize
this to work.
\end_layout
\begin_layout LyX-Code
\size scriptsize
fossil configuration reset AREA
\end_layout
\begin_layout LyX-Code
\size scriptsize
Restore the configuration to the default.
AREA as above.
\end_layout
\begin_layout LyX-Code
\size scriptsize
WARNING: Do not import, merge, or pull configurations from an untrusted
\end_layout
\begin_layout LyX-Code
\size scriptsize
source.
The inbound configuration is not checked for safety and can
\end_layout
\begin_layout LyX-Code
\size scriptsize
introduce security vulnerabilities.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
configuration detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
deconstruct
\begin_inset Index
status open
\begin_layout Plain Layout
deconstruct
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is used to disassemble a repository into the atomic artifacts.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help deconstruct
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: deconstruct
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage fossil deconstruct ?-R|--repository REPOSITORY? DESTINATION
\end_layout
\begin_layout LyX-Code
\size scriptsize
Populates the indicated DESTINATION directory with copies of all
\end_layout
\begin_layout LyX-Code
\size scriptsize
artifacts contained within the repository.
Artifacts are named AA/bbbbb
\end_layout
\begin_layout LyX-Code
\size scriptsize
where AA is the first 2 characters of the artifact ID and bbbbb is the
\end_layout
\begin_layout LyX-Code
\size scriptsize
remaining 38 characters.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
deconstruct detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
reconstruct
\begin_inset Index
status open
\begin_layout Plain Layout
reconstruct
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This takes the artifacts generated by the deconstruct command and turns
them into a repository.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help reconstruct
\end_layout
\begin_layout LyX-Code
\size scriptsize
COMMAND: reconstruct
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage fossil reconstruct REPOSITORY ORIGIN
\end_layout
\begin_layout LyX-Code
\size scriptsize
Creates the REPOSITORY and populates it with the artifacts in the
\end_layout
\begin_layout LyX-Code
\size scriptsize
indicated ORIGIN directory.
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
reconstruct detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
descendants
\begin_inset Index
status open
\begin_layout Plain Layout
descendants
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This is used to find where the checked out files are in the time line.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout LyX-Code
\size scriptsize
[Pandora-2:jschimpf/Public/FossilBook] jim%
\series bold
fossil help descendants
\end_layout
\begin_layout LyX-Code
\size scriptsize
Usage: fossil descendants ?BASELINE-ID?
\end_layout
\begin_layout LyX-Code
\size scriptsize
Find all leaf descendants of the baseline specified or if the argument
\end_layout
\begin_layout LyX-Code
\size scriptsize
is omitted, of the baseline currently checked out.
\end_layout
\begin_layout LyX-Code
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
descendants detail
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Section
What's next ?
\end_layout
\begin_layout Standard
This book so far has covered how to use the many features of Fossil and
has I hoped interested you in using it.
The question is what's next now comes up.
First go to the Fossil website
\begin_inset Flex URL
status open
\begin_layout Plain Layout
http://www.fossil-scm.org/
\end_layout
\end_inset
.
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.
\end_layout
\begin_layout Standard
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 are interesting to read the pros and cons of suggested changes.
\end_layout
\begin_layout Standard
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
\series bold
rebuild
\series default
of your current repositories.
The developers have been very careful to preserve the basic structure so
it is easy and safe to switch versions.
\end_layout
\begin_layout Standard
Finally if you wish to contribute to the project there are many things to
do (See the To Do List in the Wiki).
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset index_print
LatexCommand printindex
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset bibtex
LatexCommand bibtex
bibfiles "Research/fossilbib"
options "plain"
\end_inset
\end_layout
\end_body
\end_document