Command Line Interface Reference

This is an easy introduction to the fossil command line interface (cli). It assumes some familiarity with using the command line, and with Source Code Maintenence (SCM) systems—but not too much.
If you are trying to find information about fossil's web capabilities, see the Fossil Home and Fossil Wiki pages for pointers.

Things to note

* Fossil cli commands do not use special delimeters, they use spaces. This is traditional with VCS/SCM. Some options to fossil commands do use special delimiters, particularly the '-' (hyphen, or dash) character. This is very similar to Tcl. Think of fossil as a shell you invoke and feed a command to, including any options, and it will make more sense.
* Any fossil command is acceptable once enough of it has been entered to make the intent unambiguous. 'clo' is a proper prefix of both the 'clone' and 'close' commands, for instance, but 'clon' is enough to make the intent—the 'clone' command—unambiguous.
* Pragmatically, a version in fossil is a 40-character long string of hexadecimal. fossil will be able to figure out which version you want with any distinct prefix of that string which is at least four characters long. Commands which require a version are looking for the string, a distinct prefix of the string, or a tag.
* SCM in a distributed environment can be a bit confusing with regard to branching, merging, and versions in general. See the explanation of branching and it will all make much more sense.
* Op.Ed. An excellent way to learn to use fossil effectively is to clone the repository for fossil itself. You can then poke around using the fossil ui command, and look things up with no connection worries. You can set up test repositories and try things out on-the-fly to see how they work, using their own ui's. The CLI will far easier to understand if you can run a repository, watch it in a browser, and hack around with it in a simplified environment (your tests) with guaranteed and fast access to the sources & docs (your cloned fossil repository).

You should probably start interacting with fossil at the command line by asking it what it can do:    ˆ
$ fossil help
Usage: fossil help COMMAND.
Available COMMANDs:
add* co* http rebuild sync*
all* commit info reconstruct tag
branch configuration leaves redo timeline
cgi* deconstruct ls* rename* ui
changes* del* merge revert undo
checkout* descendants mv* rm* unset
ci diff new* rstats update*
clean extra* open server user
clone gdiff pull settings version*
close help push status* wiki
This is fossil version [a89b436bc9] 2009-02-11 05:00:02 UTC
What follows is a survey of what you get if you type fossil help command for all of the commands listed above. There are links to individual pages for each of them; pages with content (commands marked with a '*' are done) go into the reason for a command in a bit more depth than the program help.

ˆ Usage: fossil add FILE... Make arrangements to add one or more files to the current checkout at the next commit.
ˆ Usage: fossil all (list|pull|push|rebuild|sync) 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 disconnection operation. Available operations are: list Display the location of all repositories pull Run a "pull" operation on all repositories push Run a "push" on all repositories rebuild Rebuild on all repositories sync Run a "sync" on all repositories Respositories are automatically added to the set of known repositories when one of the following commands against the repository: clone, info, pull, push, or sync
ˆ Usage: fossil branch SUBCOMMAND ... ?-R|--repository FILE? Run various subcommands on the branches of the open repository or of the repository identified by the -R or --repository option. fossil branch new BRANCH-NAME BASIS ?-bgcolor COLOR? Create a new branch BRANCH-NAME off of check-in BASIS. You can optionally give the branch a default color. fossil branch list List all branches
ˆ Usage: fossil cgi SCRIPT The SCRIPT argument is the name of a file that is the CGI script that is being run. The command name, "cgi", may be omitted if the GATEWAY_INTERFACE environment variable is set to "CGI" (which should always be the case for CGI scripts run by a webserver.) The SCRIPT file should look something like this: #!/usr/bin/fossil repository: /home/somebody/project.db The second line defines the name of the repository. After locating the repository, fossil will generate a webpage on stdout based on the values of standard CGI environment variables.
ˆ Usage: fossil changes Report on the edit status of all files in the current checkout. See also the "status" and "extra" commands.
ˆ Usage: fossil checkout VERSION ?-f|--force? Check out a version specified on the command-line. This command will not overwrite edited files in the current checkout unless the --force option appears on the command-line. See also the "update" command.
ˆ Usage: fossil commit ?-m COMMENT? ?--nosign? ?FILE...? fossil ci ... (as above) 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 "-m" option is used to specify a comment line. You will be prompted for your GPG passphrase in order to sign the new manifest unless the "--nosign" options is used. All files that have changed will be committed unless some subset of files is specified on the command line.
ˆ Usage: fossil clean ?-all? Delete all "extra" files in the source tree. "Extra" files are files that are not officially part of the checkout. See also the "extra" command. This operation cannot be undone. You will be prompted before removing each file. If you are sure you wish to remove all "extra" files you can specify the optional -all flag.
ˆ Usage: fossil clone URL FILENAME Make a clone of a repository specified by URL in the local file named FILENAME.
ˆ Usage: fossil close ?-f|--force? The opposite of "open". Close the current database connection. Require a -f or --force flag if there are unsaved changed in the current check-out.
ˆ Usage: fossil configuration METHOD ... Where METHOD is one of: export import merge pull push reset. All methods accept the -R or --repository option to specific a repository. fossil configuration export AREA FILENAME Write to FILENAME exported configuraton information for AREA. AREA can be one of: all ticket skin project 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. 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. fossil configuration reset AREA Restore the configuration to the default. AREA as above. WARNING: Do not import, merge, or pull configurations from an untrusted source. The inbound configuration is not checked for safety and can introduce security vulnerabilities.
ˆ COMMAND: deconstruct Usage: fossil deconstruct ?-R|--repository REPOSITORY? DESTINATION Populates the indicated DESTINATION directory with copies of all artifcats contained within the repository. Artifacts are named AA/bbbbb where AA is the first 2 characters of the artifact ID and bbbbb is the remaining 38 characters.
ˆ Usage: fossil rm FILE... or: fossil del FILE... Remove one or more files from the tree.
ˆ Usage: fossil descendants ?CHECKIN-ID? Find all leaf descendants of the check-in specified or if the argument is omitted, of the check-in currently checked out.
ˆ Usage: fossil diff|gdiff ?-i? ?-r REVISION? FILE... Show the difference between the current version of a file (as it exists on disk) and that same file as it was checked out. diff will show a textual diff while gdiff will attempt to run a graphical diff command that you have setup. If the choosen command is not yet configured, the internal textual diff command will be used. If -i is supplied for either diff or gdiff, the internal textual diff command will be executed. Here are a few external diff command settings, for example: fossil setting diff-command diff fossil setting gdiff-command tkdiff fossil setting gdiff-command eskill22 fossil setting gdiff-command tortoisemerge fossil setting gdiff-command meld fossil setting gdiff-command xxdiff fossil setting gdiff-command kdiff3
ˆ Usage: fossil extra Print a list of all files in the source tree that are not part of the current checkout. See also the "clean" command.
ˆ Usage: fossil help COMMAND Display information on how to use COMMAND
ˆ Usage: fossil http REPOSITORY Handle a single HTTP request appearing on stdin. The resulting webpage is delivered on stdout. This method is used to launch an HTTP request handler from inetd, for example. The argument is the name of the repository.
ˆ Usage: fossil info ?ARTIFACT-ID|FILENAME? With no arguments, provide information about the current tree. If an argument is specified, provide information about the object in the respository of the current tree that the argument refers to. Or if the argument is the name of a repository, show information about that repository.
ˆ Usage: fossil leaves Find leaves of all branches.
ˆ Usage: fossil ls Show the names of all files in the current checkout
ˆ Usage: fossil merge VERSION The argument is a version that should be merged into the current checkout. 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.
ˆ Usage: fossil mv|rename OLDNAME NEWNAME or: fossil mv|rename OLDNAME... DIR Move or rename one or more files within the tree This command does not rename the files on disk. All this command does is record the fact that filenames have changed so that appropriate notations can be made at the next commit/checkin.
ˆ Usage: fossil new 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.
ˆ Usage: fossil open FILENAME Open a connection to the local repository in FILENAME. A checkout for the repository is created with its root at the working directory. See also the "close" command.
ˆ Usage: fossil rstats Deliver a report of the repository statistics for the current checkout.
ˆ Usage: fossil pull ?URL? ?-R|--respository REPOSITORY? Pull changes in a remote repository into the local repository. The repository is identified by the -R or --repository option. If there is no such option then the open repository is used. The URL of the remote server is specified on the command line If no URL is specified then the URL used by the most recent "pull", "push", or "sync" command is used. The URL is of the following form: http://USER@HOST:PORT/PATH The "USER@" and ":PORT" substrings are optional. The "USER" substring specifies the login user. You will be prompted for the password on the command-line. The PORT specifies the TCP port of the server. The default port is 80.
ˆ Usage: fossil push ?URL? ?-R|--repository REPOSITORY? Push changes in the local repository over into a remote repository. See the "pull" command for additional information.
ˆ Usage: fossil rebuild REPOSITORY 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.
ˆ COMMAND: reconstruct Usage: fossil reconstruct REPOSITORY ORIGIN Creates the REPOSITORY and populates it with the artifacts in the indicated ORIGIN directory.
ˆ Usage: fossil redo ?FILENAME...? Redo the an update or merge operation that has been undone by the undo command. If FILENAME is specified then restore the changes associated with the named file(s) but otherwise leave the update or merge undone. A single level of undo/redo is supported. The undo/redo stack is cleared by the commit and checkout commands.
ˆ Usage: fossil revert ?--yes? ?-r CHECKIN? FILE Revert to the current repository version of FILE, or to the version associated with check-in CHECKIN if the -r flag appears. This command will confirm your operation unless the file is missing or the --yes option is used.
ˆ Usage: fossil server ?-P|--port TCPPORT? ?REPOSITORY? Or: fossil ui ?-P|--port TCPPORT? ?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.
ˆ COMMAND: settings COMMAND: unset Usage: fossil setting ?PROPERTY? ?VALUE? ?-global? fossil unset PROPERTY ?-global? The "setting" command with no arguments lists all properties and their values. With just a property name it shows the value of that property. With a value argument it changes the property for the current repository. The "unset" command clears a property setting. autosync If enabled, automatically pull prior to commit or update and automatically push after commit or tag or branch creation. diff-command External command to run when performing a diff. If undefined, the internal text diff will be used. editor Text editor command used for check-in comments. http-port The TCP/IP port number to use by the "server" and "ui" commands. Default: 8080 gdiff-command External command to run when performing a graphical diff. If undefined, text diff will be used. localauth If enabled, require that HTTP connections from be authenticated by password. If false, all HTTP requests from localhost have unrestricted access to the repository. clearsign When enabled (the default), fossil will attempt to sign all commits with gpg. When disabled, commits will be unsigned. pgp-command Command used to clear-sign manifests at check-in. The default is "gpg --clearsign -o ". mtime-changes Use file modification times (mtimes) to detect when files have been modified. proxy URL of the HTTP proxy. If undefined or "on" then the "http_proxy" environment variable is consulted. If the http_proxy environment variable is undefined then a direct HTTP connection is used. web-browser A shell command used to launch your preferred web browser when given a URL as an argument. Defaults to "start" on windows, "open" on Mac, and "firefox" on Unix.
ˆ Usage: fossil status Report on the status of the current checkout.
ˆ Usage: fossil sync ?URL? ?-R|--repository REPOSITORY? Synchronize the local repository with a remote repository. This is the equivalent of running both "push" and "pull" at the same time. See the "pull" command for additional information.
ˆ Usage: fossil tag SUBCOMMAND ... Run various subcommands to control tags and properties fossil tag add ?--raw? 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. fossil tag branch ?--raw? ?--nofork? TAGNAME CHECK-IN ?VALUE? A fork will be created so that the new checkin is a sibling of CHECK-IN and identical to it except for a generated comment. Then the new tag will be added to the new checkin and propagated to all direct children. Additionally all symbolic tags of that checkin inherited from CHECK-IN will be cancelled. However, if the option --nofork is given, no fork will be created and the tag/property will be added to CHECK-IN directly. No tags will be canceled. 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. fossil tag find ?--raw? TAGNAME List all check-ins that use TAGNAME fossil tag list ?--raw? ?CHECK-IN? List all tags, or if CHECK-IN is supplied, list all tags and their values for CHECK-IN. The option --raw allows the manipulation of all types of tags used for various internal purposes in fossil. 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 check-in 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 check-in 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.
ˆ Usage: fossil timeline ?WHEN? ?CHECK-IN|DATETIME? ?-n|--count N? Print a summary of activity going backwards in date and time specified or from the current date and time if no arguments are given. Show as many as N (default 20) check-ins. 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. The DATETIME should be in the ISO8601 format. For examples: "2007-08-18 07:21:21". You can also say "current" for the current version or "now" for the current time.
ˆ Usage: fossil undo ?FILENAME...? Undo the most recent update or merge operation. If FILENAME is specified then restore the content of the named file(s) but otherwise leave the update or merge in effect. A single level of undo/redo is supported. The undo/redo stack is cleared by the commit and checkout commands.
ˆ Usage: fossil update ?VERSION? ?--latest? The optional argument is a version that should become the current version. If the argument is omitted, then use the leaf of the tree that begins with the current version, if there is only a single leaf. If there are a multiple leaves, the latest is used if the --latest flag is present. This command is different from the "checkout" in that edits are not overwritten. Edits are merged into the new version.
ˆ 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 default ?USERNAME? Query or set the default user. The default user is the user for command-line interaction. fossil user list List all users known to the repository fossil user new ?USERNAME? 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 Change the web access password for a user.
ˆ Usage: fossil version Print the source code version number for the fossil executable.
ˆ Usage: fossil wiki (export|create|commit|list) WikiName Run various subcommands to fetch wiki entries. fossil wiki export PAGENAME ?FILE? Sends the latest version of the PAGENAME wiki entry to the given file or standard output. fossil wiki commit PAGENAME ?FILE? Commit changes to a wiki page from FILE or from standard. fossil wiki create PAGENAME ?FILE? Create a new wiki page with initial content taken from FILE or from standard input. fossil wiki list Lists all wiki entries, one per line, ordered case-insentively by name. TODOs: fossil wiki export ?-u ARTIFACT? WikiName ?FILE? Outputs the selected version of WikiName. fossil wiki delete ?-m MESSAGE? WikiName The same as deleting a file entry, but i don't know if fossil supports a commit message for Wiki entries. fossil wiki ?-u? ?-d? ?-s=[|]? list Lists the artifact ID and/or Date of last change along with each entry name, delimited by the -s char. fossil wiki diff ?ARTIFACT? ?-f infile[=stdin]? EntryName Diffs the local copy of a page with a given version (defaulting to the head version).



This is not actually a reference, it's the start of a reference. There are wikilinks to uncreated pages for the commands. This was created by running the fossil help for each command listed by running fossil help... Duplicate commands are only listed once (I think). There are several bits of fossil that are not addressed in the help for commands (special wiki directories, special users, etc.) so they are (currently) not addressed here. Clarity and brevity may be sacrificed for expediency at the authors indiscretion. All spelling and grammatical mistakes are somebody elses fault. void * prohibited where __C_PLUS_PLUS__ . Title and taxes extra. Not valid in Hooptigonia.