- /.well-known (web page)
-
If the "--acme" option was supplied to "fossil server" or "fossil http" or
similar, then this page returns the content of files found in the
".well-known" subdirectory of the same directory that contains the
repository file. This facilitates Automated Certificate
Management using tools like "certbot".
The content is returned directly, without any interpretation, using a generic mimetype.
- /access_log (web page)
- /user_log (web page)
-
Show login attempts, including timestamp and IP address.
Requires Admin privileges.
Query parameters:
- y=N
- 1: success only. 2: failure only. 3: both (default: 3)
- n=N
- Number of entries to show (default: 200)
- o=N
- Skip this many entries (default: 0)
- /admin_log (web page)
- Shows the contents of the admin_log table, which is only created if the admin-log setting is enabled. Requires Admin or Setup ('a' or 's') permissions.
- /admin_sql (web page)
- Run raw SQL commands against the database file using the web interface. Requires Setup privileges.
- /admin_th1 (web page)
- Run raw TH1 commands using the web interface. If Tcl integration was enabled at compile-time and the "tcl" setting is enabled, Tcl commands may be run as well. Requires Admin privilege.
- /ainfo (web page)
-
URL: /ainfo?name=ARTIFACTID
Show the details of an attachment artifact.
- /alerts (web page)
-
Edit email alert and notification settings.
The subscriber is identified in several ways:
- The name= query parameter contains the complete subscriberCode. This only happens when the user receives a verification email and clicks on the link in the email. When a compilete subscriberCode is seen on the name= query parameter, that constitutes verification of the email address.
-
The sid= query parameter contains an integer subscriberId. This only works for the administrator. It allows the administrator to edit any subscription.
-
The user is logged into an account other than "nobody" or "anonymous". In that case the notification settings associated with that account can be edited without needing to know the subscriber code.
-
The name= query parameter contains a 32-digit prefix of subscriber code. (Subscriber codes are normally 64 hex digits in length.) This uniquely identifies the subscriber without revealing the complete subscriber code, and hence without verifying the email address.
- /ambiguous (web page)
-
URL: /ambiguous?name=NAME&src=WEBPAGE
The NAME given by the name parameter is ambiguous. Display a page that shows all possible choices and let the user select between them.
The src= query parameter is optional. If omitted it defaults to "info".
- /annotate (web page)
- /blame (web page)
- /praise (web page)
-
URL: /annotate?checkin=ID&filename=FILENAME
URL: /blame?checkin=ID&filename=FILENAME
URL: /praise?checkin=ID&filename=FILENAME
Show the most recent change to each line of a text file. /annotate shows the date of the changes and the check-in hash (with a link to the check-in). /blame and /praise also show the user who made the check-in.
Reverse Annotations: Normally, these web pages look at versions of FILENAME moving backwards in time back toward the root check-in. However, if the origin= query parameter is used to specify some future check-in (example: "origin=trunk") then these pages show changes moving towards that alternative origin. Thus using "origin=trunk" on an historical version of the file shows the first time each line in the file was changed or removed by any subsequent check-in.
Query parameters:
- checkin=ID
- The check-in at which to start the annotation
- filename=FILENAME
- The filename.
- filevers=BOOLEAN
- Show file versions rather than check-in versions
- limit=LIMIT
- Limit the amount of analysis. LIMIT can be one of:
- none
- No limit
- Xs
- As much as can be computed in X seconds
- N
- N versions
- log=BOOLEAN
- Show a log of versions analyzed
- origin=ID
- The origin check-in. If unspecified, the root check-in over the entire repository is used. Specify "origin=trunk" or similar for a reverse annotation
- w=BOOLEAN
- Ignore whitespace
- /announce (web page)
- A web-form, available to users with the "Send-Announcement" or "A" capability, that allows one to send announcements to whomever has subscribed to receive announcements. The administrator can also send a message to an arbitrary email address and/or to all subscribers regardless of whether or not they have elected to receive announcements.
- /artifact (web page)
- /file (web page)
- /whatis (web page)
-
Typical usage:
/artifact/HASH /whatis/HASH /file/NAME
Additional query parameters:
- ln
- - show line numbers
- ln=N
- - highlight line number N
- ln=M-N
- - highlight lines M through N inclusive
- ln=M-N+Y-Z
- - highlight lines M through N and Y through Z (inclusive)
- verbose
- - show more detail in the description
- download
- - redirect to the download (artifact page only)
- name=NAME
- - filename or hash as a query parameter
- filename=NAME
- - alternative spelling for "name="
- fn=NAME
- - alternative spelling for "name="
- ci=VERSION
- - The specific check-in to use with "name=" to identify the file.
- txt
- - Force display of unformatted source text
The /artifact page show the complete content of a file identified by HASH. The /whatis page shows only a description of how the artifact is used. The /file page shows the most recent version of the file or directory called NAME, or a list of the top-level directory if NAME is omitted.
For /artifact and /whatis, the name= query parameter can refer to either the name of a file, or an artifact hash. If the ci= query parameter is also present, then name= must refer to a file name. If ci= is omitted, then the hash interpretation is preferred but if name= cannot be understood as a hash, a default "tip" value is used for ci=.
For /file, name= can only be interpreted as a filename. As before, a default value of "tip" is used for ci= if ci= is omitted.
- /artifact_stats (web page)
- Show information about the sizes of artifacts in this repository
- /attachadd (web page)
-
Add a new attachment.
tkt=HASH page=WIKIPAGE technote=HASH from=URL
- /attachdownload (web page)
- /attachimage (web page)
- /attachview (web page)
-
Download or display an attachment.
Query parameters:
tkt=HASH page=WIKIPAGE technote=HASH file=FILENAME attachid=ID
- /attachlist (web page)
-
List attachments.
tkt=HASH page=WIKIPAGE technote=HASH
At most one of technote=, tkt= or page= may be supplied.
If none are given, all attachments are listed. If one is given, only attachments for the designated technote, ticket or wiki page are shown.
HASH may be just a prefix of the relevant technical note or ticket artifact hash, in which case all attachments of all technical notes or tickets with the prefix will be listed.
- /background (web page)
- Return the background image. If no background image is defined, a built-in 16x16 pixel white GIF is returned.
- /bigbloblist (web page)
-
Return a page showing the largest artifacts in the repository in order
of decreasing size.
- n=N
- Show the top N artifacts (default: 250)
- /bloblist (web page)
-
Return a page showing all artifacts in the repository. Query parameters:
- n=N
- Show N artifacts
- s=S
- Start with artifact number S
- priv
- Show only unpublished or private artifacts
- phan
- Show only phantom artifacts
- hclr
- Color code hash types (SHA1 vs SHA3)
- /brlist (web page)
-
Show a list of branches. With no query parameters, a sortable table
is used to show all branches. If query parameters are present a
fixed bullet list is shown.
Query parameters:
- all
- Show all branches
- closed
- Show only closed branches
- open
- Show only open branches
- colortest
- Show all branches with automatic color
When there are no query parameters, a new-style /brlist page shows all branches in a sortable table. The new-style /brlist page is preferred and is the default.
- /brtimeline (web page)
-
Show a timeline of all branches
Query parameters:
- ng
- No graph
- nohidden
- Hide check-ins with "hidden" tag
- onlyhidden
- Show only check-ins with "hidden" tag
- brbg
- Background color by branch name
- ubg
- Background color by user name
- /builtin (web page)
-
Return one of many built-in content files. Query parameters:
- name=FILENAME
- Return the single file whose name is FILENAME.
- mimetype=TYPE
- Override the mimetype in the returned file to be TYPE. If this query parameter is omitted (the usual case) then the mimetype is inferred from the suffix on FILENAME
- m=IDLIST
- IDLIST is a comma-separated list of integers that specify multiple javascript files to be concatenated and returned all at once.
- id=UNIQUEID
- Version number of the "builtin" files. Used for cache control only.
At least one of the name= or m= query parameters must be present.
If the id= query parameter is present, then Fossil assumes that the result is immutable and sets a very large cache retention time (1 year).
- /cacheget (web page)
-
Usage: /cacheget?key=KEY
Download a single entry for the cache, identified by KEY. This page is normally a hyperlink from the /cachestat page. Requires Admin privilege.
- /cachestat (web page)
- Show information about the webpage cache. Requires Setup privilege.
- /captcha-audio (web page)
- Return a WAV file that pronounces the digits of the captcha that is determined by the seed given in the name= query parameter.
- /chat (web page)
-
Start up a browser-based chat session.
This is the main page that humans use to access the chatroom. Simply point a web-browser at /chat and the screen fills with the latest chat messages, and waits for new ones.
Other /chat-OP pages are used by XHR requests from this page to send new chat message, delete older messages, or poll for changes.
- /ci (web page)
- /vinfo (web page)
-
URL: /ci/ARTIFACTID
- OR:
- /ci?name=ARTIFACTID
Display information about a particular check-in. The exact same information is shown on the /info page if the name query parameter to /info describes a check-in.
The ARTIFACTID can be a unique prefix for the HASH of the check-in, or a tag or branch name that identifies the check-in.
- /ci_edit (web page)
-
Edit a check-in. (Check-ins are immutable and do not really change.
This page really creates supplemental tags that affect the display
of the check-in.)
Query parameters:
- rid=INTEGER
- Record ID of the check-in to edit (REQUIRED)
POST parameters after pressing "Preview", "Cancel", or "Apply":
- c=TEXT
- New check-in comment
- u=TEXT
- New user name
- newclr
- Apply a background color
- clr=TEXT
- New background color (only if newclr)
- pclr
- Propagate new background color (only if newclr)
- dt=TEXT
- New check-in date/time (ISO8610 format)
- newtag
- Add a new tag to the check-in
- tagname=TEXT
- Name of the new tag to be added (only if newtag)
- newbr
- Put the check-in on a new branch
- brname=TEXT
- Name of the new branch (only if newbr)
- close
- Close this check-in
- hide
- Hide this check-in
- cNNN
- Cancel tag with tagid=NNN
- cancel
- Cancel the edit. Return to the check-in view
- preview
- Show a preview of the edited check-in comment
- apply
- Apply changes
- /ci_tags (web page)
-
URL: /ci_tags?name=ARTIFACTID
Show all tags and properties for a given check-in.
This information used to be part of the main /ci page, but it is of marginal usefulness. Better to factor it out into a sub-screen.
- /ckout (web page)
-
Show information about the current checkout. This page only functions
if the web server is run on a loopback interface (in other words, was
started using "fossil ui" or similar) from within an open check-out.
If the "exbase=PATH" query parameter is provided, then the diff shown uses the files in PATH as the baseline. This is the same as using the "--from PATH" argument to the "fossil diff" command-line. In fact, when using "fossil ui --from PATH", the --from argument becomes the value of the exbase query parameter for the start page. Note that if PATH is a pure hexadecimal string, it is decoded first before being used as the pathname. Real pathnames should contain at least one directory separator character.
Other query parameters related to diffs are also accepted.
- /contact_admin (web page)
- A web-form to send an email message to the repository administrator, or (with appropriate permissions) to anybody.
- /cookies (web page)
- /fdscookie (web page)
-
Show all cookies associated with Fossil. This shows the text of the
login cookie and is hence dangerous if an adversary is looking over
your shoulder and is able to read and reproduce that cookie.
Show the current display settings contained in the "fossil_display_settings" cookie.
- /debug_tktedit (web page)
- /tktedit (web page)
- Edit a ticket. The ticket is identified by the name CGI parameter. /tktedit is the official page. The /debug_tktedit page does the same thing except that it does not save the ticket change record when you press submit - it instead prints the ticket change record at the top of the page. The /debug_tktedit page is intended to be used when debugging ticket configurations.
- /debug_tktnew (web page)
- /tktnew (web page)
- Enter a new ticket. The tktnew_template script in the ticket configuration is used. The /tktnew page is the official ticket entry page. The /debug_tktnew page is used for debugging the tktnew_template in the ticket configuration. /debug_tktnew works just like /tktnew except that it does not really save the new ticket when you press submit - it just prints the ticket artifact at the top of the screen.
- /deltachain (web page)
-
Usage: /deltachain/RID
The RID query parameter is required. Generate a page with a table showing storage characteristics of RID and other artifacts that are derived from RID via delta.
- /dir (web page)
-
Show the files and subdirectories within a single directory of the
source tree. Only files for a single check-in are shown if the ci=
query parameter is present. If ci= is missing, the union of files
across all check-ins is shown.
Query parameters:
- ci=LABEL
- Show only files in this check-in. Optional.
- name=PATH
- Directory to display. Optional. Top-level if missing
- re=REGEXP
- Show only files matching REGEXP
- type=TYPE
- TYPE=flat: use this display TYPE=tree: use the /tree display instead
- noreadme
- Do not attempt to display the README file.
- dx
- Behave like /docdir
- /doc (web page)
- /uv (web page)
-
URL: /uv/FILE
URL: /doc/CHECKIN/FILE
CHECKIN can be either tag or hash prefix or timestamp identifying a particular check-in, or the name of a branch (meaning the most recent check-in on that branch) or one of various magic words:
- "tip"
- means the most recent check-in
- "ckout"
- means the current check-out, if the server is run from within a check-out, otherwise it is the same as "tip"
- "latest"
- means use the most recent check-in for the document regardless of what branch it occurs on.
FILE is the name of a file to delivered up as a webpage. FILE is relative to the root of the source tree of the repository. The FILE must be a part of CHECKIN, except when CHECKIN=="ckout" when FILE is read directly from disk and need not be a managed file. For /uv, FILE can also be the hash of the unversioned file.
The "ckout" CHECKIN is intended for development - to provide a mechanism for looking at what a file will look like using the /doc webpage after it gets checked in. Some commands like "fossil ui", "fossil server", and "fossil http" accept an argument "--ckout-alias NAME" when allows NAME to be understood as an alias for "ckout". On a site with many embedded hyperlinks to /doc/trunk/... one can run with "--ckout-alias trunk" to simulate what the pending changes will look like after they are checked in. The NAME alias is stored in g.zCkoutAlias.
The file extension is used to decide how to render the file.
If FILE ends in "/" then the names "FILE/index.html", "FILE/index.wiki", and "FILE/index.md" are tried in that order. If the binary was compiled with TH1 embedded documentation support and the "th1-docs" setting is enabled, the name "FILE/index.th1" is also tried. If none of those are found, then FILE is completely replaced by "404.md" and tried. If that is not found, then a default 404 screen is generated.
If the file's mimetype is "text/x-fossil-wiki" or "text/x-markdown" then headers and footers are added. If the document has mimetype text/html then headers and footers are usually not added. However, if a "text/html" document begins with the following div:
<div class='fossil-doc' data-title='TEXT'>
then headers and footers are supplied. The optional data-title field specifies the title of the document in that case.
For fossil-doc documents and for markdown documents, text of the form: "href='$ROOT/" or "action='$ROOT" has the $ROOT name expanded to the top-level of the repository.
- /docdir (web page)
-
Show the files and subdirectories within a single directory of the
source tree. This works similarly to /dir but with the following
differences:
- Links to files go to /doc (showing the file content directly, depending on mimetype) rather than to /file (which always shows the file embedded in a standard Fossil page frame).
-
The submenu and the page title is now show. The page is plain.
The /docdir page is a shorthand for /dir with the "dx" query parameter.
Query parameters:
- ci=LABEL
- Show only files in this check-in. If omitted, the "trunk" directory is used.
- name=PATH
- Directory to display. Optional. Top-level if missing
- re=REGEXP
- Show only files matching REGEXP
- noreadme
- Do not attempt to display the README file.
- dx
- File links to go to /doc instead of /file or /finfo.
- /docsrch (web page)
-
Search for documents that match a user-supplied full-text search pattern.
If no pattern is specified (by the s= query parameter) then the user
is prompted to enter a search string.
Query parameters:
- s=PATTERN
- Search for PATTERN
- /download (web page)
- Provide a simple page that enables newbies to download the latest tarball or ZIP archive, and provides instructions on how to clone.
- /errorlog (web page)
- Show the content of the error log. Only the administrator can view this page.
- /event (web page)
- /technote (web page)
-
Display a technical note (formerly called an "event").
PARAMETERS:
- name=ID
- Identify the technical note to display. ID must be complete.
- aid=ARTIFACTID
- Which specific version of the tech-note. Optional.
- v=BOOLEAN
- Show details if TRUE. Default is FALSE. Optional.
Display an existing tech-note identified by its ID, optionally at a specific version, and optionally with additional details.
- /eventedit (web page)
- /technoteedit (web page)
-
Revise or create a technical note (formerly called an "event").
Required query parameter:
- name=ID
- Hex hash ID of the technote. If omitted, a new tech-note is created.
POST parameters from the "Cancel", "Preview", or "Submit" buttons:
- w=TEXT
- Complete text of the technote.
- t=TEXT
- Time of the technote on the timeline (ISO 8601)
- c=TEXT
- Timeline comment
- g=TEXT
- Tags associated with this technote
- mimetype=TEXT
- Mimetype for w= text
- newclr
- Use a background color
- clr=TEXT
- Background color to use if newclr
For GET requests, when editing an existing technote newclr and clr are implied if a custom color has been set on the previous version of the technote.
- /ext (raw-content web page)
-
Relay an HTTP request to secondary CGI after first checking the
login credentials and setting auxiliary environment variables
so that the secondary CGI can be aware of the credentials and
capabilities of the Fossil user.
The /ext page is only functional if the "extroot: DIR" setting is found in the CGI script that launched Fossil, or if the "--extroot DIR" flag is present when Fossil is launched using the "server", "ui", or "http" commands. DIR must be an absolute pathname (relative to the chroot jail) of the root of the file hierarchy that implements the CGI functionality. Executable files are CGI. Non-executable files are static content.
The path after the /ext is the path to the CGI script or static file relative to DIR. For security, this path may not contain characters other than ASCII letters or digits, ".", "-", "/", and "_". If the "." or "-" characters are present in the path then they may not follow a "/".
If the path after /ext ends with "/" and is the name of a directory then that directory is searched for files named "index.html", "index.wiki", and "index.md" (in that order) and if found, those filenames are appended to the path.
- /extfilelist (web page)
- List all files in the extension CGI document root and its subfolders.
- /favicon.ico (web page)
-
Return the configured "favicon.ico" image. If no "favicon.ico" image
is defined, the returned image is for the Fossil lizard icon.
The intended use case here is to supply an icon for the "fossil ui" command. For a permanent website, the recommended process is for the admin to set up a project-specific icon and reference that icon in the HTML header using a line like:
<link rel="icon" href="URL-FOR-YOUR-ICON" type="MIMETYPE"/>
- /fdiff (web page)
-
URL: fdiff?v1=HASH&v2=HASH
Two arguments, v1 and v2, identify the artifacts to be diffed. Show diff side by side unless sbs is 0. Generate plain text if "patch" is present, otherwise generate "pretty" HTML.
Alternative URL: fdiff?from=filename1&to=filename2&ci=checkin
If the "from" and "to" query parameters are both present, then they are the names of two files within the check-in "ci" that are diffed. If the "ci" parameter is omitted, then the most recent check-in ("tip") is used.
Additional parameters:
- dc=N
- Show N lines of context around each diff
- patch
- Use the patch diff format
- regex=REGEX
- Only show differences that match REGEX
- sbs=BOOLEAN
- Turn side-by-side diffs on and off (default: on)
- verbose=BOOLEAN
- Show more detail when describing artifacts
- w=BOOLEAN
- Ignore whitespace
- /fileage (web page)
-
Show all files in a single check-in (identified by the name= query
parameter) in order of increasing age.
Parameters:
- name=VERSION
- Selects the check-in version (default=tip).
- glob=STRING
- Only shows files matching this glob pattern (e.g. *.c or *.txt).
- showid
- Show RID values for debugging
- /fileedit (web page)
-
Enables the online editing and committing of text files. Requires
that the user have Write permissions and that a user with setup
permissions has set the fileedit-glob setting to a list of glob
patterns matching files which may be edited (e.g. "*.wiki,*.md").
Note that fileedit-glob, by design, is a local-only setting.
It does not sync across repository clones, and must be explicitly
set on any repositories where this page should be activated.
Optional query parameters:
- filename=FILENAME
- Repo-relative path to the file.
- checkin=VERSION
- Check-in version, using any unambiguous symbolic version name.
If passed a filename but no check-in then it will attempt to load that file from the most recent leaf check-in.
Once the page is loaded, files may be selected from any open leaf version. The only way to edit files from non-leaf checkins is to pass both the filename and check-in as URL parameters to the page. Users with the proper permissions will be presented with "Edit" links in various file-specific contexts for files which match the fileedit-glob, regardless of whether they refer to leaf versions or not.
- /finfo (web page)
-
Usage:
- /finfo?name=FILENAME
- /finfo?name=FILENAME&ci=HASH
Show the change history for a single file. The name=FILENAME query parameter gives the filename and is a required parameter. If the ci=HASH parameter is also supplied, then the FILENAME,HASH combination identifies a particular version of a file, and in that case all changes to that one file version are tracked across both edits and renames. If only the name=FILENAME parameter is supplied (if ci=HASH is omitted) then the graph shows all changes to any file while it happened to be called FILENAME and changes are not tracked across renames.
Additional query parameters:
- a=DATETIME
- Only show changes after DATETIME
- b=DATETIME
- Only show changes before DATETIME
- ci=HASH
- identify a particular version of a file and then track changes to that file across renames
- m=HASH
- Mark this particular file version.
- n=NUM
- Show the first NUM changes only
- name=FILENAME
- (Required) name of file whose history to show
- brbg
- Background color by branch name
- ubg
- Background color by user name
- from=HASH
- Ancestors only (not descendants) of the version of the file in this particular check-in.
- to=HASH
- If both from= and to= are supplied, only show those changes on the direct path between the two given checkins.
- showid
- Show RID values for debugging
- showsql
- Show the SQL query used to gather the data for the graph
DATETIME may be in any of usual formats, including "now", "YYYY-MM-DDTHH:MM:SS.SSS", "YYYYMMDDHHMM", and others.
- /forum (web page)
- /forummain (web page)
-
The main page for the forum feature. Show a list of recent forum
threads. Also show a search box at the top if search is enabled,
and a button for creating a new thread, if enabled.
Query parameters:
- n=N
- The number of threads to show on each page
- x=X
- Skip the first X threads
- s=Y
- Search for term Y.
- /forume1 (web page)
- Start a new forum thread.
- /forume2 (web page)
-
Edit an existing forum message.
Query parameters:
- fpid=X
- Hash of the post to be edited. REQUIRED
- /forumedit (web page)
- /forumnew (web page)
- Start a new thread on the forum or reply to an existing thread. But first prompt to see if the user would like to log in.
- /forumpost (web page)
-
Show a single forum posting. The posting is shown in context with
its entire thread. The selected posting is enclosed within
<div class='forumSel'>...</div>. Javascript is used to move the
selected posting into view after the page loads.
Query parameters:
- name=X
- REQUIRED. The hash of the post to display.
- t=a
- Automatic display mode, i.e. hierarchical for desktop and chronological for mobile. This is the default if the "t" query parameter is omitted.
- t=c
- Show posts in the order they were written.
- t=h
- Show posts using hierarchical indenting.
- t=s
- Show only the post specified by "name=X".
- t=r
- Alias for "t=c&unf&hist".
- t=y
- Alias for "t=s&unf&hist".
- raw
- Alias for "t=s&unf". Additionally, omit the border around the post, and ignore "t" and "hist".
- unf
- Show the original, unformatted source text.
- hist
- Show edit history in addition to current posts.
- /forumthread (web page)
-
Show all forum messages associated with a particular message thread.
The result is basically the same as /forumpost except that none of
the postings in the thread are selected.
Query parameters:
- name=X
- REQUIRED. The hash of any post of the thread.
- t=a
- Automatic display mode, i.e. hierarchical for desktop and chronological for mobile. This is the default if the "t" query parameter is omitted.
- t=c
- Show posts in the order they were written.
- t=h
- Show posts using hierarchical indenting.
- unf
- Show the original, unformatted source text.
- hist
- Show edit history in addition to current posts.
- /forumthreadhashlist (web page)
-
Usage: /forumthreadhashlist/HASH-OF-ROOT
This page (accessibly only to admins) shows a list of all artifacts associated with a single forum thread. An admin might copy/paste this list into the /shun page in order to shun an entire thread.
- /hacklog (web page)
- Scan the error log for "possible hack attempt" entries Show hack attempt messages only, omitting all others. Or if the "not" query parameter is present, show only messages that are not hack attempts.
- /hash-collisions (web page)
- Show the number of hash collisions for hash prefixes of various lengths.
- /hash-color-test (web page)
- Print out the color names associated with each tag. Used for testing the hash_color() function.
- /help (web page)
-
URL: /help?name=CMD
Show the built-in help text for CMD. CMD can be a command-line interface command or a page name from the web interface or a setting. Query parameters:
- name=CMD
- Show help for CMD where CMD is a command name or webpage name or setting name.
- plaintext
- Show the help within <pre>...</pre>, as if it were displayed using the "fossil help" command.
- raw
- Show the raw help text without any formatting. (Used for debugging.)
- /hexdump (web page)
-
URL: /hexdump?name=ARTIFACTID
Show the complete content of a file identified by ARTIFACTID as preformatted text.
Other parameters:
- verbose
- Show more detail when describing the object
- /home (web page)
- /index (web page)
- /not_found (web page)
- The /home, /index, and /not_found pages all redirect to the homepage configured by the administrator.
- /honeypot (web page)
- This page is a honeypot for spiders and bots.
- /info (web page)
-
URL: info/NAME
The NAME argument is any valid artifact name: an artifact hash, a timestamp, a tag name, etc.
Because NAME can match so many different things (commit artifacts, wiki pages, ticket comments, forum posts...) the format of the output page depends on the type of artifact that NAME matches.
- /intermap (web page)
- View and modify the interwiki tag map or "intermap". This page is visible to administrators only.
- /ityaar (web page)
-
This is the action for the form that is the captcha. Not intended
for external use. "ityaar" is an acronym "I Think You Are A Robot".
If the captcha is correctly solved, then an anonymous login cookie is set. Regardless of whether or not the captcha was solved, this page always redirects to the fossil-goto cookie.
- /juvlist (web page)
-
Return a complete list of unversioned files as JSON. The JSON
looks like this:
[{"name":NAME, "mtime":MTIME, "hash":HASH, "size":SIZE, "user":USER}]
- /leaves (web page)
-
Show leaf check-ins in a timeline. By default only open leaves
are listed.
A "leaf" is a check-in with no children in the same branch. A "closed leaf" is a leaf that has a "closed" tag. An "open leaf" is a leaf without a "closed" tag.
Query parameters:
- all
- Show all leaves
- closed
- Show only closed leaves
- ng
- No graph
- nohidden
- Hide check-ins with "hidden" tag
- onlyhidden
- Show only check-ins with "hidden" tag
- brbg
- Background color by branch name
- ubg
- Background color by user name
- /login (web page)
- /logout (web page)
- /my (web page)
-
The login/logout page. Parameters:
- g=URL
- Jump back to this URL after login completes
- anon
- The g=URL is not accessible by "nobody" but is accessible by "anonymous"
- /logo (web page)
- Return the logo image. This image is available to anybody who can see the login page. It is designed for use in the upper left-hand corner of the header.
- /markup_help (web page)
- Show links to the md_rules and wiki_rules pages.
- /md_rules (web page)
- Show a summary of the Markdown wiki formatting rules.
- /mimetype_list (web page)
- Show the built-in table used to guess embedded document mimetypes from file suffixes.
- /mlink (web page)
-
URL: /mlink?name=FILENAME
URL: /mlink?ci=NAME
Show all MLINK table entries for a particular file, or for a particular check-in.
This screen is intended for use by Fossil developers to help in debugging Fossil itself. Ordinary Fossil users are not expected to know what the MLINK table is or why it is important.
To avoid confusing ordinary users, this page is only available to administrators.
- /modreq (web page)
- Show all pending moderation request
- /oneclickunsub (web page)
- /unsubscribe (web page)
-
Users visit this page to be delisted from email alerts.
If a valid subscriber code is supplied in the name= query parameter, then that subscriber is delisted.
Otherwise, If the users is logged in, then they are redirected to the /alerts page where they have an unsubscribe button.
Non-logged-in users with no name= query parameter are invited to enter an email address to which will be sent the unsubscribe link that contains the correct subscriber code.
The /unsubscribe page requires comfirmation. The /oneclickunsub page unsubscribes immediately without any need to confirm.
- /paniclog (web page)
- Scan the error log for panics. Show all panic messages, ignoring all other error log entries.
- /phantoms (web page)
-
Show a list of all "phantom" artifacts that are not marked as "private".
A "phantom" artifact is an artifact whose hash named appears in some artifact but whose content is unknown. For example, if a manifest references a particular SHA3 hash of a file, but that SHA3 hash is not on the shunning list and is not in the database, then the file is a phantom. We know it exists, but we do not know its content.
Whenever a sync occurs, both each party looks at its phantom list and for every phantom that is not also marked private, it asks the other party to send it the content. This mechanism helps keep all repositories synced up.
This page is similar to the /bloblist page in that it lists artifacts. But this page is a special case in that it only shows phantoms that are not private. In other words, this page shows all phantoms that generate extra network traffic on every sync request.
- /pikchrshow (web page)
-
A pikchr code editor and previewer, allowing users to experiment
with pikchr code or prototype it for use in copy/pasting into forum
posts, wiki pages, or embedded docs. This version of pikchrshow
uses WebAssembly to run entirely in the client browser, without a
need for back-and-forth client/server traffic to perform the
rendering. The "legacy" version of this application, which sends
all input to the server for rendering, can be accessed by adding
the "legacy" URL argument.
It optionally accepts a p=pikchr-script-code URL parameter or POST value to pre-populate the editor with that code.
- /raw (web page)
-
URL: /raw/ARTIFACTID
URL: /raw?ci=BRANCH&filename=NAME
Additional query parameters:
- m=MIMETYPE
- The mimetype is MIMETYPE
- at=FILENAME
- Content-disposition; attachment; filename=FILENAME;
Return the uninterpreted content of an artifact. Used primarily to view artifacts that are images.
- /rcvfrom (web page)
- Show a single RCVFROM table entry identified by the rcvid= query parameters. Requires Admin privilege.
- /rcvfromlist (web page)
-
Show a listing of RCVFROM table entries.
The RCVFROM table records where this repository received each artifact, including the time of receipt, user, and IP address.
Access requires Admin privilege.
- /register (web page)
- Page to allow users to self-register. The "self-register" setting must be enabled for this page to operate.
- /renew (web page)
- Users visit this page to update the last-contact date on their subscription. The last-contact date is the day that the subscriber last interacted with the repository. If the name= query parameter (or POST parameter) contains a valid subscriber code, then the last-contact subscription associated with that subscriber code is updated to be the current date.
- /repo-tabsize (web page)
- Show relative sizes of tables in the repository database.
- /repo_schema (web page)
- Show the repository schema
- /repo_stat1 (web page)
- Show the sqlite_stat1 table for the repository schema
- /reportlist (web page)
- Main menu for Tickets.
- /reports (web page)
-
Shows activity reports for the repository.
Query Parameters:
- view=REPORT_NAME
- Valid REPORT_NAME values:
- byyear
- bymonth
- byweek
- byweekday
- byhour
- byuser
- byfile
- lastchng
- user=NAME
- Restricts statistics to the given user
- type=TYPE
- Restricts the report to a specific event type:
- all (everything),
- ci (check-in)
- m (merge check-in),
- n (non-merge check-in)
- f (forum post)
- w (wiki page change)
- t (ticket change)
- g (tag added or removed)
The view-specific query parameters include:
view=byweek:
- y=YYYY
- The year to report (default is the server's current year).
- /reqpwreset (web page)
-
A web page to request a password reset.
A form is presented where the user can enter their email address and a captcha. If the email address entered corresponds to a known users, an email is sent to that address that contains a link to the /resetpw page that allows the users to enter a new password.
This page is only available if the self-pw-reset property is enabled and email notifications are configured and operating. Password resets are not available to users with Admin or Setup privilege.
- /resetpw (web page)
-
The URL format must be like this:
/resetpw/UID-TIMESTAMP-HASH
Where UID is the uid of the user whose password is to be reset, TIMESTAMP is the unix timestamp when the request was made, and HASH is a hash based on UID, TIMESTAMP, and other information that is unavailable to an attacher.
With no other arguments, a form is present which allows the user to enter a new password. When the SUBMIT button is pressed, a POST request back to the same URL that will change the password.
- /robots.txt (web page)
-
Return text/plain which is the content of the "robots-txt" setting, if
such a setting exists and is non-empty. Or construct an RFC-9309 complaint
robots.txt file and return that if there is not "robots.txt" setting.
This is useful for robot exclusion in cases where Fossil is run as a stand-alone server in its own domain. For the more common case where Fossil is run as a CGI, or SCGI, or a server that responding to a reverse proxy, the returns robots.txt file will not be at the top level of the domain, and so it will be pointless.
- /rptedit (web page)
- /rptnew (web page)
-
Create (/rptnew) or edit (/rptedit) a ticket report format.
Query parameters:
- name=N
- Ticket report number or tag.
- rn=N
- Ticket report number (legacy). ^^^-- one of the two previous is required.
- t=TITLE
- Title of the report format
- w=USER
- Owner of the report format
- s=SQL
- SQL text used to implement the report
- k=KEY
- Color key
- d=DESC
- Optional descriptive text
- m=MIMETYPE
- Mimetype for DESC
- x=TAG
- Symbolic name for the report
- /rptsql (web page)
-
URL: /rptsql/N
Display the SQL query used to generate a ticket report. The N value is either the report number of a report tag.
- /rptview (web page)
- Generate a report. The rn query parameter is the report number corresponding to REPORTFMT.RN. If the tablist query parameter exists, then the output consists of lines of tab-separated fields instead of an HTML table.
- /script.js (web page)
- Return the "Javascript" content for the current skin (if there is any)
- /search (web page)
-
Search for check-in comments, documents, tickets, or wiki that
match a user-supplied pattern.
- s=PATTERN
- Specify the full-text pattern to search for
- y=TYPE
- What to search. c -> check-ins d -> documentation t -> tickets w -> wiki e -> tech notes f -> forum all -> everything
- /secaudit0 (web page)
-
Run a security audit of the current Fossil setup, looking
for configuration problems that might allow unauthorized
access to the repository.
This page requires administrator access. It is usually accessed using the Admin/Security-Audit menu option from any of the default skins.
- /secureraw (web page)
-
URL: /secureraw/HASH?m=TYPE
Return the uninterpreted content of an artifact. This is similar to /raw except in this case the only way to specify the artifact is by the full-length SHA1 or SHA3 hash. Abbreviations are not accepted.
- /setup (web page)
- Main menu for the administrative pages. Requires Admin or Setup privileges. Links to sub-pages only usable by Setup users are shown only to Setup users.
- /setup-logmenu (web page)
-
Show a menu of available log renderings accessible to an administrator,
together with a succinct explanation of each.
This page is only accessible by administrators.
- /setup_access (web page)
- The access-control settings page. Requires Setup privileges.
- /setup_adunit (web page)
- Administrative page for configuring and controlling ad units and how they are displayed.
- /setup_chat (web page)
- The "Admin/Chat" page. Requires Setup privilege.
- /setup_config (web page)
- The "Admin/Configuration" page. Requires Setup privilege.
- /setup_forum (web page)
- Forum configuration and metrics.
- /setup_login_group (web page)
- Change how the current repository participates in a login group.
- /setup_logo (web page)
- Administrative page for changing the logo, background, and icon images.
- /setup_modreq (web page)
- Admin page for setting up moderation of tickets and wiki.
- /setup_notification (web page)
- Administrative page for configuring and controlling email notification. Normally accessible via the /Admin/Notification menu.
- /setup_robot (web page)
- Settings associated with defense against robots. Requires setup privilege.
- /setup_settings (web page)
- Change or view miscellaneous settings. Part of the /setup pages requiring Setup privileges.
- /setup_skin (web page)
- Generate a page showing the steps needed to create or edit a custom skin.
- /setup_skin_admin (web page)
- Administrative actions on skins. For administrators only.
- /setup_skinedit (web page)
-
Edit aspects of a skin determined by the w= query parameter.
Requires Admin or Setup privileges.
- w=NUM
- -- 0=CSS, 1=footer, 2=header, 3=details, 4=js
- sk=NUM
- -- the draft skin number
- /setup_timeline (web page)
- Edit administrative settings controlling the display of timelines.
- /setup_ucap_list (web page)
- A documentation page showing the meaning of the various user capabilities code letters.
- /setup_uedit (web page)
- Edit information about a user or create a new user. Requires Admin privileges.
- /setup_uinfo (web page)
-
Detailed information about a user account, available to administrators
only.
u=UID l=LOGIN
- /setup_ulist (web page)
-
Show a list of users. Clicking on any user jumps to the edit
screen for that user. Requires Admin privileges.
Query parameters:
- with=CAP
- Only show users that have one or more capabilities in CAP.
- ubg
- Color backgrounds by username hash
- /setup_ulist_notes (web page)
- A documentation page showing notes about user configuration. This information used to be a side-bar on the user list page, but has been factored out for improved presentation.
- /setup_wiki (web page)
- The "Admin/Wiki" page. Requires Setup privilege.
- /shun (web page)
- View the hashes of all shunned artifacts. Add new hashes to the shun set. Requires Admin privilege.
- /sitemap (web page)
-
List some of the web pages offered by the Fossil web engine. This
page is intended as a supplement to the menu bar on the main screen.
That is, this page is designed to hold links that are omitted from
the main menu due to lack of space.
Additional entries defined by the "sitemap-extra" setting are included in the sitemap. "sitemap-extra" should be a TCL script with three values per entry:
- The displayed text
-
The URL
-
A "capexpr" expression that determines whether or not to include the entry based on user capabilities. "*" means always include the entry and "{}" means never.
If the "e=1" query parameter is present, then the standard content is omitted and only the sitemap-extra content is shown. If "e=2" is present, then only the standard content is shown and sitemap-extra content is omitted.
If the "popup" query parameter is present and this is a POST request from the same origin, then the normal HTML header and footer information is omitted and the HTML text returned is just a raw "<ul>...</ul>".
- /sitemap-test (web page)
- List some of the web pages offered by the Fossil web engine for testing purposes. This is similar to /sitemap, but is focused only on showing pages associated with testing.
- /sitemap-timeline (web page)
- Generate a list of hyperlinks to various (obscure) variations on the /timeline page.
- /skins (web page)
- Show a list of all of the built-in skins, plus the respository skin, and provide the user with an opportunity to change to any of them.
- /sqlar (web page)
- /zip (web page)
-
URLs:
/zip/[VERSION/]NAME.zip /sqlar/[VERSION/]NAME.sqlar
Generate a ZIP Archive or an SQL Archive for the check-in specified by VERSION. The archive is called NAME.zip or NAME.sqlar and has a top-level directory called NAME.
The optional VERSION element defaults to "trunk" per the r= rules below. All of the following URLs are equivalent:
/zip/release/xyz.zip /zip?r=release&name=xyz.zip /zip/xyz.zip?r=release /zip?name=release/xyz.zip
Query parameters:
- name=[CKIN/]NAME
- The optional CKIN component of the name= parameter identifies the check-in from which the archive is constructed. If CKIN is omitted and there is no r= query parameter, then use "trunk". NAME is the name of the download file. The top-level directory in the generated archive is called by NAME with the file extension removed.
- r=TAG
- TAG identifies the check-in that is turned into an SQL or ZIP archive. The default value is "trunk". If r= is omitted and if the name= query parameter contains one "/" character then the of part the name= value before the / becomes the TAG and the part of the name= value after the / is the download filename. If no check-in is specified by either name= or r=, then "trunk" is used.
- in=PATTERN
- Only include files that match the comma-separate list of GLOB patterns in PATTERN, as with ex=
- ex=PATTERN
- Omit any file that match PATTERN. PATTERN is a comma-separated list of GLOB patterns, where each pattern can optionally be quoted using ".." or '..'. Any file matching both ex= and in= is excluded.
- /srchsetup (web page)
- Configure the search engine. Requires Admin privilege.
- /stat (web page)
- Show statistics and global information about the repository.
- /style.css (web page)
-
Return the style sheet. The style sheet is assemblied from
multiple sources, in order:
- (1)
- The built-in "default.css" style sheet containing basic defaults.
- (2)
- The page-specific style sheet taken from the built-in called "PAGENAME.css" where PAGENAME is the value of the name= or page= query parameters. If neither name= nor page= exist, then this section is a no-op.
- (3)
- The skin-specific "css.txt" file, if there one.
All of (1), (2), and (3) above (or as many as exist) are concatenated. The result is then run through TH1 with the following variables set:
- $basename
- $secureurl
- $home
- $logo
- $background
The output from TH1 becomes the style sheet. Fossil always reports that the style sheet is cacheable.
- /subscribe (web page)
-
Allow users to subscribe to email notifications.
This page is usually run by users who are not logged in. A logged-in user can add email notifications on the /alerts page. Access to this page by a logged in user (other than an administrator) results in a redirect to the /alerts page.
Administrators can visit this page in order to sign up other users.
The Alerts permission ("7") is required to access this page. To allow anonymous passers-by to sign up for email notification, set Email-Alerts on user "nobody" or "anonymous".
- /subscribers (web page)
- This page, accessible to administrators only, shows a list of subscriber email addresses. Clicking on an email takes one to the /alerts page for that email where the delivery settings can be modified.
- /taglist (web page)
- List all non-propagating symbolic tags.
- /tagtimeline (web page)
-
Render a timeline with all check-ins that contain non-propagating
symbolic tags.
Query parameters:
- ng
- No graph
- nohidden
- Hide check-ins with "hidden" tag
- onlyhidden
- Show only check-ins with "hidden" tag
- brbg
- Background color by branch name
- ubg
- Background color by user name
- /takeitprivate (web page)
- Disable anonymous access to this website
- /tarball (web page)
-
URL: /tarball/[VERSION/]NAME.tar.gz
Generate a compressed tarball for the check-in specified by VERSION. The tarball is called NAME.tar.gz and has a top-level directory called NAME.
The optional VERSION element defaults to "trunk" per the r= rules below. All of the following URLs are equivalent:
/tarball/release/xyz.tar.gz /tarball?r=release&name=xyz.tar.gz /tarball/xyz.tar.gz?r=release /tarball?name=release/xyz.tar.gz
Query parameters:
- name=[CKIN/]NAME
- The optional CKIN component of the name= parameter identifies the check-in from which the tarball is constructed. If CKIN is omitted and there is no r= query parameter, then use "trunk". NAME is the name of the download file. The top-level directory in the generated tarball is called by NAME with the file extension removed.
- r=TAG
- TAG identifies the check-in that is turned into a compressed tarball. The default value is "trunk". If r= is omitted and if the name= query parameter contains one "/" character then the of part the name= value before the / becomes the TAG and the part of the name= value after the / is the download filename. If no check-in is specified by either name= or r=, then "trunk" is used.
- in=PATTERN
- Only include files that match the comma-separate list of GLOB patterns in PATTERN, as with ex=
- ex=PATTERN
- Omit any file that match PATTERN. PATTERN is a comma-separated list of GLOB patterns, where each pattern can optionally be quoted using ".." or '..'. Any file matching both ex= and in= is excluded.
- /test-all-help (web page)
- Show all help text on a single page. Useful for proof-reading.
- /test-backlink-timeline (web page)
- Show a timeline of all check-ins and other events that have entries in the backlink table. This is used for testing the rendering of the "References" section of the /info page.
- /test-backlinks (web page)
- Show a table of all backlinks. Admin access only.
- /test-builtin-files (web page)
- Show all built-in text files.
- /test-captcha (web page)
-
If the name query parameter is provided, then render the hex value of
the name using the captcha font.
Otherwise render the captcha screen. The "show-button" parameter causes the submit button to be rendered.
- /test-captcha-audio (web page)
- Return a WAV file that pronounces the hex digits of the name= query parameter.
- /test-ftsdocs (web page)
- Show a table of all documents currently in the search index.
- /test-pid (web page)
-
Return the process identifier of the running Fossil server instance.
Query parameters:
- usepidkey
- When present and available, also return the address and size, within this server process, of the saved database encryption key. This is only supported when using SEE on Windows or Linux.
- /test-piechart (web page)
- Generate a pie-chart based on data input from a form.
- /test-rename-list (web page)
- Print a list of all file rename operations throughout history. This page is intended for testing purposes only and may change or be discontinued without notice.
- /test-warning (web page)
-
Test error and warning log operation. This webpage is accessible to
the administrator only.
- case=1
- Issue a fossil_warning() while generating the page.
- case=2
- Extra db_begin_transaction()
- case=3
- Extra db_end_transaction()
- case=4
- Error during SQL processing
- case=5
- Call the segfault handler
- case=6
- Call webpage_assert()
- case=7
- Call webpage_error()
- /test_env (web page)
- Display CGI-variables and other aspects of the run-time environment, for debugging and trouble-shooting purposes.
- /thisdayinhistory (web page)
-
Generate a vanity page that shows project activity for the current
day of the year for various years in the history of the project.
Query parameters:
- today=DATE
- Use DATE as today's date
- /ticket (web page)
- This is intended to be the primary "Ticket" page. Render as either ticket-search (if search is enabled) or as the /reportlist page (if ticket search is disabled).
- /timeline (web page)
-
Query parameters:
- a=TIMEORTAG
- Show events after TIMEORTAG
- b=TIMEORTAG
- Show events before TIMEORTAG
- c=TIMEORTAG
- Show events that happen "circa" TIMEORTAG
- cf=FILEHASH
- Show events around the time of the first use of the file with FILEHASH
- m=TIMEORTAG
- Highlight the event at TIMEORTAG, or the closest available event if TIMEORTAG is not part of the timeline. If the t= or r= is used, the m event is added to the timeline if it isn't there already.
- x=HASHLIST
- Show all check-ins in the comma-separated HASHLIST in addition to check-ins specified by t= or r=
- sel1=TIMEORTAG
- Highlight the check-in at TIMEORTAG if it is part of the timeline. Similar to m= except TIMEORTAG must match a check-in that is already in the timeline.
- sel2=TIMEORTAG
- Like sel1= but use the secondary highlight.
- n=COUNT
- Maximum number of events. "all" for no limit
- n1=COUNT
- Same as "n" but doesn't set the display-preference cookie Use "n1=COUNT" for a one-time display change
- p=CHECKIN
- Parents and ancestors of CHECKIN
- bt=PRIOR
- ... going back to PRIOR
- p2=CKIN2
- ... use CKIN2 if CHECKIN is not found
- d=CHECKIN
- Children and descendants of CHECKIN
- d2=CKIN2
- ... Use CKIN2 if CHECKIN is not found
- ft=DESCENDANT
- ... going forward to DESCENDANT
- dp=CHECKIN
- Same as 'd=CHECKIN&p=CHECKIN'
- dp2=CKIN2
- Same as 'd2=CKIN2&p2=CKIN2'
- df=CHECKIN
- Same as 'd=CHECKIN&n1=all&nd'. Mnemonic: "Derived From"
- bt=CHECKIN
- "Back To". Show ancenstors going back to CHECKIN
- p=CX
- ... from CX back to time of CHECKIN
- from=CX
- ... shortest path from CX back to CHECKIN
- ft=CHECKIN
- "Forward To": Show decendents forward to CHECKIN
- d=CX
- ... from CX up to the time of CHECKIN
- from=CX
- ... shortest path from CX up to CHECKIN
- t=TAG
- Show only check-ins with the given TAG
- r=TAG
- Show check-ins related to TAG, equivalent to t=TAG&rel
- tl=TAGLIST
- Shorthand for t=TAGLIST&ms=brlist
- rl=TAGLIST
- Shorthand for r=TAGLIST&ms=brlist
- rel
- Show related check-ins as well as those matching t=TAG
- mionly
- Limit rel to show ancestors but not descendants
- nowiki
- Do not show wiki associated with branch or tag
- ms=MATCHSTYLE
- Set tag match style to EXACT, GLOB, LIKE, REGEXP
- u=USER
- Only show items associated with USER
- y=TYPE
- 'ci', 'w', 't', 'n', 'e', 'f', or 'all'.
- ss=VIEWSTYLE
- c: "Compact", v: "Verbose", m: "Modern", j: "Columnar", x: "Classic".
- advm
- Use the "Advanced" or "Busy" menu design.
- ng
- No Graph.
- ncp
- Omit cherrypick merges
- nd
- Do not highlight the focus check-in
- nsm
- Omit the submenu
- nc
- Omit all graph colors other than highlights
- v
- Show details of files changed
- vfx
- Show complete text of forum messages
- f=CHECKIN
- Show family (immediate parents and children) of CHECKIN
- from=CHECKIN
- Path from...
- to=CHECKIN
- ... to this
- to2=CHECKIN
- ... backup name if to= doesn't resolve
- shortest
- ... show only the shortest path
- rel
- ... also show related checkins
- bt=PRIOR
- ... path from CHECKIN back to PRIOR
- ft=LATER
- ... path from CHECKIN forward to LATER
- uf=FILE_HASH
- Show only check-ins that contain the given file version All qualifying check-ins are shown unless there is also an n= or n1= query parameter.
- chng=GLOBLIST
- Show only check-ins that involve changes to a file whose name matches one of the comma-separate GLOBLIST
- brbg
- Background color determined by branch name
- ubg
- Background color determined by user
- deltabg
- Background color red for delta manifests or green for baseline manifests
- namechng
- Show only check-ins that have filename changes
- forks
- Show only forks and their children
- cherrypicks
- Show all cherrypicks
- ym=YYYY-MM
- Show only events for the given year/month
- yw=YYYY-WW
- Show only events for the given week of the given year
- yw=YYYY-MM-DD
- Show events for the week that includes the given day
- ymd=YYYY-MM-DD
- Show only events on the given day. The use "ymd=now" to see all changes for the current week.
- year=YYYY
- Show only events on the given year. The use "year=0" to see all changes for the current year.
- days=N
- Show events over the previous N days
- datefmt=N
- Override the date format: 0=HH:MM, 1=HH:MM:SS, 2=YYYY-MM-DD HH:MM:SS, 3=YYMMDD HH:MM, and 4 means "off".
- bisect
- Show the check-ins that are in the current bisect
- oldestfirst
- Show events oldest first.
- showid
- Show RIDs
- showsql
- Show the SQL text
p= and d= can appear individually or together. If either p= or d= appear, then u=, y=, a=, and b= are ignored.
If both a= and b= appear then both upper and lower bounds are honored.
When multiple time-related filters are used, e.g. ym, yw, and ymd, which one(s) is/are applied is unspecified and may change between fossil versions.
CHECKIN or TIMEORTAG can be a check-in hash prefix, or a tag, or the name of a branch.
- /timeline.rss (web page)
-
URL: /timeline.rss?y=TYPE&n=LIMIT&tkt=HASH&tag=TAG&wiki=NAME&name=FILENAME
Produce an RSS feed of the timeline.
TYPE may be: all, ci (show check-ins only), t (show ticket changes only), w (show wiki only), e (show tech notes only), f (show forum posts only), g (show tag/branch changes only).
LIMIT is the number of items to show.
tkt=HASH filters for only those events for the specified ticket. tag=TAG filters for a tag, and wiki=NAME for a wiki page. Only one may be used.
In addition, name=FILENAME filters for a specific file. This may be combined with one of the other filters (useful for looking at a specific branch).
- /timewarps (web page)
- Show all check-ins that are "timewarps". A timewarp is a check-in that occurs before its parent, according to the timestamp information on the check-in. This can only actually happen, of course, if a users system clock is set incorrectly.
- /tinfo (web page)
-
URL: /tinfo?name=ARTIFACTID
Show the details of a ticket change control artifact.
- /tkthistory (web page)
-
URL: /tkthistory/TICKETUUID
Show the complete change history for a single ticket. Or (to put it another way) show a list of artifacts associated with a single ticket.
By default, the artifacts are decoded and formatted. Text fields are formatted as text/plain, since in the general case Fossil does not have knowledge of the encoding. If the "raw" query parameter is present, then the undecoded and unformatted text of each artifact is displayed.
Reassignments of a field of the TICKET table that has a corresponding "baseline for ..." companion are rendered as unified diffs.
- /tktsetup (web page)
- Main sub-menu for configuring the ticketing system.
- /tktsetup_change (web page)
- Administrative screen used to view or edit the TH1 script that shows ticket changes.
- /tktsetup_com (web page)
- Administrative page used to define TH1 script that is common to all ticket screens.
- /tktsetup_editpage (web page)
- Administrative page for viewing or editing the TH1 script that drives the ticket editing page.
- /tktsetup_keytplt (web page)
- Administrative page used to view or edit the Key template for tickets.
- /tktsetup_newpage (web page)
- Administrative page used to view or edit the TH1 script used to enter new tickets.
- /tktsetup_reportlist (web page)
- Administrative page used to view or edit the TH1 script that defines the "report list" page.
- /tktsetup_rpttplt (web page)
- Administrative page used to view or edit the ticket report template.
- /tktsetup_tab (web page)
- Administrative page for defining the "ticket" table used to hold ticket information.
- /tktsetup_timeline (web page)
- Administrative page used ot configure how tickets are rendered on timeline views.
- /tktsetup_viewpage (web page)
- Administrative page used to view or edit the TH1 script that displays individual tickets.
- /tktsrch (web page)
-
Usage: /tktsrch?s=PATTERN
Full-text search of all current tickets
- /tkttimeline (web page)
-
URL: /tkttimeline/TICKETUUID
Show the change history for a single ticket in timeline format.
Query parameters:
- y=ci
- Show only check-ins associated with the ticket
- /tktview (web page)
-
URL: tktview/HASH
View a ticket identified by the name= query parameter. Other query parameters:
- tl
- Show a timeline of the ticket above the status
- /tree (web page)
-
Show the files using a tree-view. If the ci= query parameter is present
then show only the files for the check-in identified. If ci= is omitted,
then show the union of files over all check-ins.
The type=tree query parameter is required or else the /dir format is used.
Query parameters:
- type=tree
- Required to prevent use of /dir format
- name=PATH
- Directory to display. Optional
- ci=LABEL
- Show only files in this check-in. Optional.
- re=REGEXP
- Show only files matching REGEXP. Optional.
- expand
- Begin with the tree fully expanded.
- nofiles
- Show directories (folders) only. Omit files.
- sort
- 0: by filename, 1: by mtime, 2: by size
- /urllist (web page)
- Show ways in which this repository has been accessed
- /uvlist (web page)
-
Display a list of all unversioned files in the repository.
Query parameters:
- byage=1
- Order the initial display be decreasing age
- showdel=0
- Show deleted files
- /vdiff (web page)
-
URL: /vdiff?from=TAG&to=TAG
Show the difference between two check-ins identified by the from= and to= query parameters.
Query parameters:
- from=TAG
- Left side of the comparison
- to=TAG
- Right side of the comparison
- branch=TAG
- Show all changes on a particular branch
- diff=INTEGER
- 0: none, 1: unified, 2: side-by-side
- glob=STRING
- only diff files matching this glob
- dc=N
- show N lines of context around each diff
- w=BOOLEAN
- ignore whitespace when computing diffs
- nohdr
- omit the description at the top of the page
- nc
- omit branch coloration from the header graph
- inv
- "Invert". Exchange the roles of from= and to=
Show all differences between two check-ins.
- /version (web page)
-
Show the version information for Fossil.
Query parameters:
- verbose
- Show details
- /vpatch (web page)
-
URL: /vpatch?from=FROM&to=TO
Show a patch that goes from check-in FROM to check-in TO.
- /waliassetup (web page)
- Configure the URL aliases
- /wcontent (web page)
-
all=1 Show deleted pages
- showid
- Show rid values for each page.
List all available wiki pages with date created and last modified.
- /wdiff (web page)
-
Show the changes to a wiki page.
Query parameters:
- id=HASH
- Hash prefix for the child version to be diffed.
- rid=INTEGER
- RecordID for the child version
- pid=HASH
- Hash prefix for the parent.
The "id" query parameter is required. "pid" is optional. If "pid" is omitted, then the diff is against the first parent of the child.
- /wfind (web page)
- URL: /wfind?title=TITLE List all wiki pages whose titles contain the search text
- /whistory (web page)
-
URL: /whistory?name=PAGENAME
Additional parameters:
- showid
- Show RID values
Show the complete change history for a single wiki page.
- /wiki (web page)
-
Display a wiki page. Example: /wiki?name=PAGENAME
Query parameters:
- name=NAME
- Name of the wiki page to display. Required.
- nsm
- Omit the submenu if present. (Mnemonic: No SubMenu)
- p
- Always show just the wiki page. For special pages for check-ins, branches, or tags, there will be a redirect to the associated /info page unless this query parameter is present.
- popup
- Suppress the header and footer and other page boilerplate and only return the formatted content of the wiki page.
- /wiki_rules (web page)
- Show a summary of the wiki formatting rules.
- /wikiappend (web page)
-
URL: /wikiappend?name=PAGENAME&mimetype=MIMETYPE
Append text to the end of a wiki page.
- /wikiedit (web page)
-
URL: /wikedit?name=PAGENAME
The main front-end for the Ajax-based wiki editor app. Passing in the name of an unknown page will trigger the creation of a new page (which is not actually created in the database until the user explicitly saves it). If passed no page name, the user may select a page from the list on the first UI tab.
When creating a new page, the mimetype URL parameter may optionally be used to set its mimetype to one of text/x-fossil-wiki, text/x-markdown, or text/plain, defaulting to the former.
- /wikihelp (web page)
- A generic landing page for wiki.
- /wikinew (web page)
-
URL /wikinew
Prompt the user to enter the name of a new wiki page. Then redirect to the wikiedit screen for that new page.
- /wikisrch (web page)
-
Usage: /wikisrch?s=PATTERN
Full-text search of all current wiki text
- /winfo (web page)
-
URL: /winfo?name=HASH
Display information about a wiki page.
- /xfer (raw-content web page)
- This is the transfer handler on the server side. The transfer message has been uncompressed and placed in the g.cgiIn blob. Process this message and form an appropriate reply.
- /xfersetup (web page)
- Main sub-menu for configuring the transfer system.
- /xfersetup_com (web page)
- View or edit the TH1 script that runs prior to receiving a transfer.
- /xfersetup_commit (web page)
- View or edit the TH1 script that runs when a transfer commit is processed.
- /xfersetup_push (web page)
- View or edit the TH1 script that runs after receiving a "push".
- /xfersetup_ticket (web page)
- View or edit the TH1 script that runs when a ticket change artifact is processed during a transfer.
- 3-way-merge (2nd tier command)
-
Usage: fossil 3-way-merge BASELINE V1 V2 [MERGED]
Inputs are files BASELINE, V1, and V2. The file MERGED is generated as output. If no MERGED file is specified, output is sent to stdout.
BASELINE is a common ancestor of two files V1 and V2 that have diverging edits. The generated output file MERGED is the combination of all changes in both V1 and V2.
This command has no effect on the Fossil repository. It is a utility command made available for the convenience of users. This command can be used, for example, to help import changes from an upstream project.
Suppose an upstream project has a file named "Xup.c" which is imported with modifications to the local project as "Xlocal.c". Suppose further that the "Xbase.c" is an exact copy of the last imported "Xup.c". Then to import the latest "Xup.c" while preserving all the local changes:
fossil 3-way-merge Xbase.c Xlocal.c Xup.c Xlocal.c cp Xup.c Xbase.c # Verify that everything still works fossil commit
- access-log (boolean setting)
- When the access-log setting is enabled, all login attempts (successful and unsuccessful) on the web interface are recorded in the "access" table of the repository.
- add (1st tier command)
-
Usage: fossil add ?OPTIONS? FILE1 ?FILE2 ...?
Make arrangements to add one or more files or directories to the current check-out at the next commit.
When adding files or directories recursively, filenames that begin with "." are excluded by default. To include such files, add the "--dotfiles" option to the command-line.
The --ignore and --clean options are comma-separated lists of glob patterns for files to be excluded. Example: '*.o,*.obj,*.exe' If the --ignore option does not appear on the command line then the "ignore-glob" setting is used. If the --clean option does not appear on the command line then the "clean-glob" setting is used.
When attempting to explicitly add files on the commandline, and if those match "ignore-glob", a confirmation is asked first. This can be prevented using the -f|--force option.
The --case-sensitive option determines whether or not filenames should be treated case sensitive or not. If the option is not given, the default depends on the global setting, or the operating system default, if not set.
Options:
- --case-sensitive BOOL
- Override the case-sensitive setting
- --dotfiles
- Include files beginning with a dot (".")
- -f|--force
- Add files without prompting
- --ignore CSG
- Ignore unmanaged files matching patterns from the Comma Separated Glob (CSG) pattern list
- --clean CSG
- Also ignore files matching patterns from the Comma Separated Glob (CSG) list
- --reset
- Reset the ADDED state of a check-out, such that all newly-added (but not yet committed) files are no longer added. No flags other than --verbose and --dry-run may be used with --reset.
- --allow-reserved
- Permit filenames which are reserved on Windows platforms. Such files cannot be checked out on Windows, so use with care.
The following options are only valid with --reset:
- -v|--verbose
- Output information about each --reset file
- -n|--dry-run
- Display instead of run actions
- addremove (1st tier command)
-
Usage: fossil addremove ?OPTIONS?
Do all necessary "add" and "rm" commands to synchronize the repository with the content of the working check-out:
- All files in the check-out but not in the repository (that is, all files displayed using the "extras" command) are added as if by the "add" command.
-
All files in the repository but missing from the check-out (that is, all files that show as MISSING with the "status" command) are removed as if by the "rm" command.
Note that this command does not "commit", as that is a separate step.
Files and directories whose names begin with "." are ignored unless the --dotfiles option is used.
The --ignore option overrides the "ignore-glob" setting, as do the --case-sensitive option with the "case-sensitive" setting and the --clean option with the "clean-glob" setting. See the documentation on the "settings" command for further information.
The -n|--dry-run option shows what would happen without actually doing anything.
This command can be used to track third party software.
Options:
- --case-sensitive BOOL
- Override the case-sensitive setting
- --dotfiles
- Include files beginning with a dot (".")
- --ignore CSG
- Ignore unmanaged files matching patterns from the Comma Separated Glob (CSG) list
- --clean CSG
- Also ignore files matching patterns from the Comma Separated Glob (CSG) list
- -n|--dry-run
- If given, display instead of run actions
- --reset
- Reset the ADDED/DELETED state of a check-out, such that all newly-added (but not yet committed) files are no longer added and all newly-removed (but not yet committed) files are no longer removed. No flags other than --verbose and --dry-run may be used with --reset.
- -v|--verbose
- Outputs information about each --reset file. Only usable with --reset.
- admin-log (boolean setting)
- When the admin-log setting is enabled, configuration changes are recorded in the "admin_log" table of the repository.
- alerts (2nd tier command)
-
Usage: fossil alerts SUBCOMMAND ARGS...
Subcommands:
- pending
- Show all pending alerts. Useful for debugging.
- reset
- Hard reset of all email notification tables in the repository. This erases all subscription information. ** Use with extreme care **
- send
- Compose and send pending email alerts.
Some installations may want to do this via
a cron-job to make sure alerts are sent
in a timely manner.
Options:
- --digest
- Send digests
- --renewal
- Send subscription renewal notices
- --test
- Write to standard output
- settings [NAME VALUE]
- With no arguments, list all email settings. Or change the value of a single email setting.
- status
- Report on the status of the email alert subsystem
- subscribers [PATTERN]
- List all subscribers matching PATTERN. Either LIKE or GLOB wildcards can be used in PATTERN.
- test-message TO [OPTS]
- Send a single email message using whatever
email sending mechanism is currently configured.
Use this for testing the email notification
configuration.
Options:
- --body FILENAME
- Content from FILENAME
- --smtp-trace
- Trace SMTP processing
- --stdout
- Send msg to stdout
- -S|--subject SUBJECT
- Message "subject:"
- unsubscribe EMAIL
- Remove a single subscriber with the given EMAIL.
- all (1st tier command)
-
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 be the name of a directory into which all backup repositories are written.
- cache
- Manages the cache used for potentially expensive web pages. Any additional arguments are passed on verbatim to the cache command.
- changes
- Shows all local check-outs that have uncommitted changes. This operation has no additional options.
- clean
- Delete all "extra" files in all local check-outs. Extreme caution should be exercised with this command because its effects cannot be undone. Use of the --dry-run option to carefully review the local check-outs to be operated upon and the --whatif option to carefully review the files to be deleted beforehand is highly recommended. The command line options supported by the clean command itself, if any are present, are passed along verbatim.
- config
- Only the "config pull AREA" command works.
- dbstat
- Run the "dbstat" command on all repositories.
- extras
- Shows "extra" files from all local check-outs. The command line options supported by the extra command itself, if any are present, are passed along verbatim.
- fts-config
- Run the "fts-config" command on all repositories.
- git CMD
- Do the "git export" or "git status" command (whichever is specified by CMD) on all repositories for which a Git mirror has been previously established.
- info
- Run the "info" command on all repositories.
- pull
- Run a "pull" operation on all repositories. Only the --verbose and --share-links options are 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 option is not supported.
- remote
- Show remote hosts for all repositories.
- repack
- Look for extra compression in all repositories.
- sync
- Run a "sync" on all repositories. Only the --verbose and --unversioned and --share-links options are supported.
- set[tings]
- Run the "settings" command on all repositories. This command is useful for settings like "max-loadavg" which you usually want to be the same across all repositories on a server.
- unset
- Run the "unset" command on all repositories
- server
- Run the "server" commands on all repositories. The root URI gives a listing of all repos.
- ui
- Run the "ui" command on all repositories. Like "server" but bind to the loopback TCP address only, enable the --localauth option and automatically launch a web-browser
- whatis
- Run the "whatis" command on all repositories. Only show output for repositories that have a match.
In addition, the following maintenance operations are supported:
- add
- Add all the repositories named to the set of repositories tracked by Fossil. Normally Fossil is able to keep up with this list by itself, but sometimes it can benefit from this hint if you rename repositories.
- ignore
- Arguments are repositories that should be ignored by subsequent clean, extras, list, pull, push, rebuild, and sync operations. The -c|--ckout option causes the listed local check-outs to be ignored instead.
- list | ls
- Display the location of all repositories. The -c|--ckout option causes all local check-outs to be listed instead.
Repositories are automatically added to the set of known repositories when one of the following commands are run against the repository: clone, info, pull, push, or sync. Even previously ignored repositories are added back to the list of repositories by these commands.
Options:
- --dry-run
- If given, display instead of run actions
- --showfile
- Show the repository or check-out being operated upon
- --stop-on-error
- Halt immediately if any subprocess fails
- allow-symlinks (boolean setting)
-
When allow-symlinks is OFF, Fossil does not see symbolic links
(a.k.a "symlinks") on disk as a separate class of object. Instead Fossil
sees the object that the symlink points to. Fossil will only manage files
and directories, not symlinks. When a symlink is added to a repository,
the object that the symlink points to is added, not the symlink itself.
When allow-symlinks is ON, Fossil sees symlinks on disk as a separate object class that is distinct from files and directories. When a symlink is added to a repository, Fossil stores the target filename. In other words, Fossil stores the symlink itself, not the object that the symlink points to.
Symlinks are not cross-platform. They are not available on all operating systems and file systems. Hence the allow-symlinks setting is OFF by default, for portability.
- amend (1st tier command)
-
Usage: fossil amend HASH OPTION ?OPTION ...?
Amend the tags on check-in HASH to change how it displays in the timeline.
Options:
- --author USER
- Make USER the author for check-in
- -m|--comment COMMENT
- Make COMMENT the check-in comment
- -M|--message-file FILE
- Read the amended comment from FILE
- -e|--edit-comment
- Launch editor to revise comment
- --date DATETIME
- Make DATETIME the check-in time
- --bgcolor COLOR
- Apply COLOR to this check-in
- --branchcolor COLOR
- Apply and propagate COLOR to the branch
- --tag TAG
- Add new TAG to this check-in
- --cancel TAG
- Cancel TAG from this check-in
- --branch NAME
- Rename branch of check-in to NAME
- --hide
- Hide branch starting from this check-in
- --close
- Mark this "leaf" as closed
- -n|--dry-run
- Print control artifact, but make no changes
- --date-override DATETIME
- Set the change time on the control artifact
- --user-override USER
- Set the user name on the control artifact
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.
- annotate (1st tier command)
- blame (1st tier command)
- praise (2nd tier command)
-
Usage: fossil annotate|blame|praise ?OPTIONS? FILENAME
Output the text of a file with markings to show when each line of the file was last modified. The version currently checked out is shown by default. Other versions may be specified using the -r option. The "annotate" command shows line numbers and omits the username. The "blame" and "praise" commands show the user who made each check-in.
Reverse Annotations: Normally, these commands look at versions of FILENAME moving backwards in time back toward the root check-in, and thus the output shows the most recent change to each line. However, if the -o|--origin option is used to specify some future check-in (example: "-o trunk") then these commands show changes moving towards that alternative origin. Thus using "-o trunk" on an historical version of the file shows the first time each line in the file was changed or removed by any subsequent check-in.
Options:
- --filevers
- Show file version numbers rather than check-in versions
- -r|--revision VERSION
- The specific check-in containing the file
- -l|--log
- List all versions analyzed
- -n|--limit LIMIT
- LIMIT can be one of:
- N
- Up to N versions
- Xs
- As much as possible in X seconds
- none
- No limit
- -o|--origin VERSION
- The origin check-in. By default this is the root of the repository. Set to "trunk" or similar for a reverse annotation.
- -w|--ignore-all-space
- Ignore white space when comparing lines
- -Z|--ignore-trailing-space
- Ignore whitespace at line end
- artifact (2nd tier command)
-
Usage: fossil artifact ARTIFACT-ID ?OUTPUT-FILENAME? ?OPTIONS?
Extract an artifact by its artifact hash and write the results on standard output, or if the optional second argument is given, in the named output file.
Options:
- -R|--repository REPO
- Extract artifacts from repository REPO
See also: finfo
- attachment (2nd tier command)
-
Usage: fossil attachment add ?PAGENAME? FILENAME ?OPTIONS?
Add an attachment to an existing wiki page or tech note.
Options:
- -t|--technote DATETIME
- Specifies the timestamp of the technote to which the attachment is to be made. The attachment will be to the most recently modified tech note with the specified timestamp.
- -t|--technote TECHNOTE-ID
- Specifies the technote to be updated by its technote id
One of PAGENAME, DATETIME or TECHNOTE-ID must be 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.
- auto-captcha (boolean setting)
- If enabled, the /login page provides a button that will automatically fill in the captcha password. This makes things easier for human users, at the expense of also making logins easier for malicious robots.
- auto-hyperlink (setting)
-
If non-zero, enable hyperlinks on web pages even for users that lack
the "h" privilege as long as the UserAgent string in the HTTP request
(The HTTP_USER_AGENT cgi variable) looks like it comes from a human and
not a robot. Details depend on the value of the setting.
- (0)
- Off: No adjustments are made to the 'h' privilege based on the user agent.
- (1)
- UserAgent and Javascript: The the href= values of hyperlinks initially point to /honeypot and are changed to point to the correct target by javascript that runs after the page loads. The auto-hyperlink-delay and auto-hyperlink-mouseover settings influence that javascript.
- (2)
- UserAgent only: If the HTTP_USER_AGENT looks human then generate hyperlinks, otherwise do not.
Better robot exclusion is obtained when this setting is 1 versus 2. However, a value of 1 causes the visited/unvisited colors of hyperlinks to stop working on Safari-derived web browsers. When this setting is 2, the hyperlinks work better on Safari, but more robots are able to sneak in.
- auto-hyperlink-delay (setting)
- When the auto-hyperlink setting is 1, the javascript that runs to set the href= attributes of hyperlinks delays by this many milliseconds after the page load. Suggested values: 50 to 200.
- auto-hyperlink-mouseover (boolean setting)
- When the auto-hyperlink setting is 1 and this setting is on, the javascript that runs to set the href= attributes of hyperlinks waits until either a mousedown or mousemove event is seen. This helps to distinguish real users from robots. For maximum robot defense, the recommended setting is ON.
- auto-shun (boolean setting)
- If enabled, automatically pull the shunning list from a server to which the client autosyncs.
- autosync (setting)
-
This setting determines when autosync occurs. The setting is a
string that provides a lot of flexibility for determining when and
when not to autosync. Examples:
- on
- Always autosync for command where autosync makes sense ("commit", "merge", "open", "update")
- off
- Never autosync.
- pullonly
- Only to pull autosyncs
- all
- Sync with all remotes
- on,open=off
- Autosync for most commands, but not for "open"
- off,commit=pullonly
- Do not autosync, except do a pull before each "commit", presumably to avoid undesirable forks.
The syntax is a comma-separated list of VALUE and COMMAND=VALUE entries. A plain VALUE entry is the default that is used if no COMMAND matches. Otherwise, the VALUE of the matching command is used.
The "all" value is special in that it applies to the "sync" command in addition to "commit", "merge", "open", and "update".
- autosync-tries (setting)
- If autosync is enabled setting this to a value greater than zero will cause autosync to try no more than this number of attempts if there is a sync failure.
- backoffice (2nd tier command)
-
Usage: fossil backoffice [OPTIONS...] [REPOSITORIES...]
Run backoffice processing on the repositories listed. If no repository is specified, run it on the repository of the local check-out.
This might be done by a cron job or similar to make sure backoffice processing happens periodically. Or, the --poll option can be used to run this command as a daemon that will periodically invoke backoffice on a collection of repositories.
If only a single repository is named and --poll is omitted, then the backoffice work is done in-process. But if there are multiple repositories or if --poll is used, a separate sub-process is started for each poll of each repository.
Standard options:
- --debug
- Show what this command is doing
- --logfile FILE
- Append a log of backoffice actions onto FILE
- --min N
- When polling, invoke backoffice at least once every N seconds even if the repository never changes. 0 or negative means disable this feature. Default: 3600 (once per hour).
- --poll N
- Repeat backoffice calls for repositories that change in appoximately N-second intervals. N less than 1 turns polling off (the default). Recommended polling interval: 60 seconds.
- --trace
- Enable debugging output on stderr
Options intended for internal use only which may change or be discontinued in future releases:
- --nodelay
- Do not queue up or wait for a backoffice job to complete. If no work is available or if backoffice has run recently, return immediately.
- --nolease
- Always run backoffice, even if there is a lease conflict. This option implies --nodelay. This option is added to secondary backoffice commands that are invoked by the --poll option.
- backoffice-disable (boolean setting)
-
If backoffice-disable is true, then the automatic backoffice
processing is disabled. Automatic backoffice processing is the
backoffice work that normally runs after each web page is
rendered. Backoffice processing that is triggered by the
"fossil backoffice" command is unaffected by this setting.
Backoffice processing does things such as delivering email notifications. So if this setting is true, and if there is no cron job periodically running "fossil backoffice", email notifications and other work normally done by the backoffice will not occur.
- backoffice-logfile (setting)
- If backoffice-logfile is not an empty string and is a valid filename, then a one-line message is appended to that file every time the backoffice runs. This can be used for debugging, to ensure that backoffice is running appropriately.
- backoffice-nodelay (boolean setting)
- If backoffice-nodelay is true, then the backoffice processing will never invoke sleep(). If it has nothing useful to do, it simply exits.
- backup (2nd tier command)
-
Usage: fossil backup ?OPTIONS? FILE|DIRECTORY
Make a backup of the repository into the named file or into the named directory. This backup is guaranteed to be consistent even if there are concurrent changes taking place on the repository. In other words, it is safe to run "fossil backup" on a repository that is in active use.
Only the main repository database is backed up by this command. The open check-out file (if any) is not saved. Nor is the global configuration database.
Options:
- --overwrite
- OK to overwrite an existing file
- -R NAME
- Filename of the repository to backup
- binary-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files that should be treated as "binary" for committing and merging purposes. Example: *.jpg,*.png The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax
- bisect (1st tier command)
-
Usage: fossil bisect SUBCOMMAND ...
Run various subcommands useful for searching back through the change history for a particular check-in that causes or fixes a problem.
- fossil bisect bad ?VERSION?
- Identify version VERSION as non-working. If VERSION is omitted, the current check-out is marked as non-working.
- fossil bisect good ?VERSION?
- Identify version VERSION as working. If VERSION is omitted, the current check-out is marked as working.
- fossil bisect log
- fossil bisect chart
- Show a log of "good", "bad", and "skip" versions. "bisect log" shows the events in the order that they were tested. "bisect chart" shows them in order of check-in.
- fossil bisect next
- Update to the next version that is halfway between the working and non-working versions.
- fossil bisect options ?NAME? ?VALUE?
- List all bisect options, or the value of a single option, or set the value of a bisect option.
- fossil bisect reset
- Reinitialize a bisect session. This cancels prior bisect history and allows a bisect session to start over from the beginning.
- fossil bisect run [OPTIONS] COMMAND
- Invoke COMMAND repeatedly to run the bisect. The exit code for
COMMAND should be 0 for "good", 125 for "skip", and any other value
for "bad".
Options:
- -i|--interactive
- Prompt the user for the good/bad/skip decision after each step, rather than using the exit code from COMMAND
- fossil bisect skip ?VERSION?
- Cause VERSION (or the current check-out if VERSION is omitted) to be ignored for the purpose of the current bisect. This might be done, for example, because VERSION does not compile correctly or is otherwise unsuitable to participate in this bisect.
- fossil bisect vlist|ls|status ?-a|--all?
- List the versions in between the inner-most "bad" and "good".
- fossil bisect ui ?HOST@USER:PATH?
- Like "fossil ui" except start on a timeline that shows only the check-ins that are part of the current bisect. If the optional fourth term is added, then information is shown for the bisect that occurred in the PATH directory by USER on remote machine HOST.
- fossil bisect undo
- Undo the most recent "good", "bad", or "skip" command.
- branch (1st tier command)
-
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 close|reopen ?OPTIONS? BRANCH-NAME ?...BRANCH-NAMES?
- Adds or cancels the "closed" tag to one or more branches.
It accepts arbitrary unambiguous symbolic names but
will only resolve check-in names and skips any which resolve
to non-leaf check-ins.
Options:
- -n|--dry-run
- Do not commit changes, but dump artifact to stdout
- -v|--verbose
- Output more information
- --date-override DATE
- DATE to use instead of 'now'
- --user-override USER
- USER to use instead of the current default
- fossil branch current
- Print the name of the branch for the current check-out
- fossil branch hide|unhide ?OPTIONS? BRANCH-NAME ?...BRANCH-NAMES?
- Adds or cancels the "hidden" tag for the specified branches or or check-in IDs. Accepts the same options as the close subcommand.
- fossil branch info BRANCH-NAME
- Print information about a branch
- fossil branch list|ls ?OPTIONS? ?GLOB?
- fossil branch lsh ?OPTIONS? ?LIMIT?
- List all branches.
Options:
- -a|--all
- List all branches. Default show only open branches
- -c|--closed
- List closed branches
- -m|--merged
- List branches merged into the current branch
- -M|--unmerged
- List branches not merged into the current branch
- -p
- List only private branches
- -r
- Reverse the sort order
- -t
- Show recently changed branches first
- --self
- List only branches where you participate
- --username USER
- List only branches where USER participates
- --users N
- List up to N users participating
The current branch is marked with an asterisk. Private branches are marked with a hash sign.
If GLOB is given, show only branches matching the pattern.
The "lsh" variant of this subcommand shows recently changed branches, and accepts an optional LIMIT argument (defaults to 5) to cap output, but no GLOB argument. All other options are supported, with -t being an implied no-op.
- fossil branch new BRANCH-NAME BASIS ?OPTIONS?
- Create a new branch BRANCH-NAME off of check-in BASIS.
Options:
- --private
- Branch is private (i.e., remains local)
- --bgcolor COLOR
- Use COLOR instead of automatic background
- --nosign
- Do not sign the manifest for the check-in that creates this branch
- --nosync
- Do not auto-sync prior to creating the 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:
- -R|--repository REPO
- Run commands on repository REPO
- bundle (2nd tier command)
-
Usage: fossil bundle SUBCOMMAND ARGS...
- fossil bundle append BUNDLE FILE...
- Add files named on the command line to BUNDLE. This subcommand has little practical use and is mostly intended for testing.
- fossil bundle cat BUNDLE HASH...
- Extract one or more artifacts from the bundle and write them consecutively on standard output. This subcommand was designed for testing and introspection of bundles and is not something commonly used.
- fossil bundle export BUNDLE ?OPTIONS?
- Generate a new bundle, in the file named BUNDLE, that contains a
subset of the check-ins in the repository (usually a single branch)
described by the --branch, --from, --to, and/or --checkin options,
at least one of which is required. If BUNDLE already exists, the
specified content is added to the bundle.
- --branch BRANCH
- Package all check-ins on BRANCH
- --from TAG1 --to TAG2
- Package check-ins between TAG1 and TAG2
- --checkin TAG
- Package the single check-in TAG
- --standalone
- Do no use delta-encoding against artifacts not in the bundle
- fossil bundle extend BUNDLE
- The BUNDLE must already exist. This subcommand adds to the bundle any check-ins that are descendants of check-ins already in the bundle, and any tags that apply to artifacts in the bundle.
- fossil bundle import BUNDLE ?--publish?
- Import all content from BUNDLE into the repository. By default, the imported files are private and will not sync. Use the --publish option to make the import public.
- fossil bundle ls BUNDLE
- List the contents of BUNDLE on standard output
- fossil bundle purge BUNDLE
- Remove from the repository all files that are used exclusively by check-ins in BUNDLE. This has the effect of undoing a "fossil bundle import".
See also: publish
- cache (2nd tier command)
-
Usage: fossil cache SUBCOMMAND
Manage the cache used for potentially expensive web pages such as /zip and /tarball. SUBCOMMAND can be:
- clear
- Remove all entries from the cache.
- init
- Create the cache file if it does not already exist.
- list|ls
- List the keys and content sizes and other stats for all entries currently in the cache.
- size ?N?
- Query or set the maximum number of entries in the cache.
- status
- Show a summary of the cache status.
The cache is stored in a file that is distinct from the repository but that is held in the same directory as the repository. The cache file can be deleted in order to completely disable the cache.
- case-sensitive (boolean setting)
- If TRUE, the files whose names differ only in case are considered distinct. If FALSE files whose names differ only in case are the same file. Defaults to TRUE for unix and FALSE for Cygwin, Mac and Windows.
- cat (1st tier command)
-
Usage: fossil cat FILENAME ... ?OPTIONS?
Print on standard output the content of one or more files as they exist in the repository. The version currently checked out is shown by default. Other versions may be specified using the -r option.
Options:
- -o|--out OUTFILE
- For exactly one given FILENAME, write to OUTFILE
- -R|--repository REPO
- Extract artifacts from repository REPO
- -r VERSION
- The specific check-in containing the file
See also: finfo
- cgi (2nd tier command)
-
Usage: fossil ?cgi? FILE
This command causes Fossil to generate reply to a CGI request.
The FILE argument is the name of a control file that provides Fossil with important information such as where to find its repository. In a typical CGI deployment, FILE is the name of the CGI script and will typically look something like this:
#!/usr/bin/fossil repository: /home/somebody/project.db
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. Fossil ignores any lines that begin with "#".
The following control lines are recognized:
- repository: PATH
- Name of the Fossil repository
- directory:
- PATH Name of a directory containing many Fossil repositories whose names all end with ".fossil". There should only be one of "repository:" or "directory:"
- notfound: URL
- When in "directory:" mode, redirect to URL if no suitable repository is found.
- repolist
- When in "directory:" mode, display a page showing a list of available repositories if the URL is "/".
- localauth
- Grant administrator privileges to connections from 127.0.0.1 or ::1.
- nossl
- Signal that no SSL connections are available.
- nocompress
- Do not compress HTTP replies.
- skin: LABEL
- Use the built-in skin called LABEL rather than the default, or the default if LABEL is empty. If there are no skins called LABEL then this line is a no-op.
- files: GLOBLIST
- GLOBLIST is a comma-separated list of GLOB patterns that specify files that can be returned verbatim. This feature allows Fossil to act as a web server returning static content.
- setenv: NAME VALUE
- Set environment variable NAME to VALUE. Or if VALUE is omitted, unset NAME.
- HOME: PATH
- Shorthand for "setenv: HOME PATH"
- cgi-debug: FILE
- Causing debugging information to be written into FILE.
- errorlog: FILE
- Warnings, errors, and panics written to FILE.
- timeout: SECONDS
- Do not run for longer than SECONDS. The default timeout is FOSSIL_DEFAULT_TIMEOUT (600) seconds.
- extroot: DIR
- Directory that is the root of the sub-CGI tree on the /ext page.
- redirect: REPO URL
- Extract the "name" query parameter and search REPO for a check-in or ticket that matches the value of "name", then redirect to URL. There can be multiple "redirect:" lines that are processed in order. If the REPO is "*", then an unconditional redirect to URL is taken.
- jsmode: VALUE
- Specifies the delivery mode for JavaScript files. See the help text for the --jsmode flag of the http command.
- mainmenu: FILE
- Override the mainmenu config setting with the contents of the given file.
Most CGI files contain only a "repository:" line. It is uncommon to use any other option.
The lines are processed in the order they are read, which is most significant for "errorlog:", which should be set before "repository:" so that any warnings from the database when opening the repository go to that log file.
- changes (1st tier command)
- status (1st tier command)
-
Usage: fossil changes|status ?OPTIONS? ?PATHS ...?
Report the change status of files in the current check-out. If one or more PATHS are specified, only changes among the named files and directories are reported. Directories are searched recursively.
The status command is similar to the changes command, except it lacks several of the options supported by changes and it has its own header and footer information. The header information is a subset of that shown by the info command, and the footer shows if there are any forks. Change type classification is always enabled for the status command.
Each line of output is the name of a changed file, with paths shown according to the "relative-paths" setting, unless overridden by the --abs-paths or --rel-paths options.
By default, all changed files are selected for display. This behavior can be overridden by using one or more filter options (listed below), in which case only files with the specified change type(s) are shown. As a special case, the --no-merge option does not inhibit this default. This default shows exactly the set of changes that would be checked- in by the commit command.
If no filter options are used, or if the --merge option is used, the artifact hash of each merge contributor check-in version is displayed at the end of the report. The --no-merge option is useful to display the default set of changed files without the merge contributors.
If change type classification is enabled, each output line starts with a code describing the file's change type, e.g. EDITED or RENAMED. It is enabled by default unless exactly one change type is selected. For the purposes of determining the default, --changed counts as selecting one change type. The default can be overridden by the --classify or --no-classify options.
--edited and --updated produce disjoint sets. --updated shows a file only when it is identical to that of its merge contributor, and the change type classification is UPDATED_BY_MERGE or UPDATED_BY_INTEGRATE. If the file had to be merged with any other changes, it is considered to be merged or conflicted and therefore will be shown by --edited, not --updated, with types EDITED or CONFLICT. The --changed option can be used to display the union of --edited and --updated.
--differ is so named because it lists all the differences between the checked-out version and the check-out directory. In addition to the default changes (excluding --merge), it lists extra files which (if ignore-glob is set correctly) may be worth adding. Prior to doing a commit, it is good practice to check --differ to see not only which changes would be committed but also if any files should be added.
If both --merge and --no-merge are used, --no-merge has priority. The same is true of --classify and --no-classify.
The "fossil changes --extra" command is equivalent to "fossil extras".
General options:
- --abs-paths
- Display absolute pathnames
- -b|--brief
- Show a single keyword for the status
- --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
- chat (1st tier command)
-
Usage: fossil chat [SUBCOMMAND] [--remote URL] [ARGS...]
This command performs actions associated with the /chat instance on the default remote Fossil repository (the Fossil repository whose URL shows when you run the "fossil remote" command) or to the URL specified by the --remote option. If there is no default remote Fossil repository and the --remote option is omitted, then this command fails with an error.
Subcommands:
- fossil chat
- When there is no SUBCOMMAND (when this command is simply "fossil chat") the response is to bring up a web-browser window to the chatroom on the default system web-browser. You can accomplish the same by typing the appropriate URL into the web-browser yourself. This command is merely a convenience for command-line oriented people.
- fossil chat pull
- Copy chat content from the server down into the local clone,
as a backup or archive. Setup privilege is required on the server.
- --all
- Download all chat content. Normally only previously undownloaded content is retrieved.
- --debug
- Additional debugging output
- --out DATABASE
- Store CHAT table in separate database file DATABASE rather than adding to local clone
- --unsafe
- Allow the use of unencrypted http://
- fossil chat send [ARGUMENTS]
- This command sends a new message to the chatroom. The message
to be sent is determined by arguments as follows:
- -f|--file FILENAME
- File to attach to the message
- --as FILENAME2
- Causes --file FILENAME to be sent with the attachment name FILENAME2
- -m|--message TEXT
- Text of the chat message
- --remote URL
- Send to this remote URL
- --unsafe
- Allow the use of unencrypted http://
- fossil chat url
- Show the default URL used to access the chat server.
Additional subcommands may be added in the future.
- chat-alert-sound (setting)
- This is the name of the builtin sound file to use for the alert tone. The value must be the name of a builtin WAV file.
- chat-initial-history (setting)
- If this setting has an integer value of N, then when /chat first starts up it initializes the screen with the N most recent chat messages. If N is zero, then all chat messages are loaded.
- chat-inline-images (boolean setting)
- Specifies whether posted images in /chat should default to being displayed inline or as downloadable links. Each chat user can change this value for their current chat session in the UI.
- chat-keep-count (setting)
- When /chat is cleaning up older messages, it will always keep the most recent chat-keep-count messages, even if some of those messages are older than the discard threshold. If this value is zero, then /chat is free to delete all historic messages once they are old enough.
- chat-keep-days (setting)
-
The /chat subsystem will try to discard messages that are older then
chat-keep-days. The value of chat-keep-days can be a floating point
number. So, for example, if you only want to keep chat messages for
12 hours, set this value to 0.5.
A value of 0.0 or less means that messages are retained forever.
- chat-poll-timeout (setting)
-
On an HTTP request to /chat-poll, if there is no new content available,
the reply is delayed waiting for new content to arrive. (This is the
"long poll" strategy of event delivery to the client.) This setting
determines approximately how long /chat-poll will delay before giving
up and returning an empty reply. The default value is about 7 minutes,
which works well for Fossil behind the althttpd web server. Other
server environments may choose a longer or shorter delay.
For maximum efficiency, it is best to choose the longest delay that does not cause timeouts in intermediate proxies or web server.
- chat-timeline-user (setting)
-
If this setting is defined and is not an empty string, then
timeline events are posted to the chat as they arrive. The synthesized
chat messages appear to come from the user identified by this setting,
not the user on the timeline event.
All chat messages that come from the chat-timeline-user are interpreted as text/x-fossil-wiki instead of as text/x-markdown. For this reason, the chat-timeline-user name should probably not be a real user.
- checkout (2nd tier command)
- co (alias)
-
Usage: fossil checkout ?VERSION | --latest? ?OPTIONS?
or: fossil co ?VERSION | --latest? ?OPTIONS?
NOTE: Most people use "fossil update" instead of "fossil checkout" for day-to-day operations. If you are new to Fossil and trying to learn your way around, it is recommended that you become familiar with the "fossil update" command first.
This command changes the current check-out to the version specified as an argument. The command aborts if there are edited files in the current check-out unless the --force option is used. The --keep option leaves files on disk unchanged, except the manifest and manifest.uuid files.
The --latest flag can be used in place of VERSION to check-out the latest version in the repository.
Options:
- --force
- Ignore edited files in the current check-out
- --keep
- Only update the manifest file(s)
- --force-missing
- Force check-out even if content is missing
- --setmtime
- Set timestamps of all files to match their SCM-side times (the timestamp of the last check-in which modified them)
See also: update
- cherry-pick (alias)
- cherrypick (1st tier command)
- merge (1st tier command)
-
Usage: fossil merge ?OPTIONS? ?VERSION ...?
Or: fossil cherrypick ?OPTIONS? ?VERSION ...?The argument VERSION is a version that should be merged into the current check-out. All changes from VERSION back to the nearest common ancestor are merged. Except, if either of the --cherrypick or --backout options are used only the changes associated with the single check-in VERSION are merged. The --backout option causes the changes associated with VERSION to be removed from the current check-out rather than added. When invoked with the name "cherrypick" instead of "merge", this command works exactly like "merge --cherrypick".
Files which are renamed in the merged-in branch will be renamed in the current check-out.
If the VERSION argument is omitted, then Fossil attempts to find a recent fork on the current branch to merge.
Note that this command does not commit the merge, as that is a separate step.
If there are multiple VERSION arguments, then each VERSION is merged (or cherrypicked) in the order that they appear on the command-line.
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.
- --cherrypick
- Do a cherrypick merge VERSION into the current check-out. A cherrypick merge pulls in the changes of the single check-in VERSION, rather than all changes back to the nearest common ancestor.
- -f|--force
- Force the merge even if it would be a no-op
- --force-missing
- Force the merge even if there is missing content
- --integrate
- Merged branch will be closed when committing
- -K|--keep-merge-files
- On merge conflict, retain the temporary files used for merging, named *-baseline, *-original, and *-merge.
- -n|--dry-run
- Do not actually change files on disk
- --nosync
- Do not auto-sync prior to merging
- --noundo
- Do not record changes in the undo log
- -v|--verbose
- Show additional details of the merge
- ci (alias)
- commit (1st tier command)
-
Usage: fossil commit ?OPTIONS? ?FILE...?
or: fossil ci ?OPTIONS? ?FILE...?
Create a new version containing all of the changes in the current check-out. You will be prompted to enter a check-in comment unless the comment has been specified on the command-line using "-m" or a file containing the comment using -M. The editor defined in the "editor" fossil option (see fossil help set) will be used, or from the "VISUAL" or "EDITOR" environment variables (in that order) if no editor is set.
All files that have changed will be committed unless some subset of files is specified on the command line.
The --branch option followed by a branch name causes the new check-in to be placed in a newly-created branch with the name passed to the --branch option.
Use the --branchcolor option followed by a color name (ex: '#ffc0c0') to specify the background color of entries in the new branch when shown in the web timeline interface. The use of the --branchcolor option is not recommended. Instead, let Fossil choose the branch color automatically.
The --bgcolor option works like --branchcolor but only sets the background color for a single check-in. Subsequent check-ins revert to the default color.
A check-in is not permitted to fork unless the --allow-fork option appears. An empty check-in (i.e. with nothing changed) is not allowed unless the --allow-empty option appears. A check-in may not be older than its ancestor unless the --allow-older option appears. If any 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
- --ignore-clock-skew
- If a clock skew is detected, ignore it and behave as if the user had entered 'yes' to the question of whether to proceed despite the skew.
- --ignore-oversize
- Do not warn the user about oversized files
- --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
- -v|--verbose
- Show a diff in the commit message prompt
- --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
- --nosync
- Do not auto-sync prior to committing
- --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.
- clean (1st tier command)
-
Usage: fossil clean ?OPTIONS? ?PATH ...?
Delete all "extra" files in the source tree. "Extra" files are files that are not officially part of the check-out. If one or more PATH arguments appear, then only the files named, or files contained with directories named, will be removed.
If the --prompt option is used, prompts are issued to confirm the permanent removal of each file. Otherwise, files are backed up to the undo buffer prior to removal, and prompts are issued only for files whose removal cannot be undone due to their large size or due to --disable-undo being used.
The --force option treats all prompts as having been answered yes, whereas --no-prompt treats them as having been answered no.
Files matching any glob pattern specified by the --clean option are deleted without prompting, and the removal cannot be undone.
No file that matches glob patterns specified by --ignore or --keep will ever be deleted. Files and subdirectories whose names begin with "." are automatically ignored unless the --dotfiles option is used.
The default values for --clean, --ignore, and --keep are determined by the (versionable) clean-glob, ignore-glob, and keep-glob settings.
The --verily option ignores the keep-glob and ignore-glob settings and turns on --force, --emptydirs, --dotfiles, and --disable-undo. Use the --verily option when you really want to clean up everything. Extreme care should be exercised when using the --verily option.
Options:
- --allckouts
- Check for empty directories within any check-outs that may be nested within the current one. This option should be used with great care because the empty-dirs setting (and other applicable settings) belonging to the other repositories, if any, will not be checked.
- --case-sensitive BOOL
- Override case-sensitive setting
- --dirsonly
- Only remove empty directories. No files will be removed. Using this option will automatically enable the --emptydirs option as well.
- --disable-undo
- WARNING: This option disables use of the undo mechanism for this clean operation and should be used with extreme caution.
- --dotfiles
- Include files beginning with a dot (".")
- --emptydirs
- Remove any empty directories that are not explicitly exempted via the empty-dirs setting or another applicable setting or command line argument. Matching files, if any, are removed prior to 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
- Do not prompt the user for input and assume an answer of 'No' for every question
- --temp
- Remove only Fossil-generated temporary files
- -v|--verbose
- Show all files as they are removed
- clean-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files that the "clean" command will delete without prompting or allowing undo. Example: *.a,*.o,*.so The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax
- clearsign (boolean setting)
- When enabled, fossil will attempt to sign all commits with gpg. When disabled, commits will be unsigned.
- clone (1st tier command)
-
Usage: fossil clone ?OPTIONS? URI ?FILENAME?
Make a clone of a repository specified by URI in the local file named FILENAME. If FILENAME is omitted, then an appropriate filename is deduced from last element of the path in the URL.
URI may be one of the following forms ([...] denotes optional elements):
- HTTP/HTTPS protocol:
http[s]://[userid[:password]@]host[:port][/path]
-
SSH protocol:
ssh://[userid@]host[:port]/path/to/repo.fossil[?fossil=path/fossil.exe]
-
Filesystem:
[file://]path/to/repo.fossil
For ssh and filesystem, path must have an extra leading '/' to use an absolute path.
Use %HH escapes for special characters in the userid and password. For example "%40" in place of "@", "%2f" in place of "/", and "%3a" in place of ":".
Note that in Fossil (in contrast to some other DVCSes) a repository is distinct from a check-out. Cloning a repository is not the same thing as opening a repository. This command always clones the repository. This command might also open the repository, but only if the --no-open option is omitted and either the --workdir option is included or the FILENAME argument is omitted. Use the separate open command to open a repository that was previously cloned and already exists on the local machine.
By default, the current login name is used to create the default admin user for the new clone. This can be overridden using the -A|--admin-user parameter.
Options:
- -A|--admin-user USERNAME
- Make USERNAME the administrator
- -B|--httpauth USER:PASS
- Add HTTP Basic Authorization to requests
- --nested
- Allow opening a repository inside an opened check-out
- --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
- -c|--ssh-command SSH
- Use SSH as the "ssh" command
- --ssl-identity FILENAME
- Use the SSL identity if requested by the server
- --transport-command CMD
- Use CMD to move messages to the server and back
- -u|--unversioned
- Also sync unversioned content
- -v|--verbose
- Show more statistics in output
- --workdir DIR
- Also open a check-out in DIR
- --xverbose
- Extra debugging output
- HTTP/HTTPS protocol:
- close (2nd tier command)
-
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:
- -f|--force
- Necessary to close a check-out with uncommitted changes
See also: open
- comment-format (setting)
-
Set the default options for printing timeline comments to the console.
The global --comfmtflags command-line option (or alias --comment-format) overrides this setting.
Possible values are:
- 1
- Activate the legacy comment printing format (default).
Or a bitwise combination of the following flags:
- 0
- Activate the newer (non-legacy) comment printing format.
- 2
- Trim leading and trailing CR and LF characters.
- 4
- Trim leading and trailing white space characters.
- 8
- Attempt to break lines on word boundaries.
- 16
- Break lines before the original comment embedded in other text.
Note: To preserve line breaks, activate the newer (non-legacy) comment printing format (i.e. set to "0", or a combination not including "1").
Note: The options for timeline comments displayed on the web UI can be configured through the /setup_timeline web page.
- configuration (2nd tier command)
-
Usage: fossil configuration METHOD ... ?OPTIONS?
Where METHOD is one of: export import merge pull push reset.
- 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 REPO
- Affect repository REPO with changes
- crlf-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files in which it is allowed to have CR, CR+LF or mixed line endings, suppressing Fossil's normal warning about this. Set it to "*" to disable CR+LF checking entirely. Example: *.md,*.txt The crnl-glob setting is a compatibility alias.
- crnl-glob (versionable block-text setting)
- This is an alias for the crlf-glob setting.
- dbstat (1st tier command)
-
Usage: fossil dbstat OPTIONS
Shows statistics and global information about the repository and/or verify the integrity of a repository.
Options:
- -b|--brief
- Only show essential elements
- --db-check
- Run "PRAGMA quick_check" on the repository database
- --db-verify
- Run a full verification of the repository integrity. This involves decoding and reparsing all artifacts and can take significant time.
- --omit-version-info
- Omit the SQLite and Fossil version information
- deconstruct (2nd tier command)
-
Usage fossil deconstruct ?OPTIONS? DESTINATION
This command exports all artifacts of a given repository and writes all artifacts to the file system. The DESTINATION directory will be populated with subdirectories AA and files AA/BBBBBBBBB.., where AABBBBBBBBB.. is the 40+ character artifact ID, AA the first 2 characters. If -L|--prefixlength is given, the length (default 2) of the directory prefix can be set to 0,1,..,9 characters.
Options:
- -R|--repository REPO
- Deconstruct given REPOSITORY
- -K|--keep-rid1
- Save the filename of the artifact with RID=1 to the file .rid1 in the DESTINATION directory
- -L|--prefixlength N
- Set the length of the names of the DESTINATION subdirectories to N
- --private
- Include private artifacts
- -P|--keep-private
- Save the list of private artifacts to the file .private in the DESTINATION directory (implies the --private option)
- default-csp (block-text setting)
-
The text of the Content Security Policy that is included
in the Content-Security-Policy: header field of the HTTP
reply and in the default HTML <head> section that is added when the
skin header does not specify a <head> section. The text "$nonce"
is replaced by the random nonce that is created for each web page.
If this setting is an empty string or is omitted, then the following default Content Security Policy is used:
default-src 'self' data:; script-src 'self' 'nonce-$nonce'; style-src 'self' 'unsafe-inline'; img-src * data:;
The default CSP is recommended. The main reason to change this setting would be to add CDNs from which it is safe to load additional content.
- default-perms (setting)
- Permissions given automatically to new users. For more information on permissions see the Users page in Server Administration of the HTTP UI.
- default-skin (setting)
- If the text value if this setting is the name of a built-in skin then the named skin becomes the default skin for the repository.
- delete (1st tier command)
- forget (2nd tier command)
- rm (1st tier command)
-
Usage: fossil rm|delete|forget FILE1 ?FILE2 ...?
Remove one or more files or directories from the repository.
The 'rm' and 'delete' commands do NOT normally remove the files from disk. They just mark the files as no longer being part of the project. In other words, future changes to the named files will not be versioned. However, the default behavior of this command may be overridden via the command line options listed below and/or the 'mv-rm-files' setting.
The 'forget' command never removes files from disk, even when the command line options and/or the 'mv-rm-files' setting would otherwise require it to do so.
WARNING: If the "--hard" option is specified -OR- the "mv-rm-files" setting is non-zero, files WILL BE removed from disk as well. This does NOT apply to the 'forget' command.
Options:
- --soft
- Skip removing files from the check-out. This supersedes the --hard option.
- --hard
- Remove files from the check-out
- --case-sensitive BOOL
- Override the case-sensitive setting
- -n|--dry-run
- If given, display instead of run actions.
- --reset
- Reset the DELETED state of a check-out, such that all newly-rm'd (but not yet committed) files are no longer removed. No flags other than --verbose or --dry-run may be used with --reset.
- -v|--verbose
- Outputs information about each --reset file. Only usable with --reset.
- descendants (2nd tier command)
-
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 REPO
- Extract info from repository REPO
- -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.
- describe (1st tier command)
-
Usage: fossil describe ?VERSION? ?OPTIONS?
Provide a description of the given VERSION by showing a non-propagating tag of the youngest tagged ancestor, followed by the number of commits since that, and the short hash of VERSION. Only tags applied to a single check-in are considered.
If no VERSION is provided, describe the currently checked-out version.
If VERSION and the found ancestor refer to the same commit, the last two components are omitted, unless --long is provided. When no fitting tagged ancestor is found, show only the short hash of VERSION.
Options:
- --digits
- Display so many hex digits of the hash (default: the larger of 6 and the 'hash-digit' setting)
- -d|--dirty
- Show whether there are changes to be committed
- --long
- Always show all three components
- --match GLOB
- Consider only non-propagating tags matching GLOB
- detach (2nd tier command)
-
Usage: fossil detach ?REPOSITORY?
Change the project-code and make other changes to REPOSITORY so that it becomes a new and distinct child project. After being detached, REPOSITORY will not longer be able to push and pull from other clones of the original project. However REPOSITORY will still be able to pull from those other clones using the --from-parent-project option of the "fossil pull" command.
This is an experts-only command. You should not use this command unless you fully understand what you are doing.
The original use-case for this command was to create test repositories from real-world working repositories that could be safely altered by making strange commits or other changes, without having to worry that those test changes would leak back into the original project via an accidental auto-sync.
- diff (1st tier command)
- gdiff (1st tier command)
-
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 all unsaved changes currently in the working check-out.
The default output format is a "unified patch" (the same as the output of "diff -u" on most unix systems). Many alternative formats are available. A few of the more useful alternatives:
- --tk
- Pop up a Tcl/Tk-based GUI to show the diff
- --by
- Show a side-by-side diff in the default web browser
- -b
- Show a linear diff in the default web browser
- -y
- Show a text side-by-side diff
- --webpage
- Format output as HTML
- --webpage -y
- HTML output in the side-by-side format
The "--from VERSION" option is used to specify 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. Similarly, the "--to VERSION" option 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 "--branch BRANCHNAME" shows all the changes on the branch BRANCHNAME.
With the "--from VERSION" option, if VERSION is actually a directory name (not a tag or check-in hash) then the files under that directory are used as the baseline for the diff.
The "-i" command-line option forces the use of Fossil's own 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 "--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 the external diff program. This option overrides the "binary-glob" setting.
These command show differences between managed files. Use the "fossil xdiff" command to see differences in unmanaged files.
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
- -b|--browser
- Show the diff output in a web-browser
- --by
- Shorthand for "--browser -y"
- -ci|--checkin VERSION
- Show diff of all changes in VERSION
- --command PROG
- External diff program. Overrides "diff-command"
- -c|--context N
- Show N lines of context around each change, with negative N meaning show all content
- --dark
- Use dark mode for the Tcl/Tk-based GUI and HTML
- --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
- -r|--from VERSION
- Use VERSION as the baseline for the diff, or if VERSION is a directory name, use files in that directory as the baseline.
- -w|--ignore-all-space
- Ignore white space when comparing lines
- -i|--internal
- Use internal diff logic
- --invert
- Invert the diff
- --json
- Output formatted as JSON
- -n|--linenum
- Show line numbers
- -N|--new-file
- Alias for --verbose
- --numstat
- Show only the number of added and deleted lines
- -y|--side-by-side
- Side-by-side diff
- --strip-trailing-cr
- Strip trailing CR
- --tcl
- Tcl-formatted output used internally by --tk
- --tclsh PATH
- Tcl/Tk shell used for --tk (default: "tclsh")
- --tk
- Launch a Tcl/Tk GUI for display
- --to VERSION
- Select VERSION as target for the diff
- --undo
- Use the undo buffer as the baseline
- --unified
- Unified diff
- -v|--verbose
- Output complete text of added or deleted files
- -h|--versions
- Show compared versions in the diff header
- --webpage
- Format output as a stand-alone HTML webpage
- -W|--width N
- Width of lines in side-by-side diff
- -Z|--ignore-trailing-space
- Ignore changes to end-of-line whitespace
- diff-binary (boolean setting)
- If enabled, permit files that may be binary or that match the "binary-glob" setting to be used with external diff programs. If disabled, skip these files.
- diff-command (setting)
- The value is an external command to run when performing a diff. If undefined, the internal text diff will be used.
- dont-commit (boolean setting)
- If enabled, prevent committing to this repository, as an extra precaution against accidentally checking in to a repository intended to be read-only.
- dont-push (boolean setting)
- If enabled, prevent this repository from pushing from client to server. This can be used as an extra precaution to prevent accidental pushes to a public server from a private clone.
- dotfiles (versionable boolean setting)
- If enabled, include --dotfiles option for all compatible commands.
- editor (setting)
- The value is an external command that will launch the text editor command used for check-in comments.
- email-admin (setting)
- This is the email address for the human administrator for the system. Abuse and trouble reports and password reset requests are send here.
- email-listid (setting)
- If this setting is not an empty string, then it becomes the argument to a "List-ID:" header that is added to all out-bound notification emails.
- email-renew-interval (setting)
- If this setting as an integer N that is 14 or greater then email notification is suspended for subscriptions that have a "last contact time" of more than N days ago. The "last contact time" is recorded in the SUBSCRIBER.LASTCONTACT entry of the database. Logging in, sending a forum post, editing a wiki page, changing subscription settings at /alerts, or visiting /renew all update the last contact time. If this setting is not an integer value or is less than 14 or undefined, then subscriptions never expire.
- email-self (setting)
- This is the email address for the repository. Outbound emails add this email address as the "From:" field.
- email-send-command (setting)
- This is a command to which outbound email content is piped when the email-send-method is set to "pipe". The command must extract recipient, sender, subject, and all other relevant information from the email header.
- email-send-db (setting)
- This is an SQLite database file into which outbound emails are written if the email-send-method is set to "db".
- email-send-dir (setting)
- This is a directory into which outbound emails are written as individual files if the email-send-method is set to "dir".
- email-send-method (setting)
- Determine the method used to send email. Allowed values are "off", "relay", "pipe", "dir", "db", and "stdout". The "off" value means no email is ever sent. The "relay" value means emails are sent to an Mail Sending Agent using SMTP located at email-send-relayhost. The "pipe" value means email messages are piped into a command determined by the email-send-command setting. The "dir" value means emails are written to individual files in a directory determined by the email-send-dir setting. The "db" value means that emails are added to an SQLite database named by the* email-send-db setting. The "stdout" value writes email text to standard output, for debugging.
- email-send-relayhost (setting)
- This is the hostname and TCP port to which output email messages are sent when email-send-method is "relay". There should be an SMTP server configured as a Mail Submission Agent listening on the designated host and port and all times.
- email-subname (setting)
- This is a short name used to identifies the repository in the Subject: line of email alerts. Traditionally this name is included in square brackets. Examples: "[fossil-src]", "[sqlite-src]".
- email-url (setting)
- This is the main URL used to access the repository for cloning or syncing or for operating the web interface. It is also the basename for hyperlinks included in email alert text. Omit the trailing "/". If the repository is not intended to be a long-running server and will not be sending email notifications, then leave this setting blank.
- empty-dirs (versionable block-text setting)
- The value is a list of pathnames parsed according to the same rules as the *-glob settings. On update and checkout commands, if no directory exists with that name, an empty directory will be be created, even if it must create one or more parent directories.
- encoding-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files that the "commit" command will ignore when issuing warnings about text files that may use another encoding than ASCII or UTF-8. Set to "*" to disable encoding checking. Example: *.md,*.txt The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax
- exec-rel-paths (boolean setting)
- When executing certain external commands (e.g. diff and gdiff), use relative paths.
- export (2nd tier command)
- This command is deprecated. Use "fossil git export" instead.
- extras (1st tier command)
-
Usage: fossil extras ?OPTIONS? ?PATH1 ...?
Print a list of all files in the source tree that are not part of the current check-out. See also the "clean" command. If paths are specified, only files in the given directories will be listed.
Files and subdirectories whose names begin with "." are normally ignored but can be included by adding the --dotfiles option.
Files whose names match any of the glob patterns in the "ignore-glob" setting are ignored. This setting can be overridden by the --ignore option, whose CSG argument is a comma-separated list of glob patterns.
Pathnames are displayed according to the "relative-paths" setting, unless overridden by the --abs-paths or --rel-paths options.
Options:
- --abs-paths
- Display absolute pathnames
- --case-sensitive BOOL
- Override case-sensitive setting
- --dotfiles
- Include files beginning with a dot (".")
- --header
- Identify the repository if there are extras
- --ignore CSG
- Ignore files matching patterns from the argument
- --rel-paths
- Display pathnames relative to the current working directory
- --tree
- Show output in the tree format
- fileedit-glob (block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files which are allowed to be edited using the /fileedit page. An empty list suppresses the feature. Example: *.md,*.txt The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax Note that /fileedit cannot edit binary files, so the list should not contain any globs for, e.g., images or PDFs.
- finfo (1st tier command)
-
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.
The -i mode will print various facts about FILENAME, including its hash and the check-in and time when the current version of the file was created. Use -v for additional information. Add the -r VERSION option to see similar information about the same file for the check-in specified by VERSION.
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.
- -i|--id
- Print the artifact ID
- -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)
- -v|--verbose
- On the -i option, show all check-ins that use the file, not just the earliest check-in
- -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
- forbid-delta-manifests (boolean setting)
- If enabled on a client, new delta manifests are prohibited on commits. If enabled on a server, whenever a client attempts to obtain a check-in lock during auto-sync, the server will send the "pragma avoid-delta-manifests" statement in its reply, which will cause the client to avoid generating a delta manifest.
- forum-close-policy (boolean setting)
- If true, forum moderators may close/re-open forum posts, and reply to closed posts. If false, only administrators may do so. Note that this only affects the forum web UI, not post-closing tags which arrive via the command-line or from synchronization with a remote.
- forum-title (setting)
- This is the name or "title" of the Forum for this repository. The default is just "Forum". But in some setups, admins might want to change it to "Developer Forum" or "User Forum" or whatever other name seems more appropriate for the particular usage.
- fts-config (2nd tier command)
-
Usage: fossil fts-config ?SUBCOMMAND? ?ARGUMENT?
The "fossil fts-config" command configures the full-text search capabilities of the repository. Subcommands:
- reindex
- Rebuild the search index. This is a no-op if index search is disabled
- index (on|off)
- Turn the search index on or off
- enable cdtwef
- Enable various kinds of search. c=Check-ins, d=Documents, t=Tickets, w=Wiki, e=Tech Notes, f=Forum.
- disable cdtwef
- Disable various kinds of search
- tokenizer VALUE
- Select a tokenizer for indexed search. VALUE may be one of (porter, on, off, trigram, unicode61), and "on" is equivalent to "porter". Unindexed search never uses tokenization or stemming.
The current search settings are displayed after any changes are applied. Run this command with no arguments to simply see the settings.
- fusefs (2nd tier command)
-
Usage: fossil fusefs [--debug] DIRECTORY
This command uses the Fuse Filesystem (FuseFS) to mount a directory at DIRECTORY that contains the content of all check-ins in the repository. The names of files are DIRECTORY/checkins/VERSION/PATH where DIRECTORY is the root of the mount, VERSION is any valid check-in name (examples: "trunk" or "tip" or a tag or any unique prefix of an artifact hash, etc) and PATH is the pathname of the file in the check-in. If DIRECTORY does not exist, then an attempt is made to create it.
The DIRECTORY/checkins directory is not searchable so one cannot do "ls DIRECTORY/checkins" to get a listing of all possible check-in names. There are countless variations on check-in names and it is impractical to list them all. But all other directories are searchable and so the "ls" command will work everywhere else in the fusefs file hierarchy.
The FuseFS typically only works on Linux, and then only on Linux systems that have the right kernel drivers and have installed the appropriate support libraries.
After stopping the "fossil fusefs" command, it might also be necessary to run "fusermount -u DIRECTORY" to reset the FuseFS before using it again.
- gdiff-command (setting)
- The value is an external command to run when performing a graphical diff. If undefined, text diff will be used.
- git (2nd tier command)
-
Usage: fossil git SUBCOMMAND
Do incremental import or export operations between Fossil and Git. Subcommands:
- fossil git export [MIRROR] [OPTIONS]
- Write content from the Fossil repository into the Git repository
in directory MIRROR. The Git repository is created if it does not
already exist. If the Git repository does already exist, then
new content added to fossil since the previous export is appended.
Repeat this command whenever new check-ins are added to the Fossil repository in order to reflect those changes into the mirror. If the MIRROR option is omitted, the repository from the previous invocation is used.
The MIRROR directory will contain a subdirectory named ".mirror_state" that contains information that Fossil needs to do incremental exports. Do not attempt to manage or edit the files in that directory since doing so can disrupt future incremental exports.
Options:
- --autopush URL
- Automatically do a 'git push' to URL. The URL is remembered and used on subsequent exports to the same repository. Or if URL is "off" the auto-push mechanism is disabled
- --debug FILE
- Write fast-export text to FILE rather than piping it into "git fast-import"
- -f|--force
- Do the export even if nothing has changed
- --if-mirrored
- No-op if the mirror does not already exist
- --limit N
- Add no more than N new check-ins to MIRROR. Useful for debugging
- --mainbranch NAME
- Use NAME as the name of the main branch in Git. The "trunk" branch of the Fossil repository is mapped into this name. "master" is used if this option is omitted.
- -q|--quiet
- Reduce output. Repeat for even less output.
- -v|--verbose
- More output
- fossil git import MIRROR
- TBD...
- fossil git status
- Show the status of the current Git mirror, if there is one.
- -q|--quiet
- No output if there is nothing to report
- gmerge-command (setting)
-
The value is a graphical merge conflict resolver command operating
on four files. Examples:
kdiff3 "%baseline" "%original" "%merge" -o "%output" xxdiff "%original" "%baseline" "%merge" -M "%output" meld "%baseline" "%original" "%merge" --output "%output"
- grep (1st tier command)
-
Usage: fossil grep [OPTIONS] PATTERN FILENAME ...
Attempt to match the given POSIX extended regular expression PATTERN over all historic versions of FILENAME. The search begins with the most recent version of the file and moves backwards in time. Multiple FILENAMEs can be specified, in which case all named files are searched in reverse chronological order.
For details of the supported regular expression dialect, see https://fossil-scm.org/fossil/doc/trunk/www/grep.md
Options:
- -c|--count
- Suppress normal output; instead print a count of the number of matching files
- -i|--ignore-case
- Ignore case
- -l|--files-with-matches
- List only hash for each match
- --once
- Stop searching after the first match
- -s|--no-messages
- Suppress error messages about nonexistent or unreadable files
- -v|--invert-match
- Invert the sense of matching. Show only files that have no matches. Implies -l
- --verbose
- Show each file as it is analyzed
- hash-digits (setting)
- The number of hexadecimal digits of the SHA3 hash to display.
- hash-policy (2nd tier command)
-
Usage: fossil hash-policy ?NEW-POLICY?
Query or set the hash policy for the current repository. Available hash policies are as follows:
- sha1
- New artifact names are created using SHA1
- auto
- New artifact names are created using SHA1, but automatically change the policy to "sha3" when any SHA3 artifact enters the repository.
- sha3
- New artifact names are created using SHA3, but older artifacts with SHA1 names may be reused.
- sha3-only
- Use only SHA3 artifact names. Do not reuse legacy SHA1 names.
- shun-sha1
- Shun any SHA1 artifacts received by sync operations other than clones. Older legacy SHA1 artifacts are allowed during a clone.
The default hash policy for existing repositories is "auto", which will immediately promote to "sha3" if the repository contains one or more artifacts with SHA3 names. The default hash policy for new repositories is "shun-sha1".
- help (1st tier command)
-
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
- -v|--verbose
- List both names and help text
- -x|--aux
- List only auxiliary commands
- -w|--www
- List all web pages
- -f|--full
- List full set of commands (including auxiliary and unsupported "test" commands), options, settings, and web pages
- -e|--everything
- List all help on all topics
These options can be used when TOPIC is present:
- -h|--html
- Format output as HTML rather than plain text
- -c|--commands
- Restrict TOPIC search to commands
- hook (2nd tier command)
-
Usage: fossil hook COMMAND ...
Commands include:
- fossil hook add --command COMMAND --type TYPE --sequence NUMBER
- Create a new hook. The --command and --type arguments are required. --sequence is optional.
- fossil hook delete ID ...
- Delete one or more hooks by their IDs. ID can be "all" to delete all hooks. Caution: There is no "undo" for this operation. Deleted hooks are permanently lost.
- fossil hook edit --command COMMAND --type TYPE --sequence NUMBER ID ...
- Make changes to one or more existing hooks. The ID argument
is either a hook-id, or a list of hook-ids, or the keyword
"all". For example, to disable hook number 2, use:
fossil hook edit --type disabled 2
- fossil hook list
- Show all current hooks
- fossil hook status
- Print the values of CONFIG table entries that are relevant to hook processing. Used for debugging.
- fossil hook test [OPTIONS] ID
- Run the hook script given by ID for testing purposes.
Options:
- --dry-run
- Print the script on stdout rather than run it
- --base-rcvid N
- Pretend that the hook-last-rcvid value is N
- --new-rcvid M
- Pretend that the last rcvid valud is M
- --aux-file NAME
- NAME is substituted for %A in the script
The --base-rcvid and --new-rcvid options are silently ignored if the hook type is not "after-receive". The default values for --base-rcvid and --new-rcvid cause the last receive to be processed.
- hooks (block-text setting)
-
The "hooks" setting contains JSON that describes all defined
hooks. The value is an array of objects. Each object describes
a single hook. Example:
{ "type": "after-receive", // type of hook "cmd": "command-to-run", // command to run "seq": 50 // run in this order }
- http (2nd tier command)
-
Usage: fossil http ?REPOSITORY? ?OPTIONS?
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 REPOSITORY argument is the name of the repository.
If REPOSITORY is a directory that contains one or more repositories, either directly in REPOSITORY itself or in subdirectories, and with names of the form "*.fossil" then a prefix of the URL pathname selects from among the various repositories. If the pathname does not select a valid repository and the --notfound option is available, then the server redirects (HTTP code 302) to the URL of --notfound. When REPOSITORY is a directory, the pathname must contain only alphanumerics, "_", "/", "-" and "." and no "-" may occur after a "/" and every "." must be surrounded on both sides by alphanumerics or else a 404 error is returned. Static content files in the directory are returned if they match comma-separate GLOB pattern specified by --files and do not match "*.fossil*" and have a well-known suffix.
Options:
- --acme
- Deliver files from the ".well-known" subdirectory
- --baseurl URL
- Base URL (useful with reverse proxies)
- --cert FILE
- Use TLS (HTTPS) encryption with the certificate (the fullchain.pem) taken from FILE.
- --chroot DIR
- Use directory for chroot instead of repository path.
- --ckout-alias N
- Treat URIs of the form /doc/N/... as if they were /doc/ckout/...
- --extroot DIR
- Document root for the /ext extension mechanism
- --files GLOB
- Comma-separate glob patterns for static file to serve
- --host NAME
- DNS Hostname of the server
- --https
- The HTTP request originated from https but has already been decoded by a reverse proxy. Hence, URLs created by Fossil should use "https:" rather than "http:".
- --in FILE
- Take input from FILE instead of standard input
- --ipaddr ADDR
- Assume the request comes from the given IP address
- --jsmode MODE
- Determine how JavaScript is delivered with pages.
Mode can be one of:
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.- inline
- All JavaScript is inserted inline at one or more points in the HTML file.
- separate
- Separate HTTP requests are made for each JavaScript file.
- bundled
- Groups JavaScript files into one or more bundled requests which concatenate scripts together.
- --localauth
- Connections from localhost are given "setup" privileges without having to log in
- --mainmenu FILE
- Override the mainmenu config setting with the contents of the given file
- --nocompress
- Do not compress HTTP replies
- --nodelay
- Omit backoffice processing if it would delay process exit
- --nojail
- Drop root privilege but do not enter the chroot jail
- --nossl
- Do not do http: to https: redirects, regardless of the redirect-to-https setting.
- --notfound URL
- Use URL as the "HTTP 404, object not found" page
- --out FILE
- Write the HTTP reply to FILE instead of to standard output
- --pkey FILE
- Read the private key used for TLS from FILE
- --repolist
- If REPOSITORY is directory, URL "/" lists all repos
- --scgi
- Interpret input as SCGI rather than HTTP
- --skin LABEL
- Use override skin LABEL. Use an empty string ("") to force use of the current local skin config.
- --th-trace
- Trace TH1 execution (for debugging purposes)
- --usepidkey
- Use saved encryption key from parent process. This is only necessary when using SEE on Windows or Linux.
- http-port (setting)
- The default TCP/IP port number to use by the "server" and "ui" commands.
- https-login (boolean setting)
- If true, then the Fossil web server will redirect unencrypted login screen requests to HTTPS.
- ignore-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files that the "add", "addremove", "clean", and "extras" commands will ignore. Example: *.log,notes.txt The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax
- import (2nd tier command)
-
Usage: fossil import ?--git? ?OPTIONS? NEW-REPOSITORY ?INPUT-FILE?
or: fossil import --svn ?OPTIONS? NEW-REPOSITORY ?INPUT-FILE?
Read interchange format generated by another VCS and use it to construct a new Fossil repository named by the NEW-REPOSITORY argument. If no input file is supplied the interchange format data is read from standard input.
The following formats are currently understood by this command
- --git
- Import from the git-fast-export file format (default)
Options:
- --import-marks
- FILE Restore marks table from FILE
- --export-marks
- FILE Save marks table to FILE
- --rename-master NAME Renames the master branch to NAME
- --use-author
- Uses author as the committer
- --attribute
- "EMAIL USER" Attribute commits to USER instead of Git committer EMAIL address
- --svn
- Import from the svnadmin-dump file format. The default
behaviour (unless overridden by --flat) is to treat 3
folders in the SVN root as special, following the
common layout of SVN repositories. These are (by
default) trunk/, branches/ and tags/. The SVN --deltas
format is supported but not required.
Options:
- --trunk FOLDER
- Name of trunk folder
- --branches FOLDER
- Name of branches folder
- --tags FOLDER
- Name of tags folder
- --base PATH
- Path to project root in repository
- --flat
- The whole dump is a single branch
- --rev-tags
- Tag each revision, implied by -i
- --no-rev-tags
- Disables tagging effect of -i
- --rename-rev PAT
- Rev tag names, default "svn-rev-%"
- --ignore-tree DIR
- Ignores subtree rooted at DIR
Common Options:
- -i|--incremental
- Allow importing into an existing repository
- -f|--force
- Overwrite repository if already exists
- -q|--quiet
- Omit progress output
- --no-rebuild
- Skip the "rebuilding metadata" step
- --no-vacuum
- Skip the final VACUUM of the database file
- --rename-trunk NAME
- Use NAME as name of imported trunk branch
- --rename-branch PAT
- Rename all branch names using PAT pattern
- --rename-tag PAT
- Rename all tag names using PAT pattern
- -A|--admin-user NAME Use NAME for the admin user
The --incremental option allows an existing repository to be extended with new content. The --rename-* options may be useful to avoid name conflicts when using the --incremental option. The --admin-user option is ignored if --incremental is specified.
The argument to --rename-* contains one "%" character to be replaced with the original name. For example, "--rename-tag svn-%-tag" renames the tag called "release" to "svn-release-tag".
--ignore-tree is useful for importing Subversion repositories which move branches to subdirectories of "branches/deleted" instead of deleting them. It can be supplied multiple times if necessary.
The --attribute option takes a quoted string argument comprised of a Git committer email and the username to be attributed to corresponding check-ins in the Fossil repository. This option can be repeated. For example, --attribute "drh@sqlite.org drh" --attribute "xyz@abc.net X". Attributions are persisted to the repository so that subsequent 'fossil git export' operations attribute Fossil commits to corresponding 'Git Committer <git@committer.com>' users, and incremental imports with 'fossil import --git --incremental' use previous --attribute records.
See also: export
- info (1st tier command)
-
Usage: fossil info ?VERSION | REPOSITORY_FILENAME? ?OPTIONS?
With no arguments, provide information about the current tree. If an argument is specified, provide information about the object in the repository of the current tree that the argument refers to. Or if the argument is the name of a repository, show information about that repository.
If the argument is a repository name, then the --verbose option shows all known check-out locations for that repository and all URLs used to access the repository. The --verbose is (currently) a no-op if the argument is the name of an object within the repository.
Use the "finfo" command to get information about a specific file in a check-out.
Options:
- -R|--repository REPO
- Extract info from repository REPO
- -v|--verbose
- Show extra information about repositories
- init (1st tier command)
- new (alias)
-
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. In case of SQL errors, rebuild the template repository and try again.
Options:
- --template
- FILE Copy settings from repository file
- -A|--admin-user 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"
- --project-name
- STRING The name of the project "project name in quotes"
- --project-desc
- STRING The description of the project "project description in quotes"
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
- interwiki (2nd tier command)
-
Usage: fossil interwiki COMMAND ...
Manage the "intermap" that defines the mapping from interwiki tags to complete URLs for interwiki links.
- fossil interwiki delete TAG ...
- Delete one or more interwiki maps.
- fossil interwiki edit TAG --base URL --hash PATH --wiki PATH
- Create an interwiki referenced call TAG. The base URL is the --base option, which is required. The --hash and --wiki paths are optional. The TAG must be lower-case alphanumeric and must be unique. A new entry is created if it does not already exit.
- fossil interwiki list
- Show all interwiki mappings.
- keep-glob (versionable block-text setting)
- The VALUE of this setting is a list of GLOB patterns matching files that the "clean" command must not delete. Example: build/precious.exe The parsing rules are complex; see https://fossil-scm.org/home/doc/trunk/www/globs.md#syntax
- large-file-size (setting)
- Fossil considers any file whose size is greater than this value to be a "large file". Fossil might issue warnings if you try to "add" or "commit" a "large file". Set this value to 0 or less to disable all such warnings.
- leaves (2nd tier command)
-
Usage: fossil leaves ?OPTIONS?
Find leaves of all branches. By default show only open leaves. The -a|--all flag causes all leaves (closed and open) to be shown. The -c|--closed flag shows only closed leaves.
The --recompute flag causes the content of the "leaf" table in the repository database to be recomputed.
Options:
- -a|--all
- Show ALL leaves
- --bybranch
- Order output by branch name
- -c|--closed
- Show only closed leaves
- -m|--multiple
- Show only cases with multiple leaves on a single branch
- --recompute
- Recompute the "leaf" table in the repository DB
- -W|--width N
- Width of lines (default is to auto-detect). Must be more than 39 or else 0 no limit, resulting in a single line per entry.
See also: descendants, finfo, info, branch
- localauth (boolean setting)
-
If enabled, require that HTTP connections from the loopback
address (127.0.0.1) be authenticated by password. If false,
some HTTP requests might be granted full "Setup" user
privileges without having to present login credentials.
This mechanism allows the "fossil ui" command to provide
full access to the repository without requiring the user to
log in first.
In order for full "Setup" privilege to be granted without a login, the following conditions must be met:
- (1)
- This setting ("localauth") must be off
- (2)
- The HTTP request arrive over the loopback TCP/IP address (127.0.01) or else via SSH.
- (3)
- The request must be HTTP, not HTTPS. (This restriction is designed to help prevent accidentally providing "Setup" privileges to requests arriving over a reverse proxy.)
- (4)
- The command that launched the fossil server must be one of the following: (a) "fossil ui" (b) "fossil server" with the --localauth option (c) "fossil http" with the --localauth option (d) CGI with the "localauth" setting in the cgi script.
For maximum security, set "localauth" to 1. However, because of the other restrictions (2) through (4), it should be safe to leave "localauth" set to 0 in most installations, and especially on cloned repositories on workstations. Leaving "localauth" at 0 makes the "fossil ui" command more convenient to use.
- lock-timeout (setting)
-
This is the number of seconds that a check-in lock will be held on
the server before the lock expires. The default is a 60-second delay.
Set this value to zero to disable the check-in lock mechanism.
This value should be set on the server to which users auto-sync their work. This setting has no effect on client repositories. The check-in lock mechanism is only effective if all users are auto-syncing to the same server.
Check-in locks are an advisory mechanism designed to help prevent accidental forks due to a check-in race in installations where many users are committing to the same branch and auto-sync is enabled. As forks are harmless, there is no danger in disabling this mechanism. However, keeping check-in locks turned on can help prevent unnecessary confusion.
- login-group (2nd tier command)
-
Usage: fossil login-group ?SUBCOMMAND? ?OPTIONS?
Run various subcommands to manage login-group related settings of the open repository or of the repository identified by the -R or --repository option.
- fossil login-group ?-R REPO?
- Show the login-group to which REPO, or if invoked from within a check-out the repository on which the current check-out is based, belongs.
- fossil login-group join ?-R REPO? ?--name NAME? REPO2
- This command will either: (1) add the repository on which the current check-out is based, or the repository REPO specified with -R, to the login group where REPO2 is a member, in which case the optional --name argument is not required; or (2) create a new login group between the repository on which the current check-out is based, or the repository REPO specified with -R, and REPO2, in which case the new group NAME is determined by the mandatory --name option. In both cases, the specified repositories will first leave any group in which they are currently a member before joining the new login group.
- fossil login-group leave ?-R REPO?
- Take the repository REPO, or if invoked from within a check-out the repository on which the current check-out is based, out of whatever login group it is a member.
About Login Groups:
A login-group is a set of repositories that share user credentials. If a user is logged into one member of the group, then that user can access any other group member as long as they have an entry in the USER table of that member. If a user changes their password using web interface, their password is also automatically changed in every other member of the login group.
- ls (1st tier command)
-
Usage: fossil ls ?OPTIONS? ?PATHS ...?
List all files in the current check-out. If PATHS is included, only the named files (or their children if directories) are shown.
The ls command is essentially two related commands in one, depending on whether or not the -r option is given. -r selects a specific check-in version to list, in which case -R can be used to select the repository. The fine behavior of the --age, -v, and -t options is altered by the -r option as well, as explained below.
The --age option displays file commit times. Like -r, --age has the side effect of making -t sort by commit time, not modification time.
The -v option provides extra information about each file. Without -r, -v displays the change status, in the manner of the changes command. With -r, -v shows the commit time and size of the checked-in files.
The -t option changes the sort order. Without -t, files are sorted by path and name (case insensitive sort if -r). If neither --age nor -r are used, -t sorts by modification time, otherwise by commit time.
Options:
- --age
- Show when each file was committed
- --hash
- With -v, verify file status using hashing rather than relying on file sizes and mtimes
- -r VERSION
- The specific check-in to list
- -R|--repository REPO
- Extract info from repository REPO
- -t
- Sort output in time order
- --tree
- Tree format
- -v|--verbose
- Provide extra information about each file
- main-branch (setting)
- The value is the primary branch for the project.
- mainmenu (block-text setting)
-
The mainmenu setting specifies the entries on the main menu
for many skins. The mainmenu should be a TCL list. Each set
of four consecutive values defines a single main menu item:
- The first term is text that appears on the menu.
-
The second term is a hyperlink to take when a user clicks on the entry. Hyperlinks that start with "/" are relative to the repository root.
-
The third term is an argument to the TH1 "capexpr" command. If capexpr evaluates to true, then the entry is shown. If not, the entry is omitted. "*" is always true. "{}" is never true.
-
The fourth term is a list of extra class names to apply to the new menu entry. Some skins use classes "desktoponly" and "wideonly" to only show the entries when the web browser screen is wide or very wide, respectively.
Some custom skins might not use this property. Whether the property is used or not a choice made by the skin designer. Some skins may add extra choices (such as the hamburger button) to the menu.
- manifest (versionable setting)
-
If enabled, automatically create files "manifest" and "manifest.uuid"
in every check-out.
Optionally use combinations of characters 'r' for "manifest", 'u' for "manifest.uuid" and 't' for "manifest.tags". The SQLite and Fossil repositories both require manifests.
- max-cache-entry (setting)
- This is the maximum number of entries to allow in the web-cache for tarballs, ZIP-archives, and SQL-archives.
- max-loadavg (setting)
- Some CPU-intensive web pages (ex: /zip, /tarball, /blame) are disallowed if the system load average goes above this value. "0.0" means no limit. This only works on unix. Only local settings of this value make a difference since when running as a web-server, Fossil does not open the global configuration database.
- max-upload (setting)
- A limit on the size of uplink HTTP requests.
- md5sum (2nd tier command)
-
Usage: fossil md5sum FILES....
Compute an MD5 checksum of all files named on the command-line. If a file is named "-" then content is read from standard input.
- merge-base (1st tier command)
-
Usage: fossil merge-base ?options? PRIMARY SECONDARY ...
Find a common ancestor given two or more check-in versions to hypothetically merge.
Options:
- --ignore-merges
- Ignore merges for discovering name pivots
- merge-info (1st tier command)
-
Usage: fossil merge-info [OPTIONS]
Display information about the most recent merge operation.
Options:
- -a|--all
- Show all file changes that happened because of the merge. Normally only MERGE, CONFLICT, and ERROR lines are shown
- -c|--context N
- Show N lines of context around each change, with negative N meaning show all content. Only meaningful in combination with --tcl or --tk.
- --dark
- Use dark mode for the Tcl/Tk-based GUI
- --tcl FILE
- Generate (to stdout) a TCL list containing information needed to display the changes to FILE caused by the most recent merge. FILE must be a pathname relative to the root of the check-out.
- --tk
- Bring up a Tcl/Tk GUI that shows the changes associated with the most recent merge.
- mimetypes (versionable block-text setting)
- A list of file extension-to-mimetype mappings, one per line. e.g. "foo application/x-foo". File extensions are compared case-insensitively in the order listed in this setting. A leading '.' on file extensions is permitted but not required.
- mtime-changes (boolean setting)
- Use file modification times (mtimes) to detect when files have been modified. If disabled, all managed files are hashed to detect changes, which can be slow for large projects.
- mv (1st tier command)
- rename (2nd tier command)
-
Usage: fossil mv|rename OLDNAME NEWNAME
or: fossil mv|rename OLDNAME... DIR
Move or rename one or more files or directories within the repository tree. You can either rename a file or directory or move it to another subdirectory.
The 'mv' command does NOT normally rename or move the files on disk. This command merely records the fact that file names have changed so that appropriate notations can be made at the next commit. However, the default behavior of this command may be overridden via command line options listed below and/or the 'mv-rm-files' setting.
The 'rename' command never renames or moves files on disk, even when the command line options and/or the 'mv-rm-files' setting would otherwise require it to do so.
WARNING: If the "--hard" option is specified -OR- the "mv-rm-files" setting is non-zero, files WILL BE renamed or moved on disk as well. This does NOT apply to the 'rename' command.
Options:
- --soft
- Skip moving files within the check-out. This supersedes the --hard option.
- --hard
- Move files within the check-out
- --case-sensitive BOOL
- Override the case-sensitive setting
- -n|--dry-run
- If given, display instead of run actions
- mv-rm-files (boolean setting)
- If enabled, the "mv" and "rename" commands will also move the associated files within the check-out -AND- the "rm" and "delete" commands will also remove the associated files from within the check-out.
- open (1st tier command)
-
Usage: fossil open REPOSITORY ?VERSION? ?OPTIONS?
Open a new connection to the repository name REPOSITORY. A check-out for the repository is created with its root at the current working directory, or in DIR if the "--workdir DIR" is used. If VERSION is specified then that version is checked out. Otherwise the most recent check-in on the main branch (usually "trunk") is used.
REPOSITORY can be the filename for a repository that already exists on the local machine or it can be a URI for a remote repository. If REPOSITORY is a URI in one of the formats recognized by the clone command, the remote repo is first cloned, then the clone is opened. The clone will be stored in the current directory, or in DIR if the "--repodir DIR" option is used. The name of the clone will be taken from the last term of the URI. For "http:" and "https:" URIs, you can append an extra term to the end of the URI to get any repository name you like. For example:
fossil open https://fossil-scm.org/home/new-name
The base URI for cloning is "https://fossil-scm.org/home". The extra "new-name" term means that the cloned repository will be called "new-name.fossil".
Options:
- --empty
- Initialize check-out as being empty, but still connected with the local repository. If you commit this check-out, it will become a new "initial" commit in the repository.
- -f|--force
- Continue with the open even if the working directory is not empty, or if auto-sync fails.
- --force-missing
- Force opening a repository with missing content
- -k|--keep
- Only modify the manifest file(s)
- --nested
- Allow opening a repository inside an opened check-out
- --nosync
- Do not auto-sync the repository prior to opening even if the autosync setting is on.
- --repodir DIR
- If REPOSITORY is a URI that will be cloned, store the clone in DIR rather than in "."
- --setmtime
- Set timestamps of all files to match their SCM-side times (the timestamp of the last check-in which modified them).
- --verbose
- If passed a URI then this flag is passed on to the clone operation, otherwise it has no effect
- --workdir DIR
- Use DIR as the working directory instead of ".". The DIR directory is created if it does not exist.
- patch (1st tier command)
-
Usage: fossil patch SUBCOMMAND ?ARGS ..?
This command is used to create, view, and apply Fossil binary patches. A Fossil binary patch is a single (binary) file that captures all of the uncommitted changes of a check-out. Use Fossil binary patches to transfer proposed or incomplete changes between machines for testing or analysis.
- fossil patch create [DIRECTORY] PATCHFILE
- Create a new binary patch in PATCHFILE that captures all uncommitted
changes in the check-out at DIRECTORY, or the current directory if
DIRECTORY is omitted. If PATCHFILE is "-" then the binary patch
is written to standard output.
Options:
- -f|--force
- Overwrite an existing patch with the same name
- fossil patch apply [DIRECTORY] PATCHFILE
- Apply the changes in PATCHFILE to the check-out at DIRECTORY, or
in the current directory if DIRECTORY is omitted.
Options:
- -f|--force
- Apply the patch even though there are unsaved changes in the current check-out. Unsaved changes are reverted and permanently lost.
- -n|--dry-run
- Do nothing, but print what would have happened
- -v|--verbose
- Extra output explaining what happens
- fossil patch diff [DIRECTORY] PATCHFILE
- fossil patch gdiff [DIRECTORY] PATCHFILE
- Show a human-readable diff for the patch in PATCHFILE and associated
with the repository checked out in DIRECTORY. The current
directory is used if DIRECTORY is omitted. All the usual
diff flags described at "fossil help diff" apply. With gdiff,
gdiff-command is used instead of internal diff logic. In addition:
- -f|--force
- Continue trying to perform the diff even if baseline information is missing from the current repository
- fossil patch push REMOTE-CHECKOUT
- Create a patch for the current check-out, transfer that patch to
a remote machine (using ssh) and apply the patch there. The
REMOTE-CHECKOUT is in one of the following formats:
- DIRECTORY
- HOST:DIRECTORY
- USER@HOST:DIRECTORY
The name of the fossil executable on the remote host is specified by the --fossilcmd option, or if there is no --fossilcmd, it first tries "$HOME/bin/fossil" and if not found there it searches for any executable named "fossil" on the default $PATH set by SSH on the remote.
Command-line options:
- -f|--force
- Apply the patch even though there are unsaved changes in the current check-out. Unsaved changes will be reverted and then the patch is applied.
- --fossilcmd EXE
- Name of the "fossil" executable on the remote
- -n|--dry-run
- Do nothing, but print what would have happened
- -v|--verbose
- Extra output explaining what happens
- fossil patch pull REMOTE-CHECKOUT
- Like "fossil patch push" except that the transfer is from remote to local. All the same command-line options apply.
- fossil patch view PATCHFILE
- View a summary of the changes in the binary patch in PATCHFILE.
Use "fossil patch diff" for detailed patch content.
- -v|--verbose
- Show extra detail about the patch
- pgp-command (setting)
- Command used to clear-sign manifests at check-in. Default value is "gpg --clearsign -o"
- pikchr (2nd tier command)
-
Usage: fossil pikchr [options] ?INFILE? ?OUTFILE?
Accepts a pikchr script as input and outputs the rendered script as an SVG graphic. The INFILE and OUTFILE options default to stdin resp. stdout, and the names "-" can be used as aliases for those streams.
Options:
- -div
- On success, add a DIV wrapper around the resulting SVG output which limits its max-width to its computed maximum ideal size
- -div-indent
- Like -div but indent the div
- -div-center
- Like -div but center the div
- -div-left
- Like -div but float the div left
- -div-right
- Like -div but float the div right
- -div-toggle
- Set the 'toggle' CSS class on the div (used by the JavaScript-side post-processor)
- -div-source
- Set the 'source' CSS class on the div, which tells CSS to hide the SVG and reveal the source by default.
- -src
- Store the input pikchr's source code in the output as a separate element adjacent to the SVG one. Implied by -div-source.
- -th
- Process the input using TH1 before passing it to pikchr
- -th-novar
- Disable $var and $<var> TH1 processing. Use this if the pikchr script uses '$' for its own purposes and that causes issues. This only affects parsing of '$' outside of TH1 script blocks. Code in such blocks is unaffected.
- -th-nosvg
- When using -th, output the post-TH1'd script instead of the pikchr-rendered output
- -th-trace
- Trace TH1 execution (for debugging purposes)
- -dark
- Change pikchr colors to assume a dark-mode theme.
The -div-indent/center/left/right flags may not be combined.
TH1-related Notes and Caveats:
If the -th flag is used, this command must open a fossil database for certain functionality to work (via a check-out or the -R REPO flag). If opening a db fails, execution will continue but any TH1 commands which require a db will trigger a fatal error.
In Fossil skins, TH1 variables in the form $varName are expanded as-is and those in the form $<varName> are htmlized in the resulting output. This processor disables the htmlizing step, so $x and $<x> are equivalent unless the TH1-processed pikchr script invokes the TH1 command [enable_htmlify 1] to enable it. Normally that option will interfere with pikchr output, however, e.g. by HTML-encoding double-quotes.
Many of the fossil-installed TH1 functions simply do not make any sense for pikchr scripts.
- preferred-diff-type (setting)
-
The preferred-diff-type setting determines the preferred diff format
for web pages if the format is not otherwise specified, for example
by a query parameter or cookie. Allowed values:
- 1
- Unified diff
- 2
- Side-by-side diff
If this setting is omitted or has a value of 0 or less, then it is ignored.
- proxy (setting)
- URL of the HTTP proxy. If undefined or "system", the "http_proxy" environment variable is consulted. If "off", a direct HTTP connection is used.
- publish (2nd tier command)
-
Usage: fossil publish ?--only? TAGS...
Cause artifacts identified by TAGS... to be published (made non-private). This can be used (for example) to convert a private branch into a public branch, or to publish a bundle that was imported privately.
If any of TAGS names a branch, then all check-ins on the most recent instance of that branch are included, not just the most recent check-in.
If any of TAGS name check-ins then all files and tags associated with those check-ins are also published automatically. Except if the --only option is used, then only the specific artifacts identified by TAGS are published.
If a TAG is already public, this command is a harmless no-op.
- pull (1st tier command)
-
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, tech-notes, and forum posts. 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:
- --all
- Pull from all remotes, not just the default
- -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
- --no-http-compression
- Do not compress HTTP traffic
- --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
- --transport-command CMD
- Use external command CMD to move messages between client and server
- -v|--verbose
- Additional (debugging) output - use twice to also trace network traffic.
- --verily
- Exchange extra information with the remote to ensure no content is overlooked
- purge (2nd tier command)
-
The purge command removes content from a repository and stores that content
in a "graveyard". The graveyard exists so that content can be recovered
using the "fossil purge undo" command. The "fossil purge obliterate"
command empties the graveyard, making the content unrecoverable.
WARNING: This command can potentially destroy historical data and leave your repository in a goofy state. Know what you are doing! Make a backup of your repository before using this command!
FURTHER WARNING: This command is a work-in-progress and may yet contain bugs.
- fossil purge artifacts HASH... ?OPTIONS?
- Move arbitrary artifacts identified by the HASH list into the graveyard.
- fossil purge cat HASH...
- Write the content of one or more artifacts in the graveyard onto standard output.
- fossil purge checkins TAGS... ?OPTIONS?
- Move the check-ins or branches identified by TAGS and all of their descendants out of the repository and into the graveyard. If TAGS includes a branch name then it means all the check-ins on the most recent occurrence of that branch.
- fossil purge files NAME ... ?OPTIONS?
- Move all instances of files called NAME into the graveyard. NAME should be the name of the file relative to the root of the repository. If NAME is a directory, then all files within that directory are moved.
- fossil purge list|ls ?-l?
- Show the graveyard of prior purges. The -l option gives more detail in the output.
- fossil purge obliterate ID... ?--force?
- Remove one or more purge events from the graveyard. Once a purge event is obliterated, it can no longer be undone. The --force option suppresses the confirmation prompt.
- fossil purge tickets NAME ... ?OPTIONS?
- TBD...
- fossil purge undo ID
- Restore the content previously removed by purge ID.
- fossil purge wiki NAME ... ?OPTIONS?
- TBD...
COMMON OPTIONS:
- --explain
- Make no changes, but show what would happen
- --dry-run
- An alias for --explain
- push (1st tier command)
-
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, tech-notes, and forum posts. 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:
- --all
- Push to all remotes, not just the default
- -B|--httpauth USER:PASS
- Credentials for the simple HTTP auth protocol, if required by the remote website
- --ipv4
- Use only IPv4, not IPv6
- --no-http-compression
- Do not compress HTTP traffic
- --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
- --transport-command CMD
- Use external command CMD to communicate with the server
- -v|--verbose
- Additional (debugging) output - use twice for network debugging
- --verily
- Exchange extra information with the remote to ensure no content is overlooked
- rebuild (1st tier command)
-
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
- --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, power of 2)
- --quiet
- Only show output if there are errors
- --stats
- Show artifact statistics after rebuilding
- --vacuum
- Run VACUUM on the database after rebuilding
- --wal
- Set Write-Ahead-Log journalling mode on the database
- reconstruct (2nd tier command)
-
Usage: fossil reconstruct ?OPTIONS? FILENAME DIRECTORY
This command studies the artifacts (files) in DIRECTORY and reconstructs the Fossil record from them. It places the new Fossil repository in FILENAME. Subdirectories are read, files with leading '.' in the filename are ignored.
Options:
- -K|--keep-rid1
- Read the filename of the artifact with RID=1 from the file .rid in DIRECTORY.
- -P|--keep-private
- Mark the artifacts listed in the file .private in DIRECTORY as private in the new Fossil repository.
- redirect-to-https (setting)
-
Specifies whether or not to redirect unencrypted "http://" requests to
encrypted "https://" URIs. A value of 0 (the default) means do not
redirect, 1 means to redirect only the /login page, and 2
means to always redirect.
For security, a value of 2 is recommended. The default value is 0 because not all sites are TLS-capable. But you should definitely enable TLS and change this setting to 2 for all public-facing repositories.
- redo (2nd tier command)
- undo (1st tier command)
-
Usage: fossil undo ?OPTIONS? ?FILENAME...?
or: fossil redo ?OPTIONS? ?FILENAME...?
The undo command reverts the changes caused by the previous command if the previous command is one of the following:
- fossil update
- fossil merge
- fossil revert
- fossil stash pop
- fossil stash apply
- fossil stash drop
- fossil stash goto
- fossil clean (*see note below*)
Note: The "fossil clean" command only saves state for files less than 10MiB in size and so if fossil clean deleted files larger than that, then "fossil undo" will not recover the larger files.
If FILENAME is specified then restore the content of the named file(s) but otherwise leave the update or merge or revert in effect. The redo command undoes the effect of the most recent undo.
If the -n|--dry-run option is present, no changes are made and instead the undo or redo command explains what actions the undo or redo would have done had the -n|--dry-run been omitted.
If the most recent command is not one of those listed as undoable, then the undo command might try to restore the state to be what it was prior to the last undoable command, or it might be a no-op. If in doubt about what the undo command will do, first run it with the -n option.
A single level of undo/redo is supported. The undo/redo stack is cleared by the commit and check-out commands. Other commands may or may not clear the undo stack.
Future versions of Fossil might add new commands to the set of commands that are undoable.
Options:
- -n|--dry-run
- Do not make changes, but show what would be done
- relative-paths (boolean setting)
- When showing changes and extras, report paths relative to the current working directory.
- remote (1st tier command)
- remote-url (2nd tier command)
-
Usage: fossil remote ?SUBCOMMAND ...?
View or modify the URLs of remote repositories used for syncing. The "default" remote is specially named by Fossil and corresponds to the URL used in the most recent "sync", "push", "pull", "clone", or similar command. As such, the default remote can be updated by Fossil with each sync command. Other named remotes are persistent.
- fossil remote
- With no arguments, this command shows the current default remote URL. If there is no default, it shows "off".
- fossil remote add NAME URL
- Add a new named URL. Afterwards, NAME can be used as a short symbolic name for URL in contexts where a URL is required. The URL argument can be "default" or a prior symbolic name to make a copy of an existing URL under the new NAME. The "default" remote cannot be defined with this subcommand; instead, use 'fossil remote REF' as documented below.
- fossil remote config-data
- DEBUG USE ONLY - Show the name and value of every CONFIG table entry in the repository that is associated with the remote URL store. Passwords are obscured in the output.
- fossil remote delete NAME
- Delete a named URL previously created by the "add" subcommand.
- fossil remote hyperlink ?FILENAME? ?LINENUM? ?LINENUM?
- Print a URL that will access the current check-out on the remote repository. Or if the FILENAME argument is included, print the URL to access that particular file within the current check-out. If one or two linenumber arguments are provided after the filename, then the URL is for the line or range of lines specified.
- fossil remote list|ls
- Show all remote repository URLs.
- fossil remote off
- Forget the default URL. This disables autosync.
This is a convenient way to enter "airplane mode". To enter airplane mode, first save the current default URL, then turn the default off. Perhaps like this:
fossil remote add main default fossil remote off
To exit airplane mode and turn autosync back on again:
fossil remote main
- fossil remote scrub
- Forget any saved passwords for remote repositories, but continue to remember the URLs themselves. You will be prompted for the password the next time it is needed.
- fossil remote ui ?FILENAME? ?LINENUM? ?LINENUM?
- Bring up a web browser pointing at the remote repository, and specifically to the page that describes the current check-out on that remote repository. Or if FILENAME and/or LINENUM arguments are provided, to the specific file and range of lines. This command is similar to "fossil remote hyperlink" except that instead of printing the URL, it passes the URL off to the web browser.
- fossil remote REF
- Make REF the new default URL, replacing the prior default. REF may be a URL or a NAME from a prior "add".
- repack (1st tier command)
-
Usage: fossil repack ?REPOSITORY?
Perform extra delta-compression to try to minimize the size of the repository. This command is simply a short-hand for:
fossil rebuild --compress-only
The name for this command is stolen from the "git repack" command that does approximately the same thing in Git.
- reparent (2nd tier command)
-
Usage: fossil reparent [OPTIONS] CHECK-IN PARENT ...
Create a "parent" tag that causes CHECK-IN to be interpreted as a child of PARENT. If multiple PARENTs are listed, then the first is the primary parent and others are merge ancestors.
This is an experts-only command. It is used to patch up a repository that has been damaged by a shun or that has been pieced together from two or more separate repositories. You should never need to reparent during normal operations.
Reparenting is accomplished by adding a parent tag. So to undo the reparenting operation, simply delete the tag.
- --test
- Make database entries but do not add the tag artifact. So the reparent operation will be undone by the next "fossil rebuild" command.
- -n|--dry-run
- Print the tag that would have been created but do not actually change the database in any way.
- --date-override DATETIME
- Set the change time on the control artifact
- --user-override USER
- Set the user name on the control artifact
- repo-cksum (boolean setting)
- Compute checksums over all files in each check-out as a double-check of correctness. Disable this on large repositories for a performance improvement.
- repolist-skin (setting)
-
If non-zero then use this repository as the skin for a repository list
such as created by the one of:
- 1)
- fossil server DIRECTORY --repolist
- 2)
- fossil ui DIRECTORY --repolist
- 3)
- fossil http DIRECTORY --repolist
- 4)
- (The "repolist" option in a CGI script)
- 5)
- fossil all ui
- 6)
- fossil all server
All repositories are searched (in lexicographical order) and the first repository with a non-zero "repolist-skin" value is used as the skin for the repository list page. If none of the repositories on the list have a non-zero "repolist-skin" setting then the repository list is displayed using unadorned HTML ("skinless").
If repolist-skin has a value of 2, then the repository is omitted from the list in use cases 1 through 4, but not for 5 and 6.
- revert (1st tier command)
-
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:
- --noundo
- Do not record changes in the undo/redo log.
- -r|--revision VERSION
- Revert given FILE(s) back to given VERSION
- robot-restrict (block-text setting)
-
The VALUE of this setting is a list of GLOB patterns that match
pages for which complex HTTP requests from robots should be disallowed.
The recommended value for this setting is:
timeline,vdiff,fdiff,annotate,blame
- robots-txt (block-text setting)
- This setting is the override value for the /robots.txt file that Fossil returns when run as a stand-alone server for a domain. As Fossil is seldom run as a stand-alone server (and is more commonly deployed as a CGI or SCGI or behind a reverse proxy) this setting rarely needed. A reasonable default robots.txt is sent if this setting is empty.
- rss (2nd tier command)
-
Usage: fossil rss ?OPTIONS?
The CLI variant of the /timeline.rss page, this produces an RSS feed of the timeline to stdout.
Options:
- -type|y FLAG
- May be: all (default), ci (show check-ins only), t (show tickets only), w (show wiki only)
- -limit|n LIMIT
- The maximum number of items to show
- -tkt HASH
- Filter for only those events for the specified ticket
- -tag TAG
- Filter for a tag
- -wiki NAME
- Filter on a specific wiki page
Only one of -tkt, -tag, or -wiki may be used.
- -name FILENAME
- Filter for a specific file. This may be combined with one of the other filters (useful for looking at a specific branch).
- -url STRING
- Set the RSS feed's root URL to the given string. The default is "URL-PLACEHOLDER" (without quotes).
- safe-html (setting)
-
This setting controls whether or not unsafe HTML elements
(such as SCRIPT or STYLE tags) are allowed in Markdown-formatted
documents. Unsafe HTML is disabled by default. If this setting
exists and is a string, then letters in that string can enable
unsafe HTML in various contexts:
- - b
- Unsafe HTML allowed in embedded documentation
- - f
- Unsafe HTML allowed in forum posts
- - t
- Unsafe HTML allowed in tickets
- - w
- Unsafe HTML allowed on wiki pages
- scrub (2nd tier command)
-
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 IRREVERSIBLE. 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 (2nd tier command)
-
Usage: fossil search [-a|-all] [-n|-limit #] [-W|-width #] 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
- --debug
- Show additional debug content on --fts search
- --fts
- Use the full-text search mechanism (testing only)
- -n|--limit N
- Limit output to N matches
- --scope SCOPE
- Scope of search. Valid for --fts only. One or more of: all, c, d, e, f, t, w. Defaults to all.
- -W|--width WIDTH
- Set display width to WIDTH columns, 0 for unlimited. Defaults the terminal's width.
- self-pw-reset (boolean setting)
- Allow users to request that an email containing a hyperlink to the /resetpw page be sent to their email address of record, thus allowing forgetful users to reset their forgotten passwords without administrator involvement.
- self-register (boolean setting)
- Allow users to register themselves through the HTTP UI. This is useful if you want to see other names than "Anonymous" in e.g. ticketing system. On the other hand users can not be deleted.
- server (2nd tier command)
- ui (1st tier command)
-
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 REPOSITORY argument is the name of the Fossil repository to be served. The REPOSITORY argument may be omitted if the working directory is within an open check-out, in which case the repository associated with that check-out is used.
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.
If REPOSITORY is a directory name which is the root of a check-out, then use the repository associated with that check-out. This only works for the "fossil ui" command, not the "fossil server" command.
If REPOSITORY begins with a "HOST:" or "USER@HOST:" prefix, then the command is run on the remote host specified and the results are tunneled back to the local machine via SSH. This feature only works for the "fossil ui" command, not the "fossil server" command. The name of the fossil executable on the remote host is specified by the --fossilcmd option, or if there is no --fossilcmd, it first tries "fossil" and if it is not found in the default $PATH set by SSH on the remote, it then adds "$HOME/bin:/usr/local/bin:/opt/homebrew/bin" to the PATH and tries again to run "fossil".
REPOSITORY may also 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 global configuration database is consulted for a list of all known repositories. The --repolist option is implied by this special case. The "fossil ui /" command is equivalent to "fossil all ui". To see all repositories owned by "user" on machine "remote" via ssh, run "fossil ui user@remote:/".
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:
- --acme
- Deliver files from the ".well-known" subdirectory
- --baseurl URL
- Use URL as the base (useful for reverse proxies)
- --cert FILE
- Use TLS (HTTPS) encryption with the certificate (the fullchain.pem) taken from FILE.
- --chroot DIR
- Use directory for chroot instead of repository path
- --ckout-alias NAME
- Treat URIs of the form /doc/NAME/... as if they were /doc/ckout/...
- --create
- Create a new REPOSITORY if it does not already exist
- --errorlog FILE
- Append HTTP error messages to FILE
- --extroot DIR
- Document root for the /ext extension mechanism
- --files GLOBLIST
- Comma-separated list of glob patterns for static files
- --fossilcmd PATH
- The pathname of the "fossil" executable on the remote system when REPOSITORY is remote.
- --from PATH
- Use PATH as the diff baseline for the /ckout page
- --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:
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.- 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.
- --mainmenu FILE
- Override the mainmenu config setting with the contents of the given file
- --max-latency N
- Do not let any single HTTP request run for more than N seconds (only works on unix)
- -B|--nobrowser
- Do not automatically launch a web-browser for the "fossil ui" command
- --nocompress
- Do not compress HTTP replies
- --nojail
- Drop root privileges but do not enter the chroot jail
- --nossl
- Do not force redirects to SSL even if the repository setting "redirect-to-https" requests it. This is set by default for the "ui" command.
- --notfound URL
- Redirect to URL if a page is not found.
- -p|--page PAGE
- Start "ui" on PAGE. ex: --page "timeline?y=ci"
- --pkey FILE
- Read the private key used for TLS from FILE
- -P|--port [IP:]PORT
- Listen on the given IP (optional) and port
- --repolist
- If REPOSITORY is dir, URL "/" lists repos
- --scgi
- Accept SCGI rather than HTTP
- --skin LABEL
- Use override skin LABEL, or the site's default skin if LABEL is an empty string.
- --socket-mode MODE
- File permissions to set for the unix socket created by the --socket-name option.
- --socket-name NAME
- Use a unix-domain socket called NAME instead of a TCP/IP socket.
- --socket-owner USR
- Try to set the owner of the unix socket to USR. USR can be of the form USER:GROUP to set both user and group.
- --th-trace
- Trace TH1 execution (for debugging purposes)
- --usepidkey
- Use saved encryption key from parent process. This is only necessary when using SEE on Windows or Linux.
- settings (1st tier command)
- unset (2nd tier command)
-
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
- --value
- Only show the value of a given property (implies --exact)
See also: configuration
- sha1sum (2nd tier command)
-
Usage: fossil sha1sum FILE...
Compute an SHA1 checksum of all files named on the command-line. If a file is named "-" then take its content from standard input.
Options:
- -h|--dereference
- If FILE is a symbolic link, compute the hash on the object that the link points to. Normally, the hash is over the name of the object that the link points to.
- sha3sum (2nd tier command)
-
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.
- shell (2nd tier command)
-
Usage: fossil shell
Prompt for lines of input from stdin. Parse each line and evaluate it as a separate fossil command, in a child process. The initial "fossil" is omitted from each line.
This command only works on unix-like platforms that support fork(). It is non-functional on Windows.
- sitemap-extra (block-text setting)
-
The sitemap-extra setting defines extra links to appear on the
/sitemap web page as sub-items of the "Home Page" entry before the
"Documentation Search" entry (if any). For skins that use the /sitemap
page to construct a hamburger menu dropdown, new entries added here
will appear on the hamburger menu.
This setting should be a TCL list divided into triples. Each triple defines a new entry:
- The first term is the display name of the /sitemap entry
-
The second term is a hyperlink to take when a user clicks on the entry. Hyperlinks that start with "/" are relative to the repository root.
-
The third term is an argument to the TH1 "capexpr" command. If capexpr evaluates to true, then the entry is shown. If not, the entry is omitted. "*" is always true.
The default value is blank, meaning no added entries.
- sql (1st tier command)
- sqlite3 (2nd tier command)
-
Usage: fossil sql ?OPTIONS?
Run the sqlite3 command-line shell on the Fossil repository identified by the -R option, or on the current repository. See https://www.sqlite.org/cli.html for additional information about the sqlite3 command-line shell.
WARNING: Careless use of this command can corrupt a Fossil repository in ways that are unrecoverable. Be sure you know what you are doing before running any SQL commands that modify the repository database. Use the --readonly option to prevent accidental damage to the repository.
Options:
- --no-repository
- Skip opening the repository database
- --readonly
- Open the repository read-only. No changes are allowed. This is a recommended safety precaution to prevent repository damage.
- -R REPOSITORY
- Use REPOSITORY as the repository database
- --test
- Enable some testing and analysis features that are normally disabled.
All of the standard sqlite3 command-line shell options should also work.
The following SQL extensions are provided with this Fossil-enhanced version of the sqlite3 command-line shell:
- builtin
- A virtual table that contains one row for each datafile that is built into the Fossil binary.
- checkin_mtime(X,Y)
- Return the mtime for the file Y (a BLOB.RID) found in check-in X (another BLOB.RID value).
- compress(X)
- Compress text X with the same algorithm used to compress artifacts in the BLOB table.
- content(X)
- Return the content of artifact X. X can be an artifact hash or hash prefix or a tag. Artifacts are stored compressed and deltaed. This function does all necessary decompression and undeltaing.
- decompress(X)
- Decompress text X. Undoes the work of compress(X).
- delta_apply(X,D)
- Apply delta D to source blob X and return the result.
- delta_create(X,Y)
- Create and return a delta that will convert X into Y.
- delta_output_size(D)
- Return the number of bytes of output to expect when applying delta D
- delta_parse(D)
- A table-valued function that deconstructs delta D and returns rows for each element of that delta.
- files_of_checkin(X)
- A table-valued function that returns info on
all files contained in check-in X. Example:
SELECT * FROM files_of_checkin('trunk');
- helptext
- A virtual table with one row for each command, webpage, and setting together with the built-in help text.
- now()
- Return the number of seconds since 1970.
- obscure(T)
- Obfuscate the text password T so that its original value is not readily visible. Fossil uses this same algorithm when storing passwords of remote URLs.
- regexp
- The REGEXP operator works, unlike in standard SQLite.
- symbolic_name_to_rid(X)
- Return the BLOB.RID corresponding to symbolic name X.
- sqlar (2nd tier command)
-
Usage: fossil sqlar VERSION OUTPUTFILE [OPTIONS]
Generate an SQLAR archive for a check-in. If the --name option is used, its argument becomes the name of the top-level directory in the resulting SQLAR 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.
If OUTPUTFILE is an empty string or "/dev/null" then no SQLAR archive is actually generated. This feature can be used in combination with the --list option to get a list of the filenames that would be in the SQLAR archive had it actually been generated.
Options:
- -X|--exclude GLOBLIST
- Comma-separated list of GLOBs of files to exclude
- --include GLOBLIST
- Comma-separated list of GLOBs of files to include
- -l|--list
- Show archive content on stdout
- --name DIRECTORYNAME
- The name of the top-level directory in the archive
- -R REPOSITORY
- Specify a Fossil repository
- ssh-command (setting)
- The command used to talk to a remote machine with the "ssh://" protocol.
- ssl-ca-location (setting)
-
The full pathname to a file containing PEM encoded
CA root certificates, or a directory of certificates
with filenames formed from the certificate hashes as
required by OpenSSL.
If set, this will override the OS default list of OpenSSL CAs. If unset, the default list will be used. Some platforms may add additional certificates. Checking your platform behaviour is required if the exact contents of the CA root is critical for your application.
This setting is overridden by environment variables SSL_CERT_FILE and SSL_CERT_DIR.
- ssl-config (1st tier command)
- tls-config (2nd tier command)
-
Usage: fossil ssl-config [SUBCOMMAND] [OPTIONS...] [ARGS...]
This command is used to view or modify the TLS (Transport Layer Security) configuration for Fossil. TLS (formerly SSL) is the encryption technology used for secure HTTPS transport.
Sub-commands:
- remove-exception DOMAINS
- Remove TLS cert exceptions for the domains listed. Or remove them all if the --all option is specified.
- scrub ?--force?
- Remove all SSL configuration data from the repository. Use --force to omit the confirmation.
- show ?-v?
- Show the TLS configuration. Add -v to see additional explanation
- ssl-identity (setting)
-
The full pathname to a file containing a certificate
and private key in PEM format. Create by concatenating
the certificate and private key files.
This identity will be presented to SSL servers to authenticate this client, in addition to the normal password authentication.
- stash (1st tier command)
-
Usage: fossil stash SUBCOMMAND ARGS...
- fossil stash
- fossil stash save ?-m|--comment COMMENT? ?FILES...?
- fossil stash snapshot ?-m|--comment COMMENT? ?FILES...?
- Save the current changes in the working tree as a new stash. Then revert the changes back to the last check-in. If FILES are listed, then only stash and revert the named files. The "save" verb can be omitted if and only if there are no other arguments. The "snapshot" verb works the same as "save" but omits the revert, keeping the check-out unchanged.
- fossil stash list|ls ?-v|--verbose? ?-W|--width NUM?
- List all changes sets currently stashed. Show information about individual files in each changeset if -v or --verbose is used.
- fossil stash show|cat ?STASHID? ?DIFF-OPTIONS?
- fossil stash gshow|gcat ?STASHID? ?DIFF-OPTIONS?
- Show the contents of a stash as a diff against its baseline. With gshow and gcat, gdiff-command is used instead of internal diff logic.
- fossil stash pop
- fossil stash apply ?STASHID?
- Apply STASHID or the most recently created stash to the current working check-out. The "pop" command deletes that changeset from the stash after applying it but the "apply" command retains the changeset.
- fossil stash goto ?STASHID?
- Update to the baseline check-out for STASHID then apply the changes of STASHID. Keep STASHID so that it can be reused This command is undoable.
- fossil stash drop|rm ?STASHID? ?-a|--all?
- Forget everything about STASHID. Forget the whole stash if the -a|--all flag is used. Individual drops are undoable but -a|--all is not.
- fossil stash diff ?STASHID? ?DIFF-OPTIONS?
- fossil stash gdiff ?STASHID? ?DIFF-OPTIONS?
- Show diffs of the current working directory and what that directory would be if STASHID were applied. With gdiff, gdiff-command is used instead of internal diff logic.
- sync (1st tier command)
-
Usage: fossil sync ?REMOTE? ?options?
Synchronize all sharable changes between the local repository and a remote repository, with the remote provided as a URL or a configured remote name (see the remote command). Sharable changes include public check-ins and edits to wiki pages, tickets, forum posts, and technical notes.
If REMOTE 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:
- --all
- Sync with all remotes, not just the default
- -B|--httpauth USER:PASS
- Credentials for the simple HTTP auth protocol, if required by the remote website
- --ipv4
- Use only IPv4, not IPv6
- --no-http-compression
- Do not compress HTTP traffic
- --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
- --transport-command CMD
- Use external command CMD to move message between the client and the server
- -u|--unversioned
- Also sync unversioned content
- -v|--verbose
- Additional (debugging) output - use twice to get network debug info
- --verily
- Exchange extra information with the remote to ensure no content is overlooked
- tag (1st tier command)
-
Usage: fossil tag SUBCOMMAND ...
Run various subcommands to control tags and properties.
- fossil tag add ?OPTIONS? TAGNAME ARTIFACT-ID ?VALUE?
- Add a new tag or property to an artifact referenced by
ARTIFACT-ID. For check-ins, the tag will be usable instead
of a CHECK-IN in commands such as update and merge. If the
--propagate flag is present and ARTIFACT-ID refers to a
wiki page, forum post, technote, or check-in, the tag
propagates to all descendants of that artifact.
Options:
- --date-override DATETIME
- Set date and time added
- -n|--dry-run
- Display the tag text, but do not actually insert it into the database
- --propagate
- Propagating tag
- --raw
- Raw tag name. Ignored for non-CHECK-IN artifacts.
- --user-override USER
- Name USER when adding the tag
The --date-override and --user-override options support importing history from other SCM systems. DATETIME has the form 'YYYY-MMM-DD HH:MM:SS'.
Note that fossil uses some tag prefixes internally and this command will reject tags with these prefixes to avoid causing problems or confusion: "wiki-", "tkt-", "event-".
- fossil tag cancel ?--raw? TAGNAME ARTIFACT-ID
- Remove the tag TAGNAME from the artifact referenced by
ARTIFACT-ID, and also remove the propagation of the tag to
any descendants. Use the the -n|--dry-run option to see
what would have happened. Certain tag name prefixes are
forbidden, as documented for the 'add' subcommand.
Options:
- --date-override DATETIME
- Set date and time deleted
- -n|--dry-run
- Display the control artifact, but do not insert it into the database
- --raw
- Raw tag name. Ignored for non-CHECK-IN artifacts.
- --user-override USER
- Name USER when deleting the tag
- fossil tag find ?OPTIONS? TAGNAME
- List all objects that use TAGNAME.
Options:
- -n|--limit N
- Limit to N results
- --raw
- Interprets tag as a raw name instead of a branch name and matches any type of artifact. Changes the output to include only the hashes of matching objects.
- -t|--type TYPE
- One of: ci (check-in), w (wiki), e (event/technote), f (forum post), t (ticket). Default is all types. Ignored if --raw is used.
- fossil tag list|ls ?OPTIONS? ?ARTIFACT-ID?
- List all tags or, if ARTIFACT-ID is supplied, all tags and
their values for that artifact. The tagtype option accepts
one of: propagated, singleton, cancel. For historical
scripting compatibility, the internal tag types "wiki-",
"tkt-", and "event-" (technote) are elided by default
unless the --raw or --prefix options are used.
Options:
- -v|--inverse
- Inverse the meaning of --tagtype TYPE
- --prefix
- List only tags with the given prefix Fossil-internal prefixes include "sym-" (branch name), "wiki-", "event-" (technote), and "tkt-" (ticket). The prefix is stripped from the resulting list unless --raw is provided. Ignored if ARTIFACT-ID is provided.
- --raw
- List raw names of tags
- --sep SEP
- Separator when concatenating values
- --tagtype TYPE
- List only tags of type TYPE, which must be one of: cancel, singleton, propagated
- --values
- List tag values If --sep is supplied, list all values of a tag on the same line, separated by SEP; otherwise list each value on its own line.
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.
- tarball (2nd tier command)
-
Usage: fossil tarball VERSION OUTPUTFILE [OPTIONS]
Generate a compressed tarball for a specified version. If the --name option is used, its argument becomes the name of the top-level directory in the resulting tarball. 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.
If OUTPUTFILE is an empty string or "/dev/null" then no tarball is actually generated. This feature can be used in combination with the --list option to get a list of the filenames that would be in the tarball had it actually been generated. Note that --list shows only filenames. "tar tzf" shows both filenames and subdirectory names.
Options:
- -X|--exclude GLOBLIST
- Comma-separated list of GLOBs of files to exclude
- --include GLOBLIST
- Comma-separated list of GLOBs of files to include
- -l|--list
- Show archive content on stdout
- --name DIRECTORYNAME
- The name of the top-level directory in the archive
- -R REPOSITORY
- Specify a Fossil repository
- tcl (boolean setting)
- If enabled Tcl integration commands will be added to the TH1 interpreter, allowing arbitrary Tcl expressions and scripts to be evaluated from TH1. Additionally, the Tcl interpreter will be able to evaluate arbitrary TH1 expressions and scripts.
- tcl-setup (block-text setting)
- This is the setup script to be evaluated after creating and initializing the Tcl interpreter. By default, this is empty and no extra setup is performed.
- tclsh (setting)
- Name of the external TCL interpreter used for such things as running the GUI diff viewer launched by the --tk option of the various "diff" commands.
- th1-setup (block-text setting)
- This is the setup script to be evaluated after creating and initializing the TH1 interpreter. By default, this is empty and no extra setup is performed.
- th1-uri-regexp (block-text setting)
- Specify which URI's are allowed in HTTP requests from TH1 scripts. If empty, no HTTP requests are allowed whatsoever.
- ticket (2nd tier command)
-
Usage: fossil ticket SUBCOMMAND ...
Run various subcommands to control tickets
- fossil ticket show (REPORTTITLE|REPORTNR) ?TICKETFILTER? ?OPTIONS?
- Options:
- -l|--limit LIMITCHAR
- -q|--quote
- -R|--repository REPO
Run the ticket report, identified by the report format title used in the GUI. The data is written as flat file on stdout, using TAB as separator. The separator can be changed using the -l or --limit option.
If TICKETFILTER is given on the commandline, the query is limited with a new WHERE-condition.
- example:
- Report lists a column # with the uuid TICKETFILTER may be [#]='uuuuuuuuu'
- example:
- Report only lists rows with status not open TICKETFILTER: status != 'open'
If --quote is used, the tickets are encoded by quoting special chars (space -> \s, tab -> \t, newline -> \n, cr -> \r, formfeed -> \f, vtab -> \v, nul -> \0, \ -> \\). Otherwise, the simplified encoding as on the show report raw page in the GUI is used. This has no effect in JSON mode.
Instead of the report title it's possible to use the report number; the special report number 0 lists all columns defined in the ticket table.
- fossil ticket list fields
- fossil ticket ls fields
- List all fields defined for ticket in the fossil repository.
- fossil ticket list reports
- fossil ticket ls reports
- List all ticket reports defined in the fossil repository.
- fossil ticket set TICKETUUID (FIELD VALUE)+ ?-q|--quote?
- fossil ticket change TICKETUUID (FIELD VALUE)+ ?-q|--quote?
- Change ticket identified by TICKETUUID to set the values of
each field FIELD to VALUE.
Field names as defined in the TICKET table. By default, these names include: type, status, subsystem, priority, severity, foundin, resolution, title, and comment, but other field names can be added or substituted in customized installations.
If you use +FIELD, the VALUE is appended to the field FIELD. You can use more than one field/value pair on the commandline. Using --quote enables the special character decoding as in "ticket show", which allows setting multiline text or text with special characters.
- fossil ticket add FIELD VALUE ?FIELD VALUE .. ? ?-q|--quote?
- Like set, but create a new ticket with the given values.
- fossil ticket history TICKETUUID
- Show the complete change history for the ticket
Note that the values in set|add are not validated against the definitions given in "Ticket Common Script".
- ticket-default-report (setting)
- If this setting has a string value, then when the ticket search page query is blank, the report with this title is shown. If the setting is blank (default), then no report is shown.
- timeline (1st tier command)
-
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:
- -b|--branch BRANCH
- Show only items on the branch named BRANCH
- -c|--current-branch
- Show only items on the current branch
- -F|--format
- Entry format. Values "oneline", "medium", and "full"
get mapped to the full options below. Otherwise a
string which can contain these placeholders:
- %n
- newline
- %%
- a raw %
- %H
- commit hash
- %h
- abbreviated commit hash
- %a
- author name
- %d
- date
- %c
- comment (NL, TAB replaced by space, LF erased)
- %b
- branch
- %t
- tags
- %p
- phase: zero or more of *CURRENT*, *MERGE*, *FORK*, *UNPUBLISHED*, *LEAF*, *BRANCH*
- --oneline
- Show only short hash and comment for each entry
- --medium
- Medium-verbose entry formatting
- --full
- Extra verbose entry formatting
- -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.
- --offset P
- Skip P changes
- -p|--path PATH
- Output items affecting PATH only. PATH can be a file or a sub directory.
- -R REPO_FILE
- Specifies the repository db to use. Default is the current check-out's repository.
- --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 f = forum posts 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 must be zero 0 to indicate no limit, resulting in a single line per entry.
- touch (2nd tier command)
-
Usage: fossil touch ?OPTIONS? ?FILENAME...?
For each file in the current check-out matching one of the provided list of glob patterns and/or file names, the file's mtime is updated to a value specified by one of the flags --checkout, --checkin, or --now.
If neither glob patterns nor filenames are provided, it operates on all files managed by the currently checked-out version.
This command gets its name from the conventional Unix "touch" command.
Options:
- --now
- Stamp each affected file with the current time. This is the default behavior.
- -c|--checkin
- Stamp each affected file with the time of the most recent check-in which modified that file
- -C|--checkout
- Stamp each affected file with the time of the currently checked-out version
- -g GLOBLIST
- Comma-separated list of glob patterns
- -G GLOBFILE
- Similar to -g but reads its globs from a fossil-conventional glob list file
- -v|--verbose
- Outputs extra information about its globs and each file it touches
- -n|--dry-run
- Outputs which files would require touching, but does not touch them
- -q|--quiet
- Suppress warnings, e.g. when skipping unmanaged or out-of-tree files
Only one of --now, --checkin, and --checkout may be used. The default is --now.
Only one of -g or -G may be used. If neither is provided and no additional filenames are provided, the effect is as if a glob of '*' were provided, i.e. all files belonging to the currently checked-out version. Note that all glob patterns provided via these flags are always evaluated as if they are relative to the top of the source tree, not the current working (sub)directory. Filenames provided without these flags, on the other hand, are treated as relative to the current directory.
As a special case, files currently undergoing an uncommitted merge might not get timestamped with --checkin because it may be impossible for fossil to choose between multiple potential timestamps. A non-fatal warning is emitted for such cases.
- tree (1st tier command)
-
Usage: fossil tree ?OPTIONS? ?PATHS ...?
List all files in the current check-out much like the "tree" command does. If PATHS is included, only the named files (or their children if directories) are shown.
Options:
- -r VERSION
- The specific check-in to list
- -R|--repository REPO
- Extract info from repository REPO
See also: ls
- unpublished (2nd tier command)
-
Usage: fossil unpublished ?OPTIONS?
Show a list of unpublished or "private" artifacts. Unpublished artifacts will never push and hence will not be shared with collaborators.
By default, this command only shows unpublished check-ins. To show all unpublished artifacts, use the --all command-line option.
Options:
- --all
- Show all artifacts, not just check-ins
- unversioned (1st tier command)
- uv (alias)
-
Usage: fossil unversioned SUBCOMMAND ARGS...
or: fossil uv SUBCOMMAND ARGS..
Unversioned files (UV-files) are artifacts that are synced and are available for download but which do not preserve history. Only the most recent version of each UV-file is retained. Changes to an UV-file are permanent and cannot be undone, so use appropriate caution with this command.
Subcommands:
- add FILE ...
- Add or update one or more unversioned files in the local repository so that they match FILEs on disk. Changes are not pushed to other repositories until the next sync.
- add FILE --as UVFILE
- Add or update a single file named FILE on disk and UVFILE in the repository unversioned file namespace. This variant of the 'add' command allows the name to be different in the repository versus what appears on disk, but it only allows adding a single file at a time.
- cat FILE ...
- Concatenate the content of FILEs to stdout.
- edit FILE
- Bring up FILE in a text editor for modification.
- export FILE OUTPUT
- Write the content of FILE into OUTPUT on disk
- list | ls
- Show all unversioned files held in the local
repository.
Options:
- --glob PATTERN
- Show only files that match
- --like PATTERN
- Show only files that match
- -l
- Show additional details for files that match. Implied when 'list' is used.
- revert ?URL?
- Restore the state of all unversioned files in the
local repository to match the remote repository
URL.
Options:
- -v|--verbose
- Extra diagnostic output
- -n|--dry-run
- Show what would have happened
- remove|rm|delete FILE ...
- Remove unversioned files from the local repository.
Changes are not pushed to other repositories until
the next sync.
Options:
- --glob PATTERN
- Remove files that match
- --like PATTERN
- Remove files that match
- sync ?URL?
- Synchronize the state of all unversioned files with
the remote repository URL. The most recent version
of each file is propagated to all repositories and
all prior versions are permanently forgotten.
The remote account requires the 'y' capability.
Options:
- -v|--verbose
- Extra diagnostic output
- -n|--dry-run
- Show what would have happened
- touch FILE ...
- Update the TIMESTAMP on all of the listed files
Options:
- --mtime TIMESTAMP
- Use TIMESTAMP instead of "now" for the "add", "edit", "remove", and "touch" subcommands.
- -R|--repository REPO
- Use REPO as the repository
- update (1st tier command)
-
Usage: fossil update ?OPTIONS? ?VERSION? ?FILES...?
Change the version of the current check-out to VERSION. Any uncommitted changes are retained and applied to the new check-out.
The VERSION argument can be a specific version or tag or branch name. If the VERSION argument is omitted, then the leaf of the subtree that begins at the current version is used, if there is only a single leaf. VERSION can also be "current" to select the leaf of the current version or "latest" to select the most recent check-in.
If one or more FILES are listed after the VERSION then only the named files are candidates to be updated, and any updates to them will be treated as edits to the current version. Using a directory name for one of the FILES arguments is the same as using every subdirectory and file beneath that directory.
If FILES is omitted, all files in the current check-out are subject to being updated and the version of the current check-out is changed to VERSION. Any uncommitted changes are retained and applied to the new check-out.
The -n or --dry-run option causes this command to do a "dry run". It prints out what would have happened but does not actually make any changes to the current check-out or the repository.
The -v or --verbose option prints status information about unchanged files in addition to those file that actually do change.
Options:
- --case-sensitive BOOL
- Override case-sensitive setting
- --debug
- Print debug information on stdout
- -n|--dry-run
- If given, display instead of run actions
- --force-missing
- Force update if missing content after sync
- -K|--keep-merge-files
- On merge conflict, retain the temporary files used for merging, named *-baseline, *-original, and *-merge.
- --latest
- Acceptable in place of VERSION, update to latest version
- --nosync
- Do not auto-sync prior to update
- --setmtime
- Set timestamps of all files to match their SCM-side times (the timestamp of the last check-in which modified them).
- -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).
See also: revert
- user (2nd tier command)
-
Usage: fossil user SUBCOMMAND ... ?-R|--repository REPO?
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.
- user-color-map (block-text setting)
-
The user-color-map setting can be used to override user color choices.
The setting is a list of space-separated words pairs. The first word
of each pair is a login name. The second word is an alternative name
used by the color chooser algorithm.
This list is intended to be relatively short. The idea is to only use this map to resolve color collisions between common users.
Visit /hash-color-test?rand for a list of suggested names for the second word of each pair in the list.
- uv-sync (boolean setting)
- If true, automatically send unversioned files as part of a "fossil clone" or "fossil sync" command. The default is false, in which case the -u option is needed to clone or sync unversioned files.
- version (1st tier command)
-
Usage: fossil version ?-v|--verbose?
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.
Repeat the -v option or use -vv for even more information.
- web-browser (setting)
- 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.
- whatis (2nd tier command)
-
Usage: fossil whatis NAME
Resolve the symbol NAME into its canonical artifact hash artifact name and provide a description of what role that artifact plays.
Options:
- -f|--file
- Find artifacts with the same hash as file NAME. If NAME is "-", read content from standard input.
- -q|--quiet
- Show nothing if NAME is not found
- --type TYPE
- Only find artifacts of TYPE (one of: 'ci', 't', 'w', 'g', or 'e')
- -v|--verbose
- Provide extra information (such as the RID)
- wiki (2nd tier command)
-
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|TAG ?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:
- -t|--technote DATETIME|TECHNOTE-ID|TAG
- 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. If TAG is used, the most recently modified tech note with that TAG will be 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 | TECHNOTE-COMMENT) ?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. TECHNOTE-COMMENT is 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. The timestamp specifies when this technote appears in the timeline and is its permanent handle although it may not be unique. When updating a technote 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, which is its UUID.
- --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. Wiki pages associated with
check-ins and branches are NOT shown, unless -a is given.
Options:
- --all
- Include "deleted" pages in output. By default deleted pages are elided.
- -t|--technote
- Technotes will be listed instead of pages. The technotes will be in order of timestamp with the most recent first.
- -a|--show-associated
- Show wiki pages associated with check-ins and branches.
- -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.
- test-diff (test command)
- xdiff (1st tier command)
-
Usage: fossil xdiff [options] FILE1 FILE2
Compute an "external diff" between two files. By "external diff" we mean a diff between two disk files that are not necessarily under management. In other words, this command provides a mechanism to use Fossil's file difference engine on arbitrary disk files. See the "diff" command for computing differences between files that are under management.
This command prints the differences between the two files FILE1 and FILE2. all of the usual diff formatting options (--tk, --by, -c N, etc.) apply. See the "diff" command for a full list of command-line options.
This command used to be called "test-diff". The older "test-diff" spelling still works, for compatibility.
- zip (2nd tier command)
-
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.
If OUTPUTFILE is an empty string or "/dev/null" then no ZIP archive is actually generated. This feature can be used in combination with the --list option to get a list of the filenames that would be in the ZIP archive had it actually been generated.
Options:
- -X|--exclude GLOBLIST
- Comma-separated list of GLOBs of files to exclude
- --include GLOBLIST
- Comma-separated list of GLOBs of files to include
- -l|--list
- Show archive content on stdout
- --name DIRECTORYNAME
- The name of the top-level directory in the archive
- -R REPOSITORY
- Specify a Fossil repository