# Fossil commands

## Introduction

This section presents and explains the various Fossil command line commands. There is a section for each command Fossil knows. The most important command is `help`. You can always type `fossil help` at the command line and it will list out (nearly!) all the commands it has. Then typing `fossil help <command>` will print out the detailed information on that command. You always have that as your reference.

This chapter of the book will supplement the built in help text with some more explanation and with some examples of how the commands are used. All of the commands are placed in the index for easy searching.

There are a few terms that are used again and again in the description of the commands, so let us briefly look at what they mean, just to be sure:

* repository = the database that Fossil manages to keep track of you code
* current check-out = the working files which you edit to change your code
* a (new) version = a set of files in the repository reflecting a certain point in time (typically a specific state of your code)

These are the basic command that you likely will use most:

* add - Make arrangements to add one or more files or directories to the current check-out at the next commit
* changes - Report the change status of files in the current check-out
* checkout - Changes the current check-out to a specific version
* commit - Create a new version containing all of the changes in the current check-out
* delete - Remove one or more files or directories from the repository
* diff - Show the difference between the current version of file(s) as they exist on disk and that same file as it was checked out
* extras - List all files in the source tree that are not part of the current check-out
* gdiff - see `diff`
* help - Display information on how to use a command, webpage, or setting
* rename - Move or rename one or more files or directories within the repository
* revert - Change a file in the check-out to the current or a baseline repository version
* server - Serve a repository via a web page
* status - Report the change status of files in the current check-out
* ui - Start the web frontend of Fossil on the local computer
* undo - Reverts the changes caused by some (not all) previous command
* update - Change the version of the current check-out to a specific version

Then there are typical maintenance commands:

* all
* branch
* clean
* clone
* close
* info
* merge
* new
* open
* publish
* pull
* push
* rebuild
* settings
* sync
* tag
* version

Other commands:

* finfo
* timeline
* user
* wiki
* zip

Advanced commands:

* configuration
* descendants
* scrub
* search
* sha3sum

## Basic

### help

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

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

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

```
$ fossil help
Usage: fossil help TOPIC
Try "fossil help help" or "fossil help -a" for more options
Frequently used commands:
add          cat          extras       merge        rm           ui         
addremove    changes      finfo        mv           settings     undo       
all          clean        gdiff        open         sql          unversioned
amend        clone        grep         pull         stash        update     
annotate     commit       help         push         status       version    
bisect       dbstat       info         rebuild      sync       
blame        delete       init         remote       tag        
branch       diff         ls           revert       timeline   
This is fossil version 2.14 [939a13d94f] 2020-11-20 19:28:05 UTC
```

Adding the optin `-a` (or `-all`) to the help command results in a listing of ALL the available commands:

```
$ fossil help -a
3-way-merge    clean          hook           rebuild        stash        
add            clone          http           reconstruct    status       
addremove      close          import         redo           sync         
alerts         co             info           remote         tag          
all            commit         init           remote-url     tarball      
amend          configuration  interwiki      rename         ticket       
annotate       dbstat         leaves         reparent       timeline     
artifact       deconstruct    login-group    revert         tls-config   
attachment     delete         ls             rm             touch        
backoffice     descendants    md5sum         rss            ui           
backup         diff           merge          scrub          undo         
bisect         export         mv             search         unpublished  
blame          extras         new            server         unset        
branch         finfo          open           settings       unversioned  
bundle         forget         pikchr         sha1sum        update       
cache          fts-config     pop3d          sha3sum        user         
cat            gdiff          praise         shell          uv           
cgi            git            publish        smtpd          version      
changes        grep           pull           sql            whatis       
checkout       hash-policy    purge          sqlar          wiki         
ci             help           push           sqlite3        zip          

```

Use it to get further information about a particular command:


```
$ fossil help help
Usage: fossil help [OPTIONS] [TOPIC]

Display information on how to use TOPIC, which may be a command, webpage, or
setting.  Webpage names begin with "/".  If TOPIC is omitted, a list of
topics is returned.

The following options can be used when TOPIC is omitted:

   -a|--all          List both common and auxiliary commands
   -o|--options      List command-line options common to all commands
   -s|--setting      List setting names
   -t|--test         List unsupported "test" commands
   -x|--aux          List only auxiliary commands
   -w|--www          List all web pages
   -f|--full         List full set of commands (including auxiliary
                     and unsupported "test" commands), options,
                     settings, and web pages
   -e|--everything   List all help on all topics

These options can be used when TOPIC is present:

   -h|--html         Format output as HTML rather than plain text
   -c|--commands     Restrict TOPIC search to commands
```

As you can see from the description, `fossil help -a` doesn't even list all possibilities. With the `-f` option, you get even more!

### add

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

```
$ fossil help add
Usage: fossil add ?OPTIONS? FILE1 ?FILE2 ...?

Make arrangements to add one or more files or directories to the
current check-out at the next commit.

When adding files or directories recursively, filenames that begin
with "." are excluded by default.  To include such files, add
the "--dotfiles" option to the command-line.

The --ignore and --clean options are comma-separated lists of glob patterns
for files to be excluded.  Example:  '*.o,*.obj,*.exe'  If the --ignore
option does not appear on the command line then the "ignore-glob" setting
is used.  If the --clean option does not appear on the command line then
the "clean-glob" setting is used.

If files are attempted to be added explicitly on the command line which
match "ignore-glob", a confirmation is asked first. This can be prevented
using the -f|--force option.

The --case-sensitive option determines whether or not filenames should
be treated case sensitive or not. If the option is not given, the default
depends on the global setting, or the operating system default, if not set.

Options:

   --case-sensitive BOOL   Override the case-sensitive setting.
   --dotfiles              include files beginning with a dot (".")
   -f|--force              Add files without prompting
   --ignore CSG            Ignore unmanaged files matching patterns from
                           the Comma Separated Glob (CSG) pattern list
   --clean CSG             Also ignore files matching patterns from
                           the Comma Separated Glob (CSG) list
   --reset                 Reset the ADDED state of a check-out, such
                           that all newly-added (but not yet committed)
                           files are no longer added. No flags other
                           than --verbose and --dry-run may be used
                           with --reset.

The following options are only valid with --reset:
   -v|--verbose            Outputs information about each --reset file.
   -n|--dry-run            Display instead of run actions.

See also: addremove, rm

```

Typing:

```
fossil add .
```

will add all files in the current directory and subdirectories.

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

### rm or del

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

```
$ fossil help rm
Usage: fossil rm|delete|forget FILE1 ?FILE2 ...?

Remove one or more files or directories from the repository.

The 'rm' and 'delete' commands do NOT normally remove the files from
disk.  They just mark the files as no longer being part of the project.
In other words, future changes to the named files will not be versioned.
However, the default behavior of this command may be overridden via the
command line options listed below and/or the 'mv-rm-files' setting.

The 'forget' command never removes files from disk, even when the command
line options and/or the 'mv-rm-files' setting would otherwise require it
to do so.

WARNING: If the "--hard" option is specified -OR- the "mv-rm-files"
         setting is non-zero, files WILL BE removed from disk as well.
         This does NOT apply to the 'forget' command.

Options:
  --soft                  Skip removing files from the check-out.
                          This supersedes the --hard option.
  --hard                  Remove files from the check-out.
  --case-sensitive BOOL   Override the case-sensitive setting.
  -n|--dry-run            If given, display instead of run actions.
  --reset                 Reset the DELETED state of a check-out, such
                          that all newly-rm'd (but not yet committed)
                          files are no longer removed. No flags other
                          than --verbose or --dry-run may be used with
                          --reset.
  --verbose|-v            Outputs information about each --reset file.
                          Only usable with --reset.

See also: addremove, add

```

You can delete groups of files by using wild-cards in their names. Thus if I had a group of files like com_tr.c, com_rx.c and com_mgmt.c I could remove them all with:

```
fossil rm com_*.c
```

By running a "fossil status" you can see what files will be deleted on the next commit.

### rename or mv

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

```
$ fossil help rename
Usage: fossil mv|rename OLDNAME NEWNAME
   or: fossil mv|rename OLDNAME... DIR

Move or rename one or more files or directories within the repository tree.
You can either rename a file or directory or move it to another subdirectory.

The 'mv' command does NOT normally rename or move the files on disk.
This command merely records the fact that file names have changed so
that appropriate notations can be made at the next commit.
However, the default behavior of this command may be overridden via
command line options listed below and/or the 'mv-rm-files' setting.

The 'rename' command never renames or moves files on disk, even when the
command line options and/or the 'mv-rm-files' setting would otherwise
require it to do so.

WARNING: If the "--hard" option is specified -OR- the "mv-rm-files"
         setting is non-zero, files WILL BE renamed or moved on disk
         as well.  This does NOT apply to the 'rename' command.

Options:
  --soft                    Skip moving files within the check-out.
                            This supersedes the --hard option.
  --hard                    Move files within the check-out.
  --case-sensitive BOOL     Override the case-sensitive setting.
  -n|--dry-run              If given, display instead of run actions.

See also: changes, status

```

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

### status

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

```
$ fossil help status
Usage: fossil changes|status ?OPTIONS? ?PATHS ...?

Report the change status of files in the current check-out.  If one or
more PATHS are specified, only changes among the named files and
directories are reported.  Directories are searched recursively.

... [snipped]

See also: extras, ls

```

```
$ fossil status
repository:   /home/chris/repos/fossilbook.fossil
local-root:   /home/chris/fossilbook/
config-db:    /home/chris/.config/fossil.db
checkout:     516e309ea1c86132e3a9be313e8331ec91f255ee 2020-11-21 16:26:12 UTC
parent:       030a38fe4b45b7088faa635982037d2eb05143b6 2020-11-21 16:23:34 UTC
tags:         trunk
comment:      Use .md file extension in book.md links. (user: chris)
EDITED     content/introduction.md
EDITED     content/rights.md

```

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

### changes

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

```
$ fossil help changes
Usage: fossil changes|status ?OPTIONS? ?PATHS ...?

Report the change status of files in the current check-out.  If one or
more PATHS are specified, only changes among the named files and
directories are reported.  Directories are searched recursively.

The status command is similar to the changes command, except it lacks
several of the options supported by changes and it has its own header
and footer information.  The header information is a subset of that
shown by the info command, and the footer shows if there are any forks.
Change type classification is always enabled for the status command.

Each line of output is the name of a changed file, with paths shown
according to the "relative-paths" setting, unless overridden by the
--abs-paths or --rel-paths options.

By default, all changed files are selected for display.  This behavior
can be overridden by using one or more filter options (listed below),
in which case only files with the specified change type(s) are shown.
As a special case, the --no-merge option does not inhibit this default.
This default shows exactly the set of changes that would be checked
in by the commit command.

If no filter options are used, or if the --merge option is used, the
artifact hash of each merge contributor check-in version is displayed at
the end of the report.  The --no-merge option is useful to display the
default set of changed files without the merge contributors.

If change type classification is enabled, each output line starts with
a code describing the file's change type, e.g. EDITED or RENAMED.  It
is enabled by default unless exactly one change type is selected.  For
the purposes of determining the default, --changed counts as selecting
one change type.  The default can be overridden by the --classify or
--no-classify options.

--edited and --updated produce disjoint sets.  --updated shows a file
only when it is identical to that of its merge contributor, and the
change type classification is UPDATED_BY_MERGE or UPDATED_BY_INTEGRATE.
If the file had to be merged with any other changes, it is considered
to be merged or conflicted and therefore will be shown by --edited, not
--updated, with types EDITED or CONFLICT.  The --changed option can be
used to display the union of --edited and --updated.

--differ is so named because it lists all the differences between the
checked-out version and the check-out directory.  In addition to the
default changes (excluding --merge), it lists extra files which (if
ignore-glob is set correctly) may be worth adding.  Prior to doing a
commit, it is good practice to check --differ to see not only which
changes would be committed but also if any files should be added.

If both --merge and --no-merge are used, --no-merge has priority.  The
same is true of --classify and --no-classify.

The "fossil changes --extra" command is equivalent to "fossil extras".

General options:
   --abs-paths       Display absolute pathnames.
   --rel-paths       Display pathnames relative to the current working
                     directory.
   --hash            Verify file status using hashing rather than
                     relying on file mtimes.
   --case-sensitive BOOL  Override case-sensitive setting.
   --dotfiles        Include unmanaged files beginning with a dot.
   --ignore <CSG>    Ignore unmanaged files matching CSG glob patterns.

Options specific to the changes command:
   --header          Identify the repository if report is non-empty.
   -v|--verbose      Say "(none)" if the change report is empty.
   --classify        Start each line with the file's change type.
   --no-classify     Do not print file change types.

Filter options:
   --edited          Display edited, merged, and conflicted files.
   --updated         Display files updated by merge/integrate.
   --changed         Combination of the above two options.
   --missing         Display missing files.
   --added           Display added files.
   --deleted         Display deleted files.
   --renamed         Display renamed files.
   --conflict        Display files having merge conflicts.
   --meta            Display files with metadata changes.
   --unchanged       Display unchanged files.
   --all             Display all managed files, i.e. all of the above.
   --extra           Display unmanaged files.
   --differ          Display modified and extra files.
   --merge           Display merge contributors.
   --no-merge        Do not display merge contributors.

See also: extras, ls

```

### extras

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

```
$ fossil help extras
Usage: fossil extras ?OPTIONS? ?PATH1 ...?

Print a list of all files in the source tree that are not part of the
current check-out. See also the "clean" command. If paths are specified,
only files in the given directories will be listed.

Files and subdirectories whose names begin with "." are normally
ignored but can be included by adding the --dotfiles option.

Files whose names match any of the glob patterns in the "ignore-glob"
setting are ignored. This setting can be overridden by the --ignore
option, whose CSG argument is a comma-separated list of glob patterns.

Pathnames are displayed according to the "relative-paths" setting,
unless overridden by the --abs-paths or --rel-paths options.

Options:
   --abs-paths             Display absolute pathnames.
   --case-sensitive BOOL   Override case-sensitive setting
   --dotfiles              Include files beginning with a dot (".")
   --header                Identify the repository if there are extras
   --ignore CSG            Ignore files matching patterns from the argument
   --rel-paths             Display pathnames relative to the current working
                           directory.

See also: changes, clean, status

```

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 the earlier version of this repository, when Lyx was the editor of choice, there was a file called fossilbook.lyx~ that is a LyX backup file that was not wanted, as it is temporary. So one can say

```
fossil extra -{}-ignore \*.lyx~
```
and only get:

```
$ fossil extra -{}-ignore \*.lyx\~

image/basic/help.png

```

instead of:

```
$ fossil extra

image/basic/help1.png
fossilbook.lyx~

```

### revert

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

```
$ fossil help revert
Usage: fossil revert ?OPTIONS? ?FILE ...?

Revert to the current repository version of FILE, or to
the baseline VERSION specified with -r flag.

If FILE was part of a rename operation, both the original file
and the renamed file are reverted.

Using a directory name for any of the FILE arguments is the same
as using every subdirectory and file beneath that directory.

Revert all files if no file name is provided.

If a file is reverted accidentally, it can be restored using
the "fossil undo" command.

Options:
  -r|--revision VERSION    Revert given FILE(s) back to given
                           VERSION

See also: redo, undo, check-out, update

```

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

### update

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

```
$ fossil help update
Usage: fossil update ?OPTIONS? ?VERSION? ?FILES...?

Change the version of the current check-out to VERSION.  Any
uncommitted changes are retained and applied to the new check-out.

The VERSION argument can be a specific version or tag or branch
name.  If the VERSION argument is omitted, then the leaf of the
subtree that begins at the current version is used, if there is
only a single leaf.  VERSION can also be "current" to select the
leaf of the current version or "latest" to select the most recent
check-in.

If one or more FILES are listed after the VERSION then only the
named files are candidates to be updated, and any updates to them
will be treated as edits to the current version. Using a directory
name for one of the FILES arguments is the same as using every
subdirectory and file beneath that directory.

If FILES is omitted, all files in the current check-out are subject
to being updated and the version of the current check-out is changed
to VERSION. Any uncommitted changes are retained and applied to the
new check-out.

The -n or --dry-run option causes this command to do a "dry run".
It prints out what would have happened but does not actually make
any changes to the current check-out or the repository.

The -v or --verbose option prints status information about
unchanged files in addition to those file that actually do change.

Options:
  --case-sensitive BOOL  Override case-sensitive setting
  --debug                Print debug information on stdout
  --latest               Acceptable in place of VERSION, update to
                         latest version
  --force-missing        Force update if missing content after sync
  -n|--dry-run           If given, display instead of run actions
  -v|--verbose           Print status information about all files
  -W|--width WIDTH       Width of lines (default is to auto-detect).
                         Must be more than 20 or 0 (= no limit,
                         resulting in a single line per entry).
  --setmtime             Set timestamps of all files to match their
                         SCM-side times (the timestamp of the last
                         check-in which modified them).
 -K|--keep-merge-files   On merge conflict, retain the temporary files
                         used for merging, named *-baseline, *-original,
                         and *-merge.

See also: revert

```

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

```
$ fossil update \*.c

```

and it would update all C files.

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

::: GoodToKnow
The `update` command can be used to do a kind of cherrypicking. When you have a branch (or just some other version) and want to only merge a single file of that branch/version into the current check-out, you can do `fossil update other_branch other_file`. This will bring a copy of that other file into the current branch/version. However, this will not leave any trace in the timeline. Further, you will have to `fossil add` that file specifically yourself so it gets committed in the next `fossil commit`.
:::

The `---dry-run` option is special as it is not able to detect changes that have been done in another repository that have not been pulled into the local repository. The help text states that no changes are made to the current check-out or the repository. So, a dry run has no way to determine whether something changed in an "up-stream" repository and thus whether an update would lead to a conflict. Without a dry run, Fossil would typically make a `fossil pull` before the update of the check-out. Thus, if you want to have a dry run and see everything, you must do a `fossil pull` before the `fossil update --dry-run`.

### check-out or co

This command is similar to update.

```
$ fossil help check-out
Usage: fossil check-out ?VERSION | --latest? ?OPTIONS?
   or: fossil co ?VERSION | --latest? ?OPTIONS?

Check out a version specified on the command-line.  This command
will abort if there are edited files in the current check-out unless
the --force option appears on the command-line.  The --keep option
leaves files on disk unchanged, except the manifest and manifest.uuid
files.

The --latest flag can be used in place of VERSION to check-out the
latest version in the repository.

Options:
   --force           Ignore edited files in the current check-out
   --keep            Only update the manifest and manifest.uuid files
   --force-missing   Force check-out even if content is missing
   --setmtime        Set timestamps of all files to match their SCM-side
                     times (the timestamp of the last check-in which modified
                     them).

See also: update

```

### undo

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

```
$ fossil help undo
Usage: fossil undo ?OPTIONS? ?FILENAME...?
   or: fossil redo ?OPTIONS? ?FILENAME...?

The undo command reverts the changes caused by the previous command
if the previous command is one of the following:
 * fossil update
 * fossil merge
 * fossil revert
 * fossil stash pop
 * fossil stash apply
 * fossil stash drop
 * fossil stash goto
 * fossil clean (*see note below*)

Note: The "fossil clean" command only saves state for files less than
10MiB in size and so if fossil clean deleted files larger than that,
then "fossil undo" will not recover the larger files.

If FILENAME is specified then restore the content of the named
file(s) but otherwise leave the update or merge or revert in effect.
The redo command undoes the effect of the most recent undo.

If the -n|--dry-run option is present, no changes are made and instead
the undo or redo command explains what actions the undo or redo would
have done had the -n|--dry-run been omitted.

If the most recent command is not one of those listed as undoable,
then the undo command might try to restore the state to be what it was
prior to the last undoable command, or it might be a no-op.  If in
doubt about what the undo command will do, first run it with the -n
option.

A single level of undo/redo is supported.  The undo/redo stack
is cleared by the commit and check-out commands.  Other commands may
or may not clear the undo stack.

Future versions of Fossil might add new commands to the set of commands
that are undoable.

Options:
  -n|--dry-run   do not make changes but show what would be done

See also: commit, status

```

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

### diff

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

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

```
$ fossil help diff
Usage: fossil diff|gdiff ?OPTIONS? ?FILE1? ?FILE2 ...?

Show the difference between the current version of each of the FILEs
specified (as they exist on disk) and that same file as it was checked
out.  Or if the FILE arguments are omitted, show the unsaved changes
currently in the working check-out.

If the "--from VERSION" or "-r VERSION" option is used it specifies
the source check-in for the diff operation.  If not specified, the
source check-in is the base check-in for the current check-out.

If the "--to VERSION" option appears, it specifies the check-in from
which the second version of the file or files is taken.  If there is
no "--to" option then the (possibly edited) files in the current check-out
are used.

The "--checkin VERSION" option shows the changes made by
check-in VERSION relative to its primary parent.

The "-i" command-line option forces the use of the internal diff logic
rather than any external diff program that might be configured using
the "setting" command.  If no external diff program is configured, then
the "-i" option is a no-op.  The "-i" option converts "gdiff" into "diff".

The "-N" or "--new-file" option causes the complete text of added or
deleted files to be displayed.

The "--diff-binary" option enables or disables the inclusion of binary files
when using an external diff program.

The "--binary" option causes files matching the glob PATTERN to be treated
as binary when considering if they should be used with external diff program.
This option overrides the "binary-glob" setting.

Options:
  --binary PATTERN            Treat files that match the glob PATTERN
                              as binary
  --branch BRANCH             Show diff of all changes on BRANCH
  --brief                     Show filenames only
  --checkin VERSION           Show diff of all changes in VERSION
  --command PROG              External diff program. Overrides "diff-command"
  --context|-c N              Use N lines of context
  --diff-binary BOOL          Include binary files with external commands
  --exec-abs-paths            Force absolute path names on external commands
  --exec-rel-paths            Force relative path names on external commands
  --from|-r VERSION           Select VERSION as source for the diff
  --internal|-i               Use internal diff logic
  --new-file|-N               Show complete text of added and deleted files
  --numstat                   Show only the number of lines delete and added
  --side-by-side|-y           Side-by-side diff
  --strip-trailing-cr         Strip trailing CR
  --tclsh PATH                Tcl/Tk used for --tk (default: "tclsh")
  --tk                        Launch a Tcl/Tk GUI for display
  --to VERSION                Select VERSION as target for the diff
  --undo                      Diff against the "undo" buffer
  --unified                   Unified diff
  -v|--verbose                Output complete text of added or deleted files
  -w|--ignore-all-space       Ignore white space when comparing lines
  -W|--width N                Width of lines in side-by-side diff
  -Z|--ignore-trailing-space  Ignore changes to end-of-line whitespace

```

### gdiff

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

```
$ fossil help gdiff
Usage: fossil diff|gdiff ?OPTIONS? ?FILE1? ?FILE2 ...?

Show the difference between the current version of each of the FILEs
specified (as they exist on disk) and that same file as it was checked
out.  Or if the FILE arguments are omitted, show the unsaved changes
currently in the working check-out.

If the "--from VERSION" or "-r VERSION" option is used it specifies
the source check-in for the diff operation.  If not specified, the
source check-in is the base check-in for the current check-out.

If the "--to VERSION" option appears, it specifies the check-in from
which the second version of the file or files is taken.  If there is
no "--to" option then the (possibly edited) files in the current check-out
are used.

The "--checkin VERSION" option shows the changes made by
check-in VERSION relative to its primary parent.

The "-i" command-line option forces the use of the internal diff logic
rather than any external diff program that might be configured using
the "setting" command.  If no external diff program is configured, then
the "-i" option is a no-op.  The "-i" option converts "gdiff" into "diff".

The "-N" or "--new-file" option causes the complete text of added or
deleted files to be displayed.

The "--diff-binary" option enables or disables the inclusion of binary files
when using an external diff program.

The "--binary" option causes files matching the glob PATTERN to be treated
as binary when considering if they should be used with external diff program.
This option overrides the "binary-glob" setting.

Options:
  --binary PATTERN            Treat files that match the glob PATTERN
                              as binary
  --branch BRANCH             Show diff of all changes on BRANCH
  --brief                     Show filenames only
  --checkin VERSION           Show diff of all changes in VERSION
  --command PROG              External diff program. Overrides "diff-command"
  --context|-c N              Use N lines of context
  --diff-binary BOOL          Include binary files with external commands
  --exec-abs-paths            Force absolute path names on external commands
  --exec-rel-paths            Force relative path names on external commands
  --from|-r VERSION           Select VERSION as source for the diff
  --internal|-i               Use internal diff logic
  --new-file|-N               Show complete text of added and deleted files
  --numstat                   Show only the number of lines delete and added
  --side-by-side|-y           Side-by-side diff
  --strip-trailing-cr         Strip trailing CR
  --tclsh PATH                Tcl/Tk used for --tk (default: "tclsh")
  --tk                        Launch a Tcl/Tk GUI for display
  --to VERSION                Select VERSION as target for the diff
  --undo                      Diff against the "undo" buffer
  --unified                   Unified diff
  -v|--verbose                Output complete text of added or deleted files
  -w|--ignore-all-space       Ignore white space when comparing lines
  -W|--width N                Width of lines in side-by-side diff
  -Z|--ignore-trailing-space  Ignore changes to end-of-line whitespace

```

### ui

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

```
$ fossil help ui
Usage: fossil server ?OPTIONS? ?REPOSITORY?
   or: fossil ui ?OPTIONS? ?REPOSITORY?

Open a socket and begin listening and responding to HTTP requests on
TCP port 8080, or on any other TCP port defined by the -P or
--port option.  The optional argument is the name of the repository.
The repository argument may be omitted if the working directory is
within an open check-out.

The "ui" command automatically starts a web browser after initializing
the web server.  The "ui" command also binds to 127.0.0.1 and so will
only process HTTP traffic from the local machine.

The REPOSITORY can be a directory (aka folder) that contains one or
more repositories with names ending in ".fossil".  In this case, a
prefix of the URL pathname is used to search the directory for an
appropriate repository.  To thwart mischief, the pathname in the URL must
contain only alphanumerics, "_", "/", "-", and ".", and no "-" may
occur after "/", and every "." must be surrounded on both sides by
alphanumerics.  Any pathname that does not satisfy these constraints
results in a 404 error.  Files in REPOSITORY that match the comma-separated
list of glob patterns given by --files and that have known suffixes
such as ".txt" or ".html" or ".jpeg" and do not match the pattern
"*.fossil*" will be served as static content.  With the "ui" command,
the REPOSITORY can only be a directory if the --notfound option is
also present.

For the special case REPOSITORY name of "/", the list global configuration
database is consulted for a list of all known repositories.  The --repolist
option is implied by this special case.  See also the "fossil all ui"
command.

By default, the "ui" command provides full administrative access without
having to log in.  This can be disabled by turning off the "localauth"
setting.  Automatic login for the "server" command is available if the
--localauth option is present and the "localauth" setting is off and the
connection is from localhost.  The "ui" command also enables --repolist
by default.

Options:
  --baseurl URL       Use URL as the base (useful for reverse proxies)
  --create            Create a new REPOSITORY if it does not already exist
  --extroot DIR       Document root for the /ext extension mechanism
  --files GLOBLIST    Comma-separated list of glob patterns for static files
  --localauth         enable automatic login for requests from localhost
  --localhost         listen on 127.0.0.1 only (always true for "ui")
  --https             Indicates that the input is coming through a reverse
                      proxy that has already translated HTTPS into HTTP.
  --jsmode MODE       Determine how JavaScript is delivered with pages.
                      Mode can be one of:
                         inline       All JavaScript is inserted inline at
                                      the end of the HTML file.
                         separate     Separate HTTP requests are made for
                                      each JavaScript file.
                         bundled      One single separate HTTP fetches all
                                      JavaScript concatenated together.
                      Depending on the needs of any given page, inline
                      and bundled modes might result in a single
                      amalgamated script or several, but both approaches
                      result in fewer HTTP requests than the separate mode.
  --max-latency N     Do not let any single HTTP request run for more than N
                      seconds (only works on unix)
  --nocompress        Do not compress HTTP replies
  --nojail            Drop root privileges but do not enter the chroot jail
  --nossl             signal that no SSL connections are available (Always
                      set by default for the "ui" command)
  --notfound URL      Redirect
  --page PAGE         Start "ui" on PAGE.  ex: --page "timeline?y=ci"
  -P|--port TCPPORT   listen to request on port TCPPORT
  --th-trace          trace TH1 execution (for debugging purposes)
  --repolist          If REPOSITORY is dir, URL "/" lists repos.
  --scgi              Accept SCGI rather than HTTP
  --skin LABEL        Use override skin LABEL
  --usepidkey         Use saved encryption key from parent process.  This is
                      only necessary when using SEE on Windows.

See also: cgi, http, winsrv

```

### server

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

```
$ fossil help server
Usage: fossil server ?OPTIONS? ?REPOSITORY?
   or: fossil ui ?OPTIONS? ?REPOSITORY?

Open a socket and begin listening and responding to HTTP requests on
TCP port 8080, or on any other TCP port defined by the -P or
--port option.  The optional argument is the name of the repository.
The repository argument may be omitted if the working directory is
within an open check-out.

The "ui" command automatically starts a web browser after initializing
the web server.  The "ui" command also binds to 127.0.0.1 and so will
only process HTTP traffic from the local machine.

The REPOSITORY can be a directory (aka folder) that contains one or
more repositories with names ending in ".fossil".  In this case, a
prefix of the URL pathname is used to search the directory for an
appropriate repository.  To thwart mischief, the pathname in the URL must
contain only alphanumerics, "_", "/", "-", and ".", and no "-" may
occur after "/", and every "." must be surrounded on both sides by
alphanumerics.  Any pathname that does not satisfy these constraints
results in a 404 error.  Files in REPOSITORY that match the comma-separated
list of glob patterns given by --files and that have known suffixes
such as ".txt" or ".html" or ".jpeg" and do not match the pattern
"*.fossil*" will be served as static content.  With the "ui" command,
the REPOSITORY can only be a directory if the --notfound option is
also present.

For the special case REPOSITORY name of "/", the list global configuration
database is consulted for a list of all known repositories.  The --repolist
option is implied by this special case.  See also the "fossil all ui"
command.

By default, the "ui" command provides full administrative access without
having to log in.  This can be disabled by turning off the "localauth"
setting.  Automatic login for the "server" command is available if the
--localauth option is present and the "localauth" setting is off and the
connection is from localhost.  The "ui" command also enables --repolist
by default.

Options:
  --baseurl URL       Use URL as the base (useful for reverse proxies)
  --create            Create a new REPOSITORY if it does not already exist
  --extroot DIR       Document root for the /ext extension mechanism
  --files GLOBLIST    Comma-separated list of glob patterns for static files
  --localauth         enable automatic login for requests from localhost
  --localhost         listen on 127.0.0.1 only (always true for "ui")
  --https             Indicates that the input is coming through a reverse
                      proxy that has already translated HTTPS into HTTP.
  --jsmode MODE       Determine how JavaScript is delivered with pages.
                      Mode can be one of:
                         inline       All JavaScript is inserted inline at
                                      the end of the HTML file.
                         separate     Separate HTTP requests are made for
                                      each JavaScript file.
                         bundled      One single separate HTTP fetches all
                                      JavaScript concatenated together.
                      Depending on the needs of any given page, inline
                      and bundled modes might result in a single
                      amalgamated script or several, but both approaches
                      result in fewer HTTP requests than the separate mode.
  --max-latency N     Do not let any single HTTP request run for more than N
                      seconds (only works on unix)
  --nocompress        Do not compress HTTP replies
  --nojail            Drop root privileges but do not enter the chroot jail
  --nossl             signal that no SSL connections are available (Always
                      set by default for the "ui" command)
  --notfound URL      Redirect
  --page PAGE         Start "ui" on PAGE.  ex: --page "timeline?y=ci"
  -P|--port TCPPORT   listen to request on port TCPPORT
  --th-trace          trace TH1 execution (for debugging purposes)
  --repolist          If REPOSITORY is dir, URL "/" lists repos.
  --scgi              Accept SCGI rather than HTTP
  --skin LABEL        Use override skin LABEL
  --usepidkey         Use saved encryption key from parent process.  This is
                      only necessary when using SEE on Windows.

See also: cgi, http, winsrv

```

### commit or ci

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

```
$ fossil help commit
Usage: fossil commit ?OPTIONS? ?FILE...?
   or: fossil ci ?OPTIONS? ?FILE...?

Create a new version containing all of the changes in the current
check-out.  You will be prompted to enter a check-in comment unless
the comment has been specified on the command-line using "-m" or a
file containing the comment using -M.  The editor defined in the
"editor" fossil option (see fossil help set) will be used, or from
the "VISUAL" or "EDITOR" environment variables (in that order) if
no editor is set.

All files that have changed will be committed unless some subset of
files is specified on the command line.

The --branch option followed by a branch name causes the new
check-in to be placed in a newly-created branch with the name
passed to the --branch option.

Use the --branchcolor option followed by a color name (ex:
'#ffc0c0') to specify the background color of entries in the new
branch when shown in the web timeline interface.  The use of
the --branchcolor option is not recommended.  Instead, let Fossil
choose the branch color automatically.

The --bgcolor option works like --branchcolor but only sets the
background color for a single check-in.  Subsequent check-ins revert
to the default color.

A check-in is not permitted to fork unless the --allow-fork option
appears.  An empty check-in (i.e. with nothing changed) is not
allowed unless the --allow-empty option appears.  A check-in may not
be older than its ancestor unless the --allow-older option appears.
If any of files in the check-in appear to contain unresolved merge
conflicts, the check-in will not be allowed unless the
--allow-conflict option is present.  In addition, the entire
check-in process may be aborted if a file contains content that
appears to be binary, Unicode text, or text with CR/LF line endings
unless the interactive user chooses to proceed.  If there is no
interactive user or these warnings should be skipped for some other
reason, the --no-warnings option may be used.  A check-in is not
allowed against a closed leaf.

If a commit message is blank, you will be prompted:
("continue (y/N)?") to confirm you really want to commit with a
blank commit message.  The default value is "N", do not commit.

The --private option creates a private check-in that is never synced.
Children of private check-ins are automatically private.

The --tag option applies the symbolic tag name to the check-in.

The --hash option detects edited files by computing each file's
artifact hash rather than just check-ing for changes to its size or mtime.

Options:
   --allow-conflict           allow unresolved merge conflicts
   --allow-empty              allow a commit with no changes
   --allow-fork               allow the commit to fork
   --allow-older              allow a commit older than its ancestor
   --baseline                 use a baseline manifest in the commit process
   --bgcolor COLOR            apply COLOR to this one check-in only
   --branch NEW-BRANCH-NAME   check in to this new branch
   --branchcolor COLOR        apply given COLOR to the branch
   --close                    close the branch being committed
   --date-override DATETIME   DATE to use instead of 'now'
   --delta                    use a delta manifest in the commit process
   --hash                     verify file status using hashing rather
                              than relying on file mtimes
   --integrate                close all merged-in branches
   -m|--comment COMMENT-TEXT  use COMMENT-TEXT as commit comment
   -M|--message-file FILE     read the commit comment from given file
   --mimetype MIMETYPE        mimetype of check-in comment
   -n|--dry-run               If given, display instead of run actions
   --no-prompt                This option disables prompting the user for
                              input and assumes an answer of 'No' for every
                              question.
   --no-warnings              omit all warnings about file contents
   --no-verify                do not run before-commit hooks
   --nosign                   do not attempt to sign this commit with gpg
   --override-lock            allow a check-in even though parent is locked
   --private                  do not sync changes and their descendants
   --tag TAG-NAME             assign given tag TAG-NAME to the check-in
   --trace                    debug tracing.
   --user-override USER       USER to use instead of the current default

DATETIME may be "now" or "YYYY-MM-DDTHH:MM:SS.SSS". If in
year-month-day form, it may be truncated, the "T" may be replaced by
a space, and it may also name a timezone offset from UTC as "-HH:MM"
(westward) or "+HH:MM" (eastward). Either no timezone suffix or "Z"
means UTC.

See also: branch, changes, update, extras, sync

```

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.

## Maintenance

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 fossil help will probably be required before use. Some of them like new or clone are only needed when you start a repository. Others like rebuild or reconstruct are only needed to fix or update a repository.

### new

This command is used to create a new repository.

```
$ fossil help new
Usage: fossil new ?OPTIONS? FILENAME
   or: fossil init ?OPTIONS? FILENAME

Create a repository for a new project in the file named FILENAME.
This command is distinct from "clone".  The "clone" command makes
a copy of an existing project.  This command starts a new project.

By default, your current login name is used to create the default
admin user. This can be overridden using the -A|--admin-user
parameter.

By default, all settings will be initialized to their default values.
This can be overridden using the --template parameter to specify a
repository file from which to copy the initial settings.  When a template
repository is used, almost all of the settings accessible from the setup
page, either directly or indirectly, will be copied.  Normal users and
their associated permissions will not be copied; however, the system
default users "anonymous", "nobody", "reader", "developer", and their
associated permissions will be copied.

Options:
   --template      FILE         Copy settings from repository file
   --admin-user|-A USERNAME     Select given USERNAME as admin user
   --date-override DATETIME     Use DATETIME as time of the initial check-in
   --sha1                       Use an initial hash policy of "sha1"

DATETIME may be "now" or "YYYY-MM-DDTHH:MM:SS.SSS". If in
year-month-day form, it may be truncated, the "T" may be replaced by
a space, and it may also name a timezone offset from UTC as "-HH:MM"
(westward) or "+HH:MM" (eastward). Either no timezone suffix or "Z"
means UTC.

See also: clone

```

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

### clone

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

```
$ fossil help clone
Usage: fossil clone ?OPTIONS? URI ?FILENAME?

Make a clone of a repository specified by URI in the local
file named FILENAME.  If FILENAME is omitted, then an appropriate
filename is deduced from last element of the path in the URL.

URI may be one of the following forms ([...] denotes optional elements):

 * HTTP/HTTPS protocol:

     http[s]://[userid[:password]@]host[:port][/path]

 * SSH protocol:

     ssh://[userid@]host[:port]/path/to/repo.fossil[?fossil=path/fossil.exe]

 * Filesystem:

     [file://]path/to/repo.fossil

For ssh and filesystem, path must have an extra leading
'/' to use an absolute path.

Use %HH escapes for special characters in the userid and
password.  For example "%40" in place of "@", "%2f" in place
of "/", and "%3a" in place of ":".

Note that in Fossil (in contrast to some other DVCSes) a repository
is distinct from a check-out.  Cloning a repository is not the same thing
as opening a repository.  This command always clones the repository.  This
command might also open the repository, but only if the --no-open option
is omitted and either the --workdir option is included or the FILENAME
argument is omitted.  Use the separate open command to open a
repository that was previously cloned and already exists on the
local machine.

By default, the current login name is used to create the default
admin user for the new clone. This can be overridden using
the -A|--admin-user parameter.

Options:
   --admin-user|-A USERNAME   Make USERNAME the administrator
   --httpauth|-B USER:PASS    Add HTTP Basic Authorization to requests
   --nocompress               Omit extra delta compression
   --no-open                  Clone only.  Do not open a check-out.
   --once                     Don't remember the URI.
   --private                  Also clone private branches
   --save-http-password       Remember the HTTP password without asking
   --ssh-command|-c SSH       Use SSH as the "ssh" command
   --ssl-identity FILENAME    Use the SSL identity if requested by the server
   -u|--unversioned           Also sync unversioned content
   -v|--verbose               Show more statistics in output
   --workdir DIR              Also open a check-out in DIR

See also: init, open

```

As with __create__, you can specify the admin user for this clone with an option. The URL for the master repository is of the form:

```
https://user:password@domain
```

Where user and password are for a valid user of the selected repository. It is best to check the path with a browser before doing the clone. Make sure you can reach it, for example the repository for this book is:

```
https://www.fossil-scm.org/schimpf-book/home
```

Putting that into a browser should get you the home page for this book. (See Figure [fig:Web-access-to]). After you have verified that, then running the clone command should work.

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

### open

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

```
$ fossil help open
Usage: fossil open REPOSITORY ?VERSION? ?OPTIONS?

Open a new connection to the repository name REPOSITORY.  A check-out
for the repository is created with its root at the current working
directory, or in DIR if the "--workdir DIR" is used.  If VERSION is
specified then that version is checked out.  Otherwise the most recent
check-in on the main branch (usually "trunk") is used.

REPOSITORY can be the filename for a repository that already exists on the
local machine or it can be a URI for a remote repository.  If REPOSITORY
is a URI in one of the formats recognized by the clone command, then
remote repo is first cloned, then the clone is opened. The clone will be
stored in the current directory, or in DIR if the "--repodir DIR" option
is used. The name of the clone will be taken from the last term of the URI.
For "http:" and "https:" URIs, you can append an extra term to the end of
the URI to get any repository name you like. For example:

    fossil open https://fossil-scm.org/home/new-name

The base URI for cloning is "https://fossil-scm.org/home".  The extra
"new-name" term means that the cloned repository will be called
"new-name.fossil".

Options:
  --empty           Initialize check-out as being empty, but still connected
                    with the local repository. If you commit this check-out,
                    it will become a new "initial" commit in the repository.
  -f|--force        Continue with the open even if the working directory is
                    not empty.
  --force-missing   Force opening a repository with missing content
  --keep            Only modify the manifest and manifest.uuid files
  --nested          Allow opening a repository inside an opened check-out
  --repodir DIR     If REPOSITORY is a URI that will be cloned, store
                    the clone in DIR rather than in "."
  --setmtime        Set timestamps of all files to match their SCM-side
                    times (the timestamp of the last check-in which modified
                    them).
  --workdir DIR     Use DIR as the working directory instead of ".". The DIR
                    directory is created if it does not exist.

See also: close, clone

```

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

You can have multiple open connections to the same repository at the same time. Every open connection just needs to be in its own separate working directory. This is very useul when you have many branches and do not want to commit your work just to switch over to another branch and continue or check something there. Just create a new open connection in another directory and you can `cd` between them and work on multiple branches at the same time. If you want to know where all the open check-outs of your repository are located, use `fossil info -v`.

### close

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

```
$ fossil help close
Usage: fossil close ?OPTIONS?

The opposite of "open".  Close the current database connection.
Require a -f or --force flag if there are unsaved changes in the
current check-out or if there is non-empty stash.

Options:
  --force|-f  necessary to close a check out with uncommitted changes

See also: open

```

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.

### version

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

```
$ fossil help version
Usage: fossil version ?-verbose|-v?

Print the source code version number for the fossil executable.
If the verbose option is specified, additional details will
be output about what optional features this binary was compiled
with


$ fossil version
This is fossil version 2.14 [939a13d94f] 2020-11-20 19:28:05 UTC

```

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.

### rebuild

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

```
$ fossil help rebuild
Usage: fossil rebuild ?REPOSITORY? ?OPTIONS?

Reconstruct the named repository database from the core
records.  Run this command after updating the fossil
executable in a way that changes the database schema.

Options:
  --analyze         Run ANALYZE on the database after rebuilding
  --cluster         Compute clusters for unclustered artifacts
  --compress        Strive to make the database as small as possible
  --compress-only   Skip the rebuilding step. Do --compress only
  --deanalyze       Remove ANALYZE tables from the database
  --force           Force the rebuild to complete even if errors are seen
  --ifneeded        Only do the rebuild if it would change the schema version
  --index           Always add in the full-text search index
  --noverify        Skip the verification of changes to the BLOB table
  --noindex         Always omit the full-text search index
  --pagesize N      Set the database pagesize to N. (512..65536 and power of 2)
  --quiet           Only show output if there are errors
  --randomize       Scan artifacts in a random order
  --stats           Show artifact statistics after rebuilding
  --vacuum          Run VACUUM on the database after rebuilding
  --wal             Set Write-Ahead-Log journalling mode on the database

```

### repack {#f_repack}
This command was added in version 2.21. It is used to reconstruct a repository database from the core records and is typically run after updating the Fossil executable in a way that changes the database schema.

... to be continued ...

### all

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

```
$ fossil help all
Usage: fossil all SUBCOMMAND ...

The ~/.fossil file records the location of all repositories for a
user.  This command performs certain operations on all repositories
that can be useful before or after a period of disconnected operation.

On Win32 systems, the file is named "_fossil" and is located in
%LOCALAPPDATA%, %APPDATA% or %HOMEPATH%.

Available operations are:

   backup      Backup all repositories.  The argument must the name of
               a directory into which all backup repositories are written.

   cache       Manages the cache used for potentially expensive web
               pages.  Any additional arguments are passed on verbatim
               to the cache command.

   changes     Shows all local check-outs that have uncommitted changes.
               This operation has no additional options.

   clean       Delete all "extra" files in all local check-outs.  Extreme
               caution should be exercised with this command because its
               effects cannot be undone.  Use of the --dry-run option to
               carefully review the local check-outs to be operated upon
               and the --whatif option to carefully review the files to
               be deleted beforehand is highly recommended.  The command
               line options supported by the clean command itself, if any
               are present, are passed along verbatim.

   config      Only the "config pull AREA" command works.

   dbstat      Run the "dbstat" command on all repositories.

   extras      Shows "extra" files from all local check-outs.  The command
               line options supported by the extra command itself, if any
               are present, are passed along verbatim.

   fts-config  Run the "fts-config" command on all repositories.

   info        Run the "info" command on all repositories.

   pull        Run a "pull" operation on all repositories.  Only the
               --verbose option is supported.

   push        Run a "push" on all repositories.  Only the --verbose
               option is supported.

   rebuild     Rebuild on all repositories.  The command line options
               supported by the rebuild command itself, if any are
               present, are passed along verbatim.  The --force and
               --randomize options are not supported.

   sync        Run a "sync" on all repositories.  Only the --verbose
               and --unversioned options are supported.

   set|unset   Run the "setting", "set", or "unset" commands on all
               repositories.  These command are particularly useful in
               conjunction with the "max-loadavg" setting which cannot
               otherwise be set globally.

   server      Run the "ui" or "server" commands on all repositories.
   ui          The root URI gives a listing of all repos.


In addition, the following maintenance operations are supported:

   add         Add all the repositories named to the set of repositories
               tracked by Fossil.  Normally Fossil is able to keep up with
               this list by itself, but sometimes it can benefit from this
               hint if you rename repositories.

   ignore      Arguments are repositories that should be ignored by
               subsequent clean, extras, list, pull, push, rebuild, and
               sync operations.  The -c|--ckout option causes the listed
               local check-outs to be ignored instead.

   list | ls   Display the location of all repositories.  The -c|--ckout
               option causes all local check-outs to be listed instead.

Repositories are automatically added to the set of known repositories
when one of the following commands are run against the repository:
clone, info, pull, push, or sync.  Even previously ignored repositories
are added back to the list of repositories by these commands.

Options:
  --dry-run         If given, display instead of run actions.
  --showfile        Show the repository or check-out being operated upon.
  --stop-on-error   Halt immediately if any subprocess fails.

```

### push

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

```
$ fossil help push
Usage: fossil push ?URL? ?options?

Push all sharable changes from the local repository to a remote
repository.  Sharable changes include public check-ins, edits to
wiki pages, tickets, and tech-notes, as well as forum content.  Use
--private to also push private branches.  Use the "configuration
push" command to push website configuration details.

If URL is not specified, then the URL from the most recent clone, push,
pull, remote, or sync command is used.  See "fossil help clone" for
details on the URL formats.

Options:

  -B|--httpauth USER:PASS    Credentials for the simple HTTP auth protocol,
                             if required by the remote website
  --ipv4                     Use only IPv4, not IPv6
  --once                     Do not remember URL for subsequent syncs
  --proxy PROXY              Use the specified HTTP proxy
  --private                  Push private branches too
  -R|--repository REPO       Local repository to push from
  --ssl-identity FILE        Local SSL credentials, if requested by remote
  --ssh-command SSH          Use SSH as the "ssh" command
  -v|--verbose               Additional (debugging) output
  --verily                   Exchange extra information with the remote
                             to ensure no content is overlooked

See also: clone, config, pull, remote, sync

```

### pull

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

```
$ fossil help pull
Usage: fossil pull ?URL? ?options?

Pull all sharable changes from a remote repository into the local
repository.  Sharable changes include public check-ins, edits to
wiki pages, tickets, and tech-notes, as well as forum content.  Add
the --private option to pull private branches.  Use the
"configuration pull" command to pull website configuration details.

If URL is not specified, then the URL from the most recent clone, push,
pull, remote, or sync command is used.  See "fossil help clone" for
details on the URL formats.

Options:

  -B|--httpauth USER:PASS    Credentials for the simple HTTP auth protocol,
                             if required by the remote website
  --from-parent-project      Pull content from the parent project
  --ipv4                     Use only IPv4, not IPv6
  --once                     Do not remember URL for subsequent syncs
  --private                  Pull private branches too
  --project-code CODE        Use CODE as the project code
  --proxy PROXY              Use the specified HTTP proxy
  -R|--repository REPO       Local repository to pull into
  --ssl-identity FILE        Local SSL credentials, if requested by remote
  --ssh-command SSH          Use SSH as the "ssh" command
  -v|--verbose               Additional (debugging) output
  --verily                   Exchange extra information with the remote
                             to ensure no content is overlooked

See also: clone, config, push, remote, sync

```

### sync

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

```
$ fossil help sync
Usage: fossil sync ?URL? ?options?

Synchronize all sharable changes between the local repository and a
remote repository.  Sharable changes include public check-ins and
edits to wiki pages, tickets, and technical notes.

If URL is not specified, then the URL from the most recent clone, push,
pull, remote, or sync command is used.  See "fossil help clone" for
details on the URL formats.

Options:

  -B|--httpauth USER:PASS    Credentials for the simple HTTP auth protocol,
                             if required by the remote website
  --ipv4                     Use only IPv4, not IPv6
  --once                     Do not remember URL for subsequent syncs
  --proxy PROXY              Use the specified HTTP proxy
  --private                  Sync private branches too
  -R|--repository REPO       Local repository to sync with
  --ssl-identity FILE        Local SSL credentials, if requested by remote
  --ssh-command SSH          Use SSH as the "ssh" command
  -u|--unversioned           Also sync unversioned content
  -v|--verbose               Additional (debugging) output
  --verily                   Exchange extra information with the remote
                             to ensure no content is overlooked

See also: clone, pull, push, remote

```

::: GoodToKnow
Wen you want to also sync unversioned content, you need to have the corresponding user privilige (capability 'y'). The command will not tell you when you do not have this privilige and the sync will then silently fail.
:::

### clean

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

```
$ fossil help clean
Usage: fossil clean ?OPTIONS? ?PATH ...?

Delete all "extra" files in the source tree.  "Extra" files are files
that are not officially part of the check-out.  If one or more PATH
arguments appear, then only the files named, or files contained with
directories named, will be removed.

If the --prompt option is used, prompts are issued to confirm the
permanent removal of each file.  Otherwise, files are backed up to the
undo buffer prior to removal, and prompts are issued only for files
whose removal cannot be undone due to their large size or due to
--disable-undo being used.

The --force option treats all prompts as having been answered yes,
whereas --no-prompt treats them as having been answered no.

Files matching any glob pattern specified by the --clean option are
deleted without prompting, and the removal cannot be undone.

No file that matches glob patterns specified by --ignore or --keep will
ever be deleted.  Files and subdirectories whose names begin with "."
are automatically ignored unless the --dotfiles option is used.

The default values for --clean, --ignore, and --keep are determined by
the (versionable) clean-glob, ignore-glob, and keep-glob settings.

The --verily option ignores the keep-glob and ignore-glob settings and
turns on --force, --emptydirs, --dotfiles, and --disable-undo.  Use the
--verily option when you really want to clean up everything.  Extreme
care should be exercised when using the --verily option.

Options:
   --allckouts            Check for empty directories within any check-outs
                          that may be nested within the current one.  This
                          option should be used with great care because the
                          empty-dirs setting (and other applicable settings)
                          belonging to the other repositories, if any, will
                          not be checked.
   --case-sensitive BOOL  Override case-sensitive setting
   --dirsonly             Only remove empty directories.  No files will
                          be removed.  Using this option will automatically
                          enable the --emptydirs option as well.
   --disable-undo         WARNING: This option disables use of the undo
                          mechanism for this clean operation and should be
                          used with extreme caution.
   --dotfiles             Include files beginning with a dot (".").
   --emptydirs            Remove any empty directories that are not
                          explicitly exempted via the empty-dirs setting
                          or another applicable setting or command line
                          argument.  Matching files, if any, are removed
                          prior to check-ing for any empty directories;
                          therefore, directories that contain only files
                          that were removed will be removed as well.
   -f|--force             Remove files without prompting.
   -i|--prompt            Prompt before removing each file.  This option
                          implies the --disable-undo option.
   -x|--verily            WARNING: Removes everything that is not a managed
                          file or the repository itself.  This option
                          implies the --force, --emptydirs, --dotfiles, and
                          --disable-undo options. Furthermore, it
                          completely disregards the keep-glob
                          and ignore-glob settings.  However, it does honor
                          the --ignore and --keep options.
   --clean CSG            WARNING: Never prompt to delete any files matching
                          this comma separated list of glob patterns.  Also,
                          deletions of any files matching this pattern list
                          cannot be undone.
   --ignore CSG           Ignore files matching patterns from the
                          comma separated list of glob patterns.
   --keep <CSG>           Keep files matching this comma separated
                          list of glob patterns.
   -n|--dry-run           Delete nothing, but display what would have been
                          deleted.
   --no-prompt            This option disables prompting the user for input
                          and assumes an answer of 'No' for every question.
   --temp                 Remove only Fossil-generated temporary files.
   -v|--verbose           Show all files as they are removed.

See also: addremove, extras, status

```

### branch

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

```
$ fossil help branch
Usage: fossil branch SUBCOMMAND ... ?OPTIONS?

Run various subcommands to manage branches of the open repository or
of the repository identified by the -R or --repository option.

   fossil branch current

       Print the name of the branch for the current check-out

   fossil branch info BRANCH-NAME

       Print information about a branch

   fossil branch list|ls ?OPTIONS?

       List all branches. Options:
         -a|--all      List all branches.  Default show only open branches
         -c|--closed   List closed branches.
         -r            Reverse the sort order
         -t            Show recently changed branches first

   fossil branch new BRANCH-NAME BASIS ?OPTIONS?

       Create a new branch BRANCH-NAME off of check-in BASIS.
       Supported options for this subcommand include:
       --private             branch is private (i.e., remains local)
       --bgcolor COLOR       use COLOR instead of automatic background
       --nosign              do not sign contents on this branch
       --date-override DATE  DATE to use instead of 'now'
       --user-override USER  USER to use instead of the current default

       DATE may be "now" or "YYYY-MM-DDTHH:MM:SS.SSS". If in
       year-month-day form, it may be truncated, the "T" may be
       replaced by a space, and it may also name a timezone offset
       from UTC as "-HH:MM" (westward) or "+HH:MM" (eastward).
       Either no timezone suffix or "Z" means UTC.

Options valid for all subcommands:

   -R|--repository FILE       Run commands on repository FILE

```

Note, that there is no command to change a branch name. You can, however, change the name of a branch via the web interface. Just click on the first commit using the branch and then click on the 'edit' link. There's an option there to rename the branch.
### merge

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

```
$ fossil help merge
Usage: fossil merge ?OPTIONS? ?VERSION?

The argument VERSION is a version that should be merged into the
current check-out.  All changes from VERSION back to the nearest
common ancestor are merged.  Except, if either of the --cherrypick or
--backout options are used only the changes associated with the
single check-in VERSION are merged.  The --backout option causes
the changes associated with VERSION to be removed from the current
check-out rather than added.

If the VERSION argument is omitted, then Fossil attempts to find
a recent fork on the current branch to merge.

Only file content is merged.  The result continues to use the
file and directory names from the current check-out even if those
names might have been changed in the branch being merged in.

Options:

  --backout               Do a reverse cherrypick merge against VERSION.
                          In other words, back out the changes that were
                          added by VERSION.

  --baseline BASELINE     Use BASELINE as the "pivot" of the merge instead
                          of the nearest common ancestor.  This allows
                          a sequence of changes in a branch to be merged
                          without having to merge the entire branch.

  --binary GLOBPATTERN    Treat files that match GLOBPATTERN as binary
                          and do not try to merge parallel changes.  This
                          option overrides the "binary-glob" setting.

  --case-sensitive BOOL   Override the case-sensitive setting.  If false,
                          files whose names differ only in case are taken
                          to be the same file.

  --cherrypick            Do a cherrypick merge VERSION into the current
                          check-out.  A cherrypick merge pulls in the changes
                          of the single check-in VERSION, rather than all
                          changes back to the nearest common ancestor.

  -f|--force              Force the merge even if it would be a no-op.

  --force-missing         Force the merge even if there is missing content.

  --integrate             Merged branch will be closed when committing.

  -K|--keep-merge-files   On merge conflict, retain the temporary files
                          used for merging, named *-baseline, *-original,
                          and *-merge.

  -n|--dry-run            If given, display instead of run actions

  -v|--verbose            Show additional details of the merge

```

### tag

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

```
$ fossil help tag
Usage: fossil tag SUBCOMMAND ...

Run various subcommands to control tags and properties.

  fossil tag add ?OPTIONS? TAGNAME CHECK-IN ?VALUE?

        Add a new tag or property to CHECK-IN. The tag will
        be usable instead of a CHECK-IN in commands such as
        update and merge.  If the --propagate flag is present,
        the tag value propagates to all descendants of CHECK-IN

        Options:
          --raw                       Raw tag name.
          --propagate                 Propagating tag.
          --date-override DATETIME    Set date and time added.
          --user-override USER        Name USER when adding the tag.
          --dryrun|-n                 Display the tag text, but do not
                                      actually insert it into the database.

        The --date-override and --user-override options support
        importing history from other SCM systems. DATETIME has
        the form 'YYYY-MMM-DD HH:MM:SS'.

  fossil tag cancel ?--raw? TAGNAME CHECK-IN

        Remove the tag TAGNAME from CHECK-IN, and also remove
        the propagation of the tag to any descendants.  Use the
        the --dryrun or -n options to see what would have happened.

        Options:
          --raw                       Raw tag name.
          --date-override DATETIME    Set date and time deleted.
          --user-override USER        Name USER when deleting the tag.
          --dryrun|-n                 Display the control artifact, but do
                                      not insert it into the database.

  fossil tag find ?OPTIONS? TAGNAME

        List all objects that use TAGNAME.  TYPE can be "ci" for
        check-ins or "e" for events. The limit option limits the number
        of results to the given value.

        Options:
          --raw           Raw tag name.
          -t|--type TYPE  One of "ci", or "e".
          -n|--limit N    Limit to N results.

  fossil tag list|ls ?OPTIONS? ?CHECK-IN?

        List all tags, or if CHECK-IN is supplied, list
        all tags and their values for CHECK-IN.  The tagtype option
        takes one of: propagated, singleton, cancel.

        Options:
          --raw           List tags raw names of tags
          --tagtype TYPE  List only tags of type TYPE
          -v|--inverse    Inverse the meaning of --tagtype TYPE.

The option --raw allows the manipulation of all types of tags
used for various internal purposes in fossil. It also shows
"cancel" tags for the "find" and "list" subcommands. You should
not use this option to make changes unless you are sure what
you are doing.

If you need to use a tagname that might be confused with
a hexadecimal baseline or artifact ID, you can explicitly
disambiguate it by prefixing it with "tag:". For instance:

  fossil update decaf

will be taken as an artifact or baseline ID and fossil will
probably complain that no such revision was found. However

  fossil update tag:decaf

will assume that "decaf" is a tag/branch name.

```

### settings

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

```
$ fossil help settings
Usage: fossil settings ?SETTING? ?VALUE? ?OPTIONS?
   or: fossil unset SETTING ?OPTIONS?

The "settings" command with no arguments lists all settings and their
values.  With just a SETTING name it shows the current value of that setting.
With a VALUE argument it changes the property for the current repository.

Settings marked as versionable are overridden by the contents of the
file named .fossil-settings/PROPERTY in the check-out root, if that
file exists.

The "unset" command clears a setting.

Settings can have both a "local" repository-only value and "global" value
that applies to all repositories.  The local values are stored in the
"config" table of the repository and the global values are stored in the
configuration database.  If both a local and a global value exists for a
setting, the local value takes precedence.  This command normally operates
on the local settings.  Use the --global option to change global settings.

Options:
  --global   set or unset the given property globally instead of
             setting or unsetting it for the open repository only.

  --exact    only consider exact name matches.

See also: configuration

```

### info

```
fossil info ?VERSION | REPOSITORY_FILENAME? ?OPTIONS?
```

This command show various information on the repository, a bit like the `status` command does. Using the command without any arguments, it shows information on the current check-out:

- name of the project and its code (hash value)
- path to the repository
- path to Fossil's global configuration database for the user (typically `~./fossil`)
- path to the local open check-out
- id and time stamp of the last check-out, its parent and child
- tags
- last commit message

When you do not want information on the last check-in, but on other versions, you just supply the version on the command line. You can also explicitly provide the repository file with the `-R` option. Then you will only get the project name and code and the number of chek-ins.

The `-v` option is helpful since it provides not only the above information on the current check-out but also tells you the locations of all other known check-outs there are (if you have multiple open check-outs of the same repository in different directories). It also lists the possible access URLs that have been used over time (for the ui).

<!-- what are the dates in the second column of the output referring to? Date of last commit or acces (in case of URLs)? -->

### publish {#f_publish}

```
fossil publish ?--only? TAGS...
```

This command causes artifacts identified by the given `TAGS...` (these can be more than one tag) to be published (i.e. made non-private). This can be used (for example) to convert a [private](#f_branch) branch into a public branch, or to publish a bundle that was imported privately.

If any of `TAGS` names a branch, then all check-ins on the most recent instance of that branch are included, not just the most recent check-in.

If any of `TAGS` name check-ins then all files and tags associated with those check-ins are also published automatically. If the `--only` option is used, then only the specific artifacts identified by `TAGS` are published.

If a `TAG` is already public, this command is a harmless no-op.


## Miscellaneous

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

### zip

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

```
$ fossil help zip
Usage: fossil zip VERSION OUTPUTFILE [OPTIONS]

Generate a ZIP archive for a check-in.  If the --name option is
used, its argument becomes the name of the top-level directory in the
resulting ZIP archive.  If --name is omitted, the top-level directory
name is derived from the project name, the check-in date and time, and
the artifact ID of the check-in.

The GLOBLIST argument to --exclude and --include can be a comma-separated
list of glob patterns, where each glob pattern may optionally be enclosed
in "..." or '...' so that it may contain commas.  If a file matches both
--include and --exclude then it is excluded.

Options:
  -X|--exclude GLOBLIST   Comma-separated list of GLOBs of files to exclude
  --include GLOBLIST      Comma-separated list of GLOBs of files to include
  --name DIRECTORYNAME    The name of the top-level directory in the archive
  -R REPOSITORY           Specify a Fossil repository

```

Note: you can only download zip files when you have the corresponding user privilige.

### user

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

```
$ fossil help user
Usage: fossil user SUBCOMMAND ...  ?-R|--repository FILE?

Run various subcommands on users of the open repository or of
the repository identified by the -R or --repository option.

  fossil user capabilities USERNAME ?STRING?

       Query or set the capabilities for user USERNAME

  fossil user contact USERNAME ?CONTACT-INFO?

       Query or set contact information for user USERNAME

  fossil user default ?USERNAME?

       Query or set the default user.  The default user is the
       user for command-line interaction.

  fossil user list
  fossil user ls

       List all users known to the repository

  fossil user new ?USERNAME? ?CONTACT-INFO? ?PASSWORD?

       Create a new user in the repository.  Users can never be
       deleted.  They can be denied all access but they must continue
       to exist in the database.

  fossil user password USERNAME ?PASSWORD?

       Change the web access password for a user.

```

### finfo

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

```
$ fossil help finfo
Usage: fossil finfo ?OPTIONS? FILENAME

Print the complete change history for a single file going backwards
in time.  The default mode is -l.

For the -l|--log mode: If "-b|--brief" is specified one line per revision
is printed, otherwise the full comment is printed.  The "-n|--limit N"
and "--offset P" options limits the output to the first N changes
after skipping P changes.

In the -s mode prints the status as <status> <revision>.  This is
a quick status and does not check for up-to-date-ness of the file.

In the -p mode, there's an optional flag "-r|--revision REVISION".
The specified version (or the latest checked out version) is printed
to stdout.  The -p mode is another form of the "cat" command.

Options:
  -b|--brief           display a brief (one line / revision) summary
  --case-sensitive B   Enable or disable case-sensitive filenames.  B is a
                       boolean: "yes", "no", "true", "false", etc.
  -l|--log             select log mode (the default)
  -n|--limit N         Display the first N changes (default unlimited).
                       N less than 0 means no limit.
  --offset P           skip P changes
  -p|--print           select print mode
  -r|--revision R      print the given revision (or ckout, if none is given)
                       to stdout (only in print mode)
  -s|--status          select status mode (print a status indicator for FILE)
  -W|--width N         Width of lines (default is to auto-detect). Must be
                       more than 22 or else 0 to indicate no limit.

See also: artifact, cat, descendants, info, leaves

```

An example would be to run it on the outline.txt file in the earlier version of our book directory:


```
$ fossil finfo outline.txt

    History of outline.txt
    
    2010-05-17 [0272dc0169] Finished maintenance commands (user: jim, artifact:
    
    {}           [25b6e38e97])
    
    2010-05-12 [5e5c0f7d55] End of day commit (user: jim, artifact: [d1a1d31fbd])
    
    2010-05-10 [e924ca3525] End of day update (user: jim, artifact: [7cd19079a1])
    
    2010-05-09 [0abb95b046] Intermediate commit, not done with basic commands
    
    {}           (user: jim, artifact: [6f7bcd48b9])
    
    2010-05-07 [6921e453cd] Update outline & book corrections (user: jim,
    
    {}           artifact: [4eff85c793])
    
    2010-05-03 [158492516c] Moved to clone repository (user: jim, artifact:
    
    {}           [23b729cb66])
    
    2010-05-03 [1a403c87fc] Update before moving to server (user: jim, artifact:
    
    {}           [706a9d394d])
    
    2010-04-30 [fa5b9247bd] Working on chapter 1 (user: jim, artifact:
    
    {}           [7bb188f0c6])
    
    2010-04-29 [51be6423a3] Update outline (user: jim, artifact: [7cd39dfa06])
    
    2010-04-27 [39bc728527] [1665c78d94] Ticket Use (user: jim, artifact:
    
    {}           [1f82aaf41c])
    
    2010-04-26 [497b93858f] Update to catch changes in outline (user: jim,
    
    {}           artifact: [b870231e48])
    
    2010-04-25 [8fa0708186] Initial Commit (user: jim, artifact: [34a460a468])
```

### timeline

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

```
$ fossil help timeline
Usage: fossil timeline ?WHEN? ?check-in|DATETIME? ?OPTIONS?

Print a summary of activity going backwards in date and time
specified or from the current date and time if no arguments
are given.  The WHEN argument can be any unique abbreviation
of one of these keywords:

    before
    after
    descendants | children
    ancestors | parents

The check-in can be any unique prefix of 4 characters or more. You
can also say "current" for the current version.

DATETIME may be "now" or "YYYY-MM-DDTHH:MM:SS.SSS". If in
year-month-day form, it may be truncated, the "T" may be replaced by
a space, and it may also name a timezone offset from UTC as "-HH:MM"
(westward) or "+HH:MM" (eastward). Either no timezone suffix or "Z"
means UTC.


Options:
  -n|--limit N         If N is positive, output the first N entries.  If
                       N is negative, output the first -N lines.  If N is
                       zero, no limit.  Default is -20 meaning 20 lines.
  -p|--path PATH       Output items affecting PATH only.
                       PATH can be a file or a sub directory.
  --offset P           skip P changes
  --sql                Show the SQL used to generate the timeline
  -t|--type TYPE       Output items from the given types only, such as:
                           ci = file commits only
                           e  = technical notes only
                           t  = tickets only
                           w  = wiki commits only
  -v|--verbose         Output the list of files changed by each commit
                       and the type of each change (edited, deleted,
                       etc.) after the check-in comment.
  -W|--width N         Width of lines (default is to auto-detect). N must be
                       either greater than 20 or it ust be zero 0 to
                       indicate no limit, resulting in a single line per
                       entry.
  -R REPO_FILE         Specifies the repository db to use. Default is
                       the current check-out's repository.

```

### wiki

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

```
$ fossil help wiki
Usage: fossil wiki (export|create|commit|list) WikiName

Run various subcommands to work with wiki entries or tech notes.

  fossil wiki export ?OPTIONS? PAGENAME ?FILE?
  fossil wiki export ?OPTIONS? -t|--technote DATETIME|TECHNOTE-ID ?FILE?

      Sends the latest version of either a wiki page or of a tech
      note to the given file or standard output.  A filename of "-"
      writes the output to standard output.  The directory parts of
      the output filename are created if needed.
      If PAGENAME is provided, the named wiki page will be output.

      Options:
        --technote|-t DATETIME|TECHNOTE-ID
                   Specifies that a technote, rather than a wiki page,
                   will be exported. If DATETIME is used, the most
                   recently modified tech note with that DATETIME will
                   output.
        -h|--html  The body (only) is rendered in HTML form, without
                   any page header/foot or HTML/BODY tag wrappers.
        -H|--HTML  Works like -h|-html but wraps the output in
                   <html><body>...</body></html>.
        -p|--pre   If -h|-H is used and the page or technote has
                   the text/plain mimetype, its HTML-escaped output
                   will be wrapped in <pre>...</pre>.

  fossil wiki (create|commit) PAGENAME ?FILE? ?OPTIONS?

      Create a new or commit changes to an existing wiki page or
      technote from FILE or from standard input. PAGENAME is the
      name of the wiki entry or the timeline comment of the
      technote.

      Options:
        -M|--mimetype TEXT-FORMAT   The mime type of the update.
                                    Defaults to the type used by
                                    the previous version of the
                                    page, or text/x-fossil-wiki.
                                    Valid values are: text/x-fossil-wiki,
                                    text/x-markdown and text/plain. fossil,
                                    markdown or plain can be specified as
                                    synonyms of these values.
        -t|--technote DATETIME      Specifies the timestamp of
                                    the technote to be created or
                                    updated. When updating a tech note
                                    the most recently modified tech note
                                    with the specified timestamp will be
                                    updated.
        -t|--technote TECHNOTE-ID   Specifies the technote to be
                                    updated by its technote id.
        --technote-tags TAGS        The set of tags for a technote.
        --technote-bgcolor COLOR    The color used for the technote
                                    on the timeline.

  fossil wiki list ?OPTIONS?
  fossil wiki ls ?OPTIONS?

      Lists all wiki entries, one per line, ordered
      case-insensitively by name.

      Options:
        -t|--technote               Technotes will be listed instead of
                                    pages. The technotes will be in order
                                    of timestamp with the most recent
                                    first.
        -s|--show-technote-ids      The id of the tech note will be listed
                                    along side the timestamp. The tech note
                                    id will be the first word on each line.
                                    This option only applies if the
                                    --technote option is also specified.

DATETIME may be "now" or "YYYY-MM-DDTHH:MM:SS.SSS". If in
year-month-day form, it may be truncated, the "T" may be replaced by
a space, and it may also name a timezone offset from UTC as "-HH:MM"
(westward) or "+HH:MM" (eastward). Either no timezone suffix or "Z"
means UTC.

The "Sandbox" wiki pseudo-page is a special case. Its name is
checked case-insensitively and either "create" or "commit" may be
used to update its contents.

```

## Advanced

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

### uv
This command handles unversioned content, i.e. files (also binary files) that you want to provide via fossil but that are not part of the versioned files. A typical example is release files (binary distributions from the source code).

### scrub

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

```
$ fossil help scrub
Usage: fossil scrub ?OPTIONS? ?REPOSITORY?

The command removes sensitive information (such as passwords) from a
repository so that the repository can be sent to an untrusted reader.

By default, only passwords are removed.  However, if the --verily option
is added, then private branches, concealed email addresses, IP
addresses of correspondents, and similar privacy-sensitive fields
are also purged.  If the --private option is used, then only private
branches are removed and all other information is left intact.

This command permanently deletes the scrubbed information. THE EFFECTS
OF THIS COMMAND ARE NOT REVERSIBLE. USE WITH CAUTION!

The user is prompted to confirm the scrub unless the --force option
is used.

Options:
  --force     do not prompt for confirmation
  --private   only private branches are removed from the repository
  --verily    scrub real thoroughly (see above)

```

### search

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

```
$ fossil help search
Usage: fossil search [-all|-a] [-limit|-n #] [-width|-W #] pattern...

Search for timeline entries matching all words provided on the
command line. Whole-word matches scope more highly than partial
matches.

Note:  The command only search the EVENT table.  So it will only
display check-in comments or other comments that appear on an
unaugmented timeline.  It does not search document text or forum
messages.

Outputs, by default, some top-N fraction of the results. The -all
option can be used to output all matches, regardless of their search
score.  The -limit option can be used to limit the number of entries
returned.  The -width option can be used to set the output width used
when printing matches.

Options:

    -a|--all          Output all matches, not just best matches.
    -n|--limit N      Limit output to N matches.
    -W|--width WIDTH  Set display width to WIDTH columns, 0 for
                      unlimited. Defaults the terminal's width.

```

### sha3sum

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.

```
$ fossil help sha3sum
Usage: fossil sha3sum FILE...

Compute an SHA3 checksum of all files named on the command-line.
If a file is named "-" then take its content from standard input.

To be clear:  The official NIST FIPS-202 implementation of SHA3
with the added 01 padding is used, not the original Keccak submission.

Options:

   --224               Compute a SHA3-224 hash
   --256               Compute a SHA3-256 hash (the default)
   --384               Compute a SHA3-384 hash
   --512               Compute a SHA3-512 hash
   --size N            An N-bit hash.  N must be a multiple of 32 between
                       128 and 512.
   -h, --dereference   If FILE is a symbolic link, compute the hash on
                       the object pointed to, not on the link itself.

See also: md5sum, sha1sum

```

### configuration {#f_configuration}

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

```
$ fossil help configuration
Usage: fossil configuration METHOD ... ?OPTIONS?

Where METHOD is one of: export import merge pull push reset.  All methods
accept the -R or --repository option to specify a repository.

   fossil configuration export AREA FILENAME

        Write to FILENAME exported configuration information for AREA.
        AREA can be one of:

            all email interwiki project shun skin
            ticket user alias subscriber

   fossil configuration import FILENAME

        Read a configuration from FILENAME, overwriting the current
        configuration.

   fossil configuration merge FILENAME

        Read a configuration from FILENAME and merge its values into
        the current configuration.  Existing values take priority over
        values read from FILENAME.

   fossil configuration pull AREA ?URL?

        Pull and install the configuration from a different server
        identified by URL.  If no URL is specified, then the default
        server is used.  Use the --overwrite flag to completely
        replace local settings with content received from URL.

   fossil configuration push AREA ?URL?

        Push the local configuration into the remote server identified
        by URL.  Admin privilege is required on the remote server for
        this to work.  When the same record exists both locally and on
        the remote end, the one that was most recently changed wins.

   fossil configuration reset AREA

        Restore the configuration to the default.  AREA as above.

   fossil configuration sync AREA ?URL?

        Synchronize configuration changes in the local repository with
        the remote repository at URL.

Options:
   -R|--repository FILE       Extract info from repository FILE

See also: settings, unset

```

### descendants

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

```
$ fossil help descendants
Usage: fossil descendants ?check-in? ?OPTIONS?

Find all leaf descendants of the check-in specified or if the argument
is omitted, of the check-in currently checked out.

Options:
   -R|--repository FILE       Extract info from repository FILE
   -W|--width N               Width of lines (default is to auto-detect).
                              Must be greater than 20 or else 0 for no
                              limit, resulting in a one line per entry.

See also: finfo, info, leaves

```
