Fossil commands
Introduction
This section will go through the various Fossil command line commands. This will be divided into sections, the first will detail the must know commands. These are the ones you will be using all the time and will probably have memorized in short order. The other commands will be divided into Maintenance, Advanced, and Miscellaneous. These you will probably be checking as reference before use.
The most important command is help. You can always type fossil help at the command line and it will list out 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 section of the book will try to supplement the built in help with some examples and further explanation of what a command does. All of the commands will be placed in the index for easy searching
NOTE: Fossil is a moving target, commands might be added and others removed future versions. Type fossil help on your version to get the latest list. The following applies to the fossil I used when I wrote this and your version might be different.
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
Here is the help listing of ALL the available commands:
$ fossil help -all
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
These options can be used when TOPIC is present:
-h|--html Format output as HTML rather than plain text
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 checkout 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 checkout, 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 checkout.
This supersedes the --hard option.
--hard Remove files from the checkout.
--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 checkout, 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 checkout.
This supersedes the --hard option.
--hard Move files within the checkout.
--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 checkout. 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 checkout. 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 checkout 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 checkout. 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, checkout, 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 checkout to VERSION. Any
uncommitted changes are retained and applied to the new checkout.
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 checkout are subject
to being updated and the version of the current checkout is changed
to VERSION. Any uncommitted changes are retained and applied to the
new checkout.
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 checkout 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
checkin 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.
checkout or co
This command is similar to update.
$ fossil help checkout
Usage: fossil checkout ?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 checkout 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 checkout the
latest version in the repository.
Options:
--force Ignore edited files in the current checkout
--keep Only update the manifest and manifest.uuid files
--force-missing Force checkout even if content is missing
--setmtime Set timestamps of all files to match their SCM-side
times (the timestamp of the last checkin 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 checkout 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 checkout.
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 checkout.
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
checkout. 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 checking 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 checkout. 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 checkout 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 checkout
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 checkout as being empty, but still connected
with the local repository. If you commit this checkout,
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 checkout
--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 checkin 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.
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
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 checkouts that have uncommitted changes.
This operation has no additional options.
clean Delete all "extra" files in all local checkouts. 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 checkouts 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 checkouts. 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 checkouts to be ignored instead.
list | ls Display the location of all repositories. The -c|--ckout
option causes all local checkouts 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 checkout 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
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 checkout. 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 checkouts
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 checking 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
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 checkout. 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
checkout 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 checkout 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
checkout. 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
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
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? ?CHECKIN|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 CHECKIN 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 checkout'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.
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
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 ?CHECKIN? ?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