Community-Lab introduction

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)

Show the details of an attachment artifact.

This "page" is only intended to be used by higher-level pages which have certain Ajax-driven features in common. It is not intended to be used by clients and NONE of its HTTP interfaces are considered documented/stable/supported - they may change on any given build of fossil.

The exact response type depends on the route which gets called. In the case of an initialization error it emits a JSON-format response as documented for ajax_route_error(). Individual routes may emit errors in different formats, e.g. HTML.

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.

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".

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 checkin. 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

/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.

tkt=HASH
page=WIKIPAGE
technote=HASH
from=URL

Query parameters:

tkt=HASH
page=WIKIPAGE
technote=HASH
file=FILENAME
attachid=ID

Query parameters:

tkt=HASH
page=WIKIPAGE
technote=HASH
file=FILENAME
attachid=ID

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.

Query parameters:

tkt=HASH
page=WIKIPAGE
technote=HASH
file=FILENAME
attachid=ID

n=N

Show the top N artifacts

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 checkin. 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

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)

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.

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

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).

Download a single entry for the cache, identified by KEY. This page is normally a hyperlink from the /cachestat page. Requires Admin privilege.

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 one.

Other /chat-OP pages are used by XHR requests from this page to send new chat message, delete older messages, or poll for changes.

This routine both deletes the identified chat entry and also inserts a new entry with the current timestamp and with:

• xmsg = NULL

• file = NULL
• mdel = The msgid of the row that was deleted

This new entry will then be propagated to all listeners so that they will know to delete their copies of the message too.

/chat-poll/N
/chat-poll?name=N

The "name" argument should begin with an integer which is the largest "msgid" that the chat page currently holds. If newer content is available, this routine returns that content straight away. If no new content is available, this webpage blocks until the new content becomes available. In this way, the system implements "hanging-GET" or "long-poll" style event notification. If no new content arrives after a delay of approximately chat-poll-timeout seconds (default: 420), then reply is sent with an empty "msg": field.

If N is negative, then the return value is the N most recent messages. Hence a request like /chat-poll/-100 can be used to initialize a new chat session to just the most recent messages.

Some webservers (althttpd) do not allow a term of the URL path to begin with "-". Then /chat-poll/-100 cannot be used. Instead you have to say "/chat-poll?name=-100".

If the integer parameter "before" is passed in, it is assumed that the client is requesting older messages, up to (but not including) that message ID, in which case the next-oldest "n" messages (default=chat-initial-history setting, equivalent to n=0) are returned (negative n fetches all older entries). The client then needs to take care to inject them at the end of the history rather than the same place new messages go.

If "before" is provided, "name" is ignored.

The reply from this webpage is JSON that describes the new content. Format of the json:

    {
      "msgs":[
        {
           "msgid": integer // message id
           "mtime": text    // When sent:  YYYY-MM-DD HH:MM:SS UTC
           "lmtime: text    // Localtime where the message was sent from
           "xfrom": text    // Login name of sender
           "uclr":  text    // Color string associated with the user
           "xmsg":  text    // HTML text of the message
           "fsize": integer // file attachment size in bytes
           "fname": text    // Name of file attachment
           "fmime": text    // MIME-type of file attachment
           "mdel":  integer // message id of prior message to delete
        }
      ]
    }

The "fname" and "fmime" fields are only present if "fsize" is greater than zero. The "xmsg" field may be an empty string if "fsize" is zero.

The "msgid" values will be in increasing order.

The "mdel" will only exist if "xmsg" is an empty string and "fsize" is zero.

The "lmtime" value might be unknown, in which case it is omitted.

The messages are ordered oldest first unless "before" is provided, in which case they are sorted newest first (to facilitate the client-side UI update).

As a special case, if this routine encounters an error, e.g. the user's permissions cannot be verified because their login cookie expired, the request returns a slightly modified structure:

    {
      "msgs":[
        {
          "isError": true,
          "xfrom": null,
          "xmsg": "error details"
          "mtime": as above,
          "ltime": same as mtime
        }
      ]
    }

If the client gets such a response, it should display the message in a prominent manner and then stop polling for new messages.

On success it responds with an empty response: the new message should be fetched via /chat-poll. On error, e.g. login expiry, it emits a JSON response in the same form as described for /chat-poll errors, but as a standalone object instead of a list of objects.

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.

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

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.

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.

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.

Query parameters:

s=PATTERN

Search for PATTERN

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.

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.

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.

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"/>

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

/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.

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

Optional query parameters:

filename=FILENAME

Repo-relative path to the file.

checkin=VERSION

Checkin version, using any unambiguous symbolic version name.

If passed a filename but no checkin then it will attempt to load that file from the most recent leaf checkin.

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 checkin 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?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 descendents) 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.

Query parameters:

n=N

The number of threads to show on each page

x=X

Skip the first X threads

fpid=X

Hash of the post to be edited. REQUIRED

Query parameters:

n=N

The number of threads to show on each page

x=X

Skip the first X threads

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.

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.

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.)

Show the complete content of a file identified by ARTIFACTID as preformatted text.

Other parameters:

verbose

Show more detail when describing the object

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.

[{"name":NAME, "mtime":MTIME, "hash":HASH, "size":SIZE, "user":USER}]

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

g=URL

Jump back to this URL after login completes

anon

The g=URL is not accessible by "nobody" but is accessible by "anonymous"

g=URL

Jump back to this URL after login completes

anon

The g=URL is not accessible by "nobody" but is accessible by "anonymous"

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.

g=URL

Jump back to this URL after login completes

anon

The g=URL is not accessible by "nobody" but is accessible by "anonymous"

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.

It optionally accepts a p=pikchr-script-code URL parameter or POST value to pre-populate the editor with that code.

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 checkin. 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

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.

The RCVFROM table records where this repository received each artifact, including the time of receipt, user, and IP address.

Access requires Admin privilege.

Query Parameters:

view=REPORT_NAME

Valid values: bymonth, byyear, byuser

user=NAME

Restricts statistics to the given user

type=TYPE

Restricts the report to a specific event type: ci (check-in), f (forum), w (wiki), t (ticket), g (tag) Defaulting to all event types.

The view-specific query parameters include:

view=byweek:

y=YYYY

The year to report (default is the server's current year).

rn=N

Ticket report number. (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

rn=N

Ticket report number. (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

Display the SQL query used to generate a ticket report. The rn=N query parameter identifies the specific report number to be displayed.

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

This page requires administrator access. It is usually accessed using the Admin/Security-Audit menu option from any of the default skins.

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.

w=NUM

-- 0=CSS, 1=footer, 2=header, 3=details, 4=js

sk=NUM

-- the draft skin number

Query parameters:

with=CAP

Only show users that have one or more capabilities in CAP.

ubg

Color backgrounds by username hash

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>".

If the NAME contains one "/" then the part before the "/" is taken as the TAG and the part after the "/" becomes the true name. Hence, the following URLs are all equivalent:

/sqlar/508c42a6398f8/download.sqlar
/sqlar?r=508c42a6398f8&name=download.sqlar
/sqlar/download.sqlar?r=508c42a6398f8
/sqlar?name=508c42a6398f8/download.sqlar

Query parameters:

name=NAME

The base name of the output file. The default value is a configuration parameter in the project settings. A prefix of the name, omitting the extension, is used as the top-most directory name.

r=TAG

The check-in that is turned into a ZIP archive. Defaults to "trunk". This query parameter used to be called "uuid" and the older "uuid" name is still accepted for backwards compatibility. If this query parameter is omitted, the latest "trunk" check-in 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.

(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.

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".

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

Generate a compressed tarball for the check-in specified by the "r" query parameter. Return that compressed tarball as the HTTP reply content.

The r= and name= query parameters can be specified as extensions to the URI. Example, the following URIs are all 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=NAME[.tar.gz]

The base name of the output file. The default value is a configuration parameter in the project settings. A prefix of the name, omitting the extension, is used as the top-most directory name.

r=TAG

The check-in that is turned into a compressed tarball. Defaults to "trunk". This query parameter used to be called "uuid" and "uuid" is still accepted for backwards compatibility. If the name= query parameter contains one "/" character then the part before the / is the TAG and the part after the / is the true name. If no TAG is specified by any of the above means, then "trunk" is used as the default.

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.

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.

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.

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.

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()

Query parameters:

today=DATE

Use DATE as today's date

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

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

d=CHECKIN

Children and descendants of CHECKIN

dp=CHECKIN

Same as 'd=CHECKIN&p=CHECKIN'

df=CHECKIN

Same as 'd=CHECKIN&n1=all&nd'. Mnemonic: "Derived From"

bt=CHECKIN

In conjunction with p=CX, this means show all ancestors of CX going back to the time of CHECKIN. All qualifying check-ins are shown unless there is also an n= or n1= query parameter.

t=TAG

Show only check-ins with the given TAG

r=TAG

Show check-ins related to TAG, equivalent to t=TAG&rel

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

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

shortest

... show only the shortest path

rel

... also show related checkins

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.

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

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.

CHECKIN or TIMEORTAG can be a check-in hash prefix, or a tag, or the name of a branch.

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).

Show the details of a ticket change control artifact.

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.

Full-text search of all current tickets

Show the change history for a single ticket in timeline format.

Query parameters:

y=ci

Show only check-ins associated with the ticket

View a ticket identified by the name= query parameter. Other query parameters:

tl

Show a timeline of the ticket above the status

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.

mtime

Order directory elements by decreasing mtime

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.

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.

byage=1

Order the initial display be decreasing age

showdel=0

Show deleted files

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

Show all differences between two check-ins.

Query parameters:

verbose

Show details

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.

Show a patch that goes from check-in FROM to check-in TO.

showid

Show rid values for each page.

List all available wiki pages with date created and last modified.

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.

/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.

Additional parameters:

showid

Show RID values

Show the complete change history for a single wiki page.

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.

Append text to the end of a wiki page.

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.

Prompt the user to enter the name of a new wiki page. Then redirect to the wikiedit screen for that new page.

Full-text search of all current wiki text

Display information about a wiki page.

If the NAME contains one "/" then the part before the "/" is taken as the TAG and the part after the "/" becomes the true name. Hence, the following URLs are all equivalent:

/sqlar/508c42a6398f8/download.sqlar
/sqlar?r=508c42a6398f8&name=download.sqlar
/sqlar/download.sqlar?r=508c42a6398f8
/sqlar?name=508c42a6398f8/download.sqlar

Query parameters:

name=NAME

The base name of the output file. The default value is a configuration parameter in the project settings. A prefix of the name, omitting the extension, is used as the top-most directory name.

r=TAG

The check-in that is turned into a ZIP archive. Defaults to "trunk". This query parameter used to be called "uuid" and the older "uuid" name is still accepted for backwards compatibility. If this query parameter is omitted, the latest "trunk" check-in 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.

Inputs are files BASELINE, V1, and V2. The file MERGED is generated as output.

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

Make arrangements to add one or more files or directories to the current checkout at the next commit.

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

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

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

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

Options:

--case-sensitive BOOL

Override the case-sensitive setting

--dotfiles

Include files beginning with a dot (".")

-f|--force

Add files without prompting

--ignore CSG

Ignore unmanaged files matching patterns from the Comma Separated Glob (CSG) pattern list

--clean CSG

Also ignore files matching patterns from the Comma Separated Glob (CSG) list

--reset

Reset the ADDED state of a checkout, such that all newly-added (but not yet committed) files are no longer added. No flags other than --verbose and --dry-run may be used with --reset.

--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

See also: addremove, rm

Do all necessary "add" and "rm" commands to synchronize the repository with the content of the working checkout:

• All files in the checkout 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 checkout (that is, all files that show as MISSING with the "status" command) are removed as if by the "rm" command.

The command does not "commit". You must run the "commit" separately as 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 checkout, 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.

See also: add, rm

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

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

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

--smtp-trace

--stdout

-S|--subject SUBJECT

unsubscribe EMAIL

Remove a single subscriber with the given EMAIL.

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 checkouts that have uncommitted changes. This operation has no additional options.

clean

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

config

Only the "config pull AREA" command works.

dbstat

Run the "dbstat" command on all repositories.

extras

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

fts-config

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

git export

Do the "git export" command 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 option is supported.

push

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

rebuild

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

sync

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

set|unset

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

server

Run the "ui" or "server" commands on all repositories.

ui

The root URI gives a listing of all repos.

In addition, the following maintenance operations are supported:

add

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

ignore

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

list | ls

Display the location of all repositories. The -c|--ckout option causes all local checkouts to be listed instead.

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

Options:

--dry-run

If given, display instead of run actions.

--showfile

Show the repository or checkout being operated upon.

--stop-on-error

Halt immediately if any subprocess fails.

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 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

Make this check-in the start of branch 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.

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

See also: info, finfo, timeline

Extract an artifact by its artifact hash and write the results on standard output, or if the optional 4th argument is given, in the named output file.

Options:

-R|--repository REPO

Extract artifacts from repository REPO

See also: finfo

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.

Run backoffice processing on the repositories listed. If no repository is specified, run it on the repository of the local checkout.

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

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 checkout 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

Run various subcommands useful for searching back through the change history for a particular checkin that causes or fixes a problem.

fossil bisect bad ?VERSION?

Identify version VERSION as non-working. If VERSION is omitted, the current checkout is marked as non-working.

fossil bisect good ?VERSION?

Identify version VERSION as working. If VERSION is omitted, the current checkout 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 skip ?VERSION?

Cause VERSION (or the current checkout 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

Like "fossil ui" except start on a timeline that shows only the check-ins that are part of the current bisect.

fossil bisect undo

Undo the most recent "good", "bad", or "skip" command.

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

See also: info, finfo, timeline

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

fossil branch current

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

fossil branch info BRANCH-NAME

Print information about a branch

fossil branch list|ls ?OPTIONS? ?GLOB?

List all branches. Options:

-a|--all

List all branches. Default show only open branches

-c|--closed

List closed branches.

-r

Reverse the sort order

-t

Show recently changed branches first

If GLOB is given, show only branches matching the pattern.

fossil branch new BRANCH-NAME BASIS ?OPTIONS?

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

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

Options valid for all subcommands:

-R|--repository REPO

Run commands on repository REPO

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

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.

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.

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:

-R|--repository REPO

Extract artifacts from repository REPO

-r VERSION

The specific check-in containing the file

See also: finfo

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.

skin: LABEL

Use the built-in skin called LABEL rather than the default. 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.

See also: http, server, winsrv

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

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

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

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

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

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

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

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

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

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

General options:

--abs-paths

Display absolute pathnames.

--rel-paths

Display pathnames relative to the current working directory.

--hash

Verify file status using hashing rather than relying on file mtimes.

--case-sensitive BOOL

Override case-sensitive setting.

--dotfiles

Include unmanaged files beginning with a dot.

--ignore <CSG>

Ignore unmanaged files matching CSG glob patterns.

Options specific to the changes command:

--header

Identify the repository if report is non-empty.

-v|--verbose

Say "(none)" if the change report is empty.

--classify

Start each line with the file's change type.

--no-classify

Do not print file change types.

Filter options:

--edited

Display edited, merged, and conflicted files.

--updated

Display files updated by merge/integrate.

--changed

Combination of the above two options.

--missing

Display missing files.

--added

Display added files.

--deleted

Display deleted files.

--renamed

Display renamed files.

--conflict

Display files having merge conflicts.

--meta

Display files with metadata changes.

--unchanged

Display unchanged files.

--all

Display all managed files, i.e. all of the above.

--extra

Display unmanaged files.

--differ

Display modified and extra files.

--merge

Display merge contributors.

--no-merge

Do not display merge contributors.

See also: extras, ls

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.

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.

The following subcommands are supported:

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

-m|--message TEXT

Text of the chat message

--unsafe

Allow the use of unencrypted http://

Additional subcommands may be added in the future.

A value of 0.0 or less means that messages are retained forever.

For maximum efficiency, it is best to choose the longest delay that does not cause timeouts in intermediate proxies or web server.

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 checkout 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 checkout the latest version in the repository.

Options:

--force

Ignore edited files in the current checkout

--keep

Only update the manifest and manifest.uuid files

--force-missing

Force checkout even if content is missing

--setmtime

Set timestamps of all files to match their SCM-side times (the timestamp of the last checkin which modified them)

See also: update

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

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

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

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

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

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

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

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

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

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

Options:

--allow-conflict

allow unresolved merge conflicts

--allow-empty

allow a commit with no changes

--allow-fork

allow the commit to fork

--allow-older

allow a commit older than its ancestor

--baseline

use a baseline manifest in the commit process

--bgcolor COLOR

apply COLOR to this one check-in only

--branch NEW-BRANCH-NAME

check in to this new branch

--branchcolor COLOR

apply given COLOR to the branch

--close

close the branch being committed

--date-override DATETIME

DATE to use instead of 'now'

--delta

use a delta manifest in the commit process

--hash

verify file status using hashing rather than relying on file mtimes

--integrate

close all merged-in branches

-m|--comment COMMENT-TEXT

use COMMENT-TEXT as commit comment

-M|--message-file FILE

read the commit comment from given file

--mimetype MIMETYPE

mimetype of check-in comment

-n|--dry-run

If given, display instead of run actions

-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

--override-lock

allow a check-in even though parent is locked

--private

do not sync changes and their descendants

--tag TAG-NAME

assign given tag TAG-NAME to the check-in

--trace

debug tracing.

--user-override USER

USER to use instead of the current default

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

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

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

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

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

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

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

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

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

Options:

--allckouts

Check for empty directories within any checkouts that may be nested within the current one. This option should be used with great care because the empty-dirs setting (and other applicable settings) belonging to the other repositories, if any, will not be checked.

--case-sensitive BOOL

Override case-sensitive setting

--dirsonly

Only remove empty directories. No files will be removed. Using this option will automatically enable the --emptydirs option as well.

--disable-undo

WARNING: This option disables use of the undo mechanism for this clean operation and should be used with extreme caution.

--dotfiles

Include files beginning with a dot (".")

--emptydirs

Remove any empty directories that are not explicitly exempted via the empty-dirs setting or another applicable setting or command line argument. Matching files, if any, are removed prior to checking for any empty directories; therefore, directories that contain only files that were removed will be removed as well.

-f|--force

Remove files without prompting

-i|--prompt

Prompt before removing each file. This option implies the --disable-undo option.

-x|--verily

WARNING: Removes everything that is not a managed file or the repository itself. This option implies the --force, --emptydirs, --dotfiles, and --disable-undo options. Furthermore, it completely disregards the keep-glob and ignore-glob settings. However, it does honor the --ignore and --keep options.

--clean CSG

WARNING: Never prompt to delete any files matching this comma separated list of glob patterns. Also, deletions of any files matching this pattern list cannot be undone.

--ignore CSG

Ignore files matching patterns from the comma separated list of glob patterns

--keep <CSG>

Keep files matching this comma separated list of glob patterns

-n|--dry-run

Delete nothing, but display what would have been deleted

--no-prompt

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

See also: addremove, extras, status

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

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

• HTTP/HTTPS protocol:

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

• SSH protocol:

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

• Filesystem:

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

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

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

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

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

Options:

-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 checkout

--nocompress

Omit extra delta compression

--no-open

Clone only. Do not open a check-out.

--once

Don't remember the URI.

--private

Also clone private branches

--save-http-password

Remember the HTTP password without asking

--ssh-command|-c SSH

Use SSH as the "ssh" command

--ssl-identity FILENAME

Use the SSL identity if requested by the server

-u|--unversioned

Also sync unversioned content

-v|--verbose

Show more statistics in output

--workdir DIR

Also open a checkout in DIR

See also: init, open

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

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 checkout 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 checkout the latest version in the repository.

Options:

--force

Ignore edited files in the current checkout

--keep

Only update the manifest and manifest.uuid files

--force-missing

Force checkout even if content is missing

--setmtime

Set timestamps of all files to match their SCM-side times (the timestamp of the last checkin which modified them)

See also: update

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.

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

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

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

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

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

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

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

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

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

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

Options:

--allow-conflict

allow unresolved merge conflicts

--allow-empty

allow a commit with no changes

--allow-fork

allow the commit to fork

--allow-older

allow a commit older than its ancestor

--baseline

use a baseline manifest in the commit process

--bgcolor COLOR

apply COLOR to this one check-in only

--branch NEW-BRANCH-NAME

check in to this new branch

--branchcolor COLOR

apply given COLOR to the branch

--close

close the branch being committed

--date-override DATETIME

DATE to use instead of 'now'

--delta

use a delta manifest in the commit process

--hash

verify file status using hashing rather than relying on file mtimes

--integrate

close all merged-in branches

-m|--comment COMMENT-TEXT

use COMMENT-TEXT as commit comment

-M|--message-file FILE

read the commit comment from given file

--mimetype MIMETYPE

mimetype of check-in comment

-n|--dry-run

If given, display instead of run actions

-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

--override-lock

allow a check-in even though parent is locked

--private

do not sync changes and their descendants

--tag TAG-NAME

assign given tag TAG-NAME to the check-in

--trace

debug tracing.

--user-override USER

USER to use instead of the current default

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

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

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

fossil configuration export AREA FILENAME

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

all email interwiki project shun skin
ticket user alias subscriber

fossil configuration import FILENAME

Read a configuration from FILENAME, overwriting the current configuration.

fossil configuration merge FILENAME

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

fossil configuration pull AREA ?URL?

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

fossil configuration push AREA ?URL?

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

fossil configuration reset AREA

Restore the configuration to the default. AREA as above.

fossil configuration sync AREA ?URL?

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

Options:

-R|--repository REPO

Extract info from repository REPO

See also: settings, unset

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.

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).

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.

Remove one or more files or directories from the repository.

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

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

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

Options:

--soft

Skip removing files from the checkout. This supersedes the --hard option.

--hard

Remove files from the checkout.

--case-sensitive BOOL

Override the case-sensitive setting.

-n|--dry-run

If given, display instead of run actions.

--reset

Reset the DELETED state of a checkout, such that all newly-rm'd (but not yet committed) files are no longer removed. No flags other than --verbose or --dry-run may be used with --reset.

-v|--verbose

Outputs information about each --reset file. Only usable with --reset.

See also: addremove, add

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.

See also: finfo, info, leaves

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

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

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

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

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

The "-v" or "--verbose" option causes the complete text of added or deleted files to be displayed. -N and --new-file are aliases for verbose mode.

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

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

Options:

--binary PATTERN

Treat files that match the glob PATTERN as binary

--branch BRANCH

Show diff of all changes on BRANCH

--brief

Show filenames only

--checkin VERSION

Show diff of all changes in VERSION

--command PROG

External diff program. Overrides "diff-command"

-c|--context N

Use N lines of context

--diff-binary BOOL

Include binary files with external commands

--exec-abs-paths

Force absolute path names on external commands

--exec-rel-paths

Force relative path names on external commands

-r|--from VERSION

Select VERSION as source for the diff

-i|--internal

Use internal diff logic

--numstat

Show only the number of lines delete and added

-y|--side-by-side

Side-by-side diff

--strip-trailing-cr

Strip trailing CR

--tclsh PATH

Tcl/Tk used for --tk (default: "tclsh")

--tk

Launch a Tcl/Tk GUI for display

--to VERSION

Select VERSION as target for the diff

--undo

Diff against the "undo" buffer

--unified

Unified diff

-v|--verbose

Output complete text of added or deleted files

-N|--new-file

Alias for --verbose

-w|--ignore-all-space

Ignore white space when comparing lines

-W|--width N

Width of lines in side-by-side diff

-Z|--ignore-trailing-space

Ignore changes to end-of-line whitespace

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

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

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

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

Options:

--abs-paths

Display absolute pathnames

--case-sensitive BOOL

Override case-sensitive setting

--dotfiles

Include files beginning with a dot (".")

--header

Identify the repository if there are extras

--ignore CSG

Ignore files matching patterns from the argument

--rel-paths

Display pathnames relative to the current working directory

See also: changes, clean, status

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

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

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

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

Options:

-b|--brief

Display a brief (one line / revision) summary

--case-sensitive B

Enable or disable case-sensitive filenames. B is a boolean: "yes", "no", "true", "false", etc.

-l|--log

Select log mode (the default)

-n|--limit N

Display the first N changes (default unlimited). N less than 0 means no limit.

--offset P

Skip P changes

-p|--print

Select print mode

-r|--revision R

Print the given revision (or ckout, if none is given) to stdout (only in print mode)

-s|--status

Select status mode (print a status indicator for FILE)

-W|--width N

Width of lines (default is to auto-detect). Must be more than 22 or else 0 to indicate no limit.

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

Remove one or more files or directories from the repository.

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

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

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

Options:

--soft

Skip removing files from the checkout. This supersedes the --hard option.

--hard

Remove files from the checkout.

--case-sensitive BOOL

Override the case-sensitive setting.

-n|--dry-run

If given, display instead of run actions.

--reset

Reset the DELETED state of a checkout, such that all newly-rm'd (but not yet committed) files are no longer removed. No flags other than --verbose or --dry-run may be used with --reset.

-v|--verbose

Outputs information about each --reset file. Only usable with --reset.

See also: addremove, add

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 cdtwe

Enable various kinds of search. c=Check-ins, d=Documents, t=Tickets, w=Wiki, e=Tech Notes.

disable cdtwe

Disable various kinds of search

stemmer (on|off)

Turn the Porter stemmer on or off for indexed search. (Unindexed search is never stemmed.)

The current search settings are displayed after any changes are applied. Run this command with no arguments to simply see the settings.

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.

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

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

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

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

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

The "-v" or "--verbose" option causes the complete text of added or deleted files to be displayed. -N and --new-file are aliases for verbose mode.

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

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

Options:

--binary PATTERN

Treat files that match the glob PATTERN as binary

--branch BRANCH

Show diff of all changes on BRANCH

--brief

Show filenames only

--checkin VERSION

Show diff of all changes in VERSION

--command PROG

External diff program. Overrides "diff-command"

-c|--context N

Use N lines of context

--diff-binary BOOL

Include binary files with external commands

--exec-abs-paths

Force absolute path names on external commands

--exec-rel-paths

Force relative path names on external commands

-r|--from VERSION

Select VERSION as source for the diff

-i|--internal

Use internal diff logic

--numstat

Show only the number of lines delete and added

-y|--side-by-side

Side-by-side diff

--strip-trailing-cr

Strip trailing CR

--tclsh PATH

Tcl/Tk used for --tk (default: "tclsh")

--tk

Launch a Tcl/Tk GUI for display

--to VERSION

Select VERSION as target for the diff

--undo

Diff against the "undo" buffer

--unified

Unified diff

-v|--verbose

Output complete text of added or deleted files

-N|--new-file

Alias for --verbose

-w|--ignore-all-space

Ignore white space when comparing lines

-W|--width N

Width of lines in side-by-side diff

-Z|--ignore-trailing-space

Ignore changes to end-of-line whitespace

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 checkins 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.

kdiff3 "%baseline" "%original" "%merge" -o "%output"
xxdiff "%original" "%baseline" "%merge" -M "%output"
meld "%baseline" "%original" "%merge" "%output"

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

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".

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

The following options can be used when TOPIC is omitted:

-a|--all

List both common and auxiliary commands

-o|--options

List command-line options common to all commands

-s|--setting

List setting names

-t|--test

List unsupported "test" commands

-x|--aux

List only auxiliary commands

-w|--www

List all web pages

-f|--full

List full set of commands (including auxiliary and unsupported "test" commands), options, settings, and web pages

-e|--everything

List all help on all topics

These options can be used when TOPIC is present:

-h|--html

Format output as HTML rather than plain text

-c|--commands

Restrict TOPIC search to commands

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.

{
"type": "after-receive",  // type of hook
"cmd": "command-to-run",  // command to run
"seq": 50                 // run in this order
}

Handle a single HTTP request appearing on stdin. The resulting webpage is delivered on stdout. This method is used to launch an HTTP request handler from inetd, for example. The argument is the name of the repository.

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.

The --host option can be used to specify the hostname for the server. The --https option indicates that the request came from HTTPS rather than HTTP. If --nossl is given, then SSL connections will not be available, thus also no redirecting from http: to https: will take place.

If the --localauth option is given, then automatic login is performed for requests coming from localhost, if the "localauth" setting is not enabled.

Options:

--baseurl URL

base URL (useful with reverse proxies)

--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

specify hostname of the server

--https

signal a request coming in via https

--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:

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.

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.

--localauth

enable automatic login for local connections

--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

signal that no SSL connections are available

--notfound URL

use URL as "HTTP 404, object not found" page.

--out FILE

write results to FILE instead of to standard output

--repolist

If REPOSITORY is directory, URL "/" lists all repos

--scgi

Interpret input as SCGI rather than HTTP

--skin LABEL

Use override skin LABEL

--th-trace

trace TH1 execution (for debugging purposes)

--mainmenu FILE

Override the mainmenu config setting with the contents of the given file.

--usepidkey

Use saved encryption key from parent process. This is only necessary when using SEE on Windows.

See also: cgi, server, winsrv

Example: *.log customCode.c notes.txt

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"

See also: export

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 a object within the repository.

Use the "finfo" command to get information about a specific file in a checkout.

Options:

-R|--repository REPO

Extract info from repository REPO

-v|--verbose

Show extra information about repositories

See also: annotate, artifact, finfo, timeline

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

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

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

Options:

--template

FILE Copy settings from repository file

-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"

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

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 a 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.

In CLI mode, the -R REPO common option is supported. Due to limitations in the argument dispatching code, any -FLAGS must come after the final sub- (or subsub-) command.

The -json-input FILE option can be used to read JSON data and process it like the HTTP interface would. For example:

fossil json -json-input my.json

The commands include:

anonymousPassword
artifact
branch
cap
config
diff
dir
g
login
logout
query
rebuild
report
resultCodes
stat
tag
timeline
user
version (alias: HAI)
whoami
wiki

Run 'fossil json' without any subcommand to see the full list (but be aware that some listed might not yet be fully implemented).

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

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.

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 user 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.

With no arguments, this command shows the login-group to which the repository belongs.

The "join" command adds this repository to login group to which REPO belongs, or creates a new login group between itself and REPO if REPO does not already belong to a login-group. When creating a new login- group, the name of the new group is determined by the "--name" option.

The "leave" command takes the repository out of whatever login group it is currently a part of.

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.

List all files in the current checkout. 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.

-v|--verbose

Provide extra information about each file.

-t

Sort output in time order.

-r VERSION

The specific check-in to list.

-R|--repository REPO

Extract info from repository REPO.

--hash

With -v, verify file status using hashing rather than relying on file sizes and mtimes.

See also: changes, extras, status

• 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 evalutes 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 will 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.

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.

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

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

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

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

Options:

--backout

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

--baseline BASELINE

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

--binary GLOBPATTERN

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

--case-sensitive BOOL

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

--cherrypick

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

-f|--force

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

--force-missing

Force the merge even if there is missing content.

--integrate

Merged branch will be closed when committing.

-K|--keep-merge-files

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

-n|--dry-run

If given, display instead of run actions

-v|--verbose

Show additional details of the merge

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

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

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

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

Options:

--soft

Skip moving files within the checkout. This supersedes the --hard option.

--hard

Move files within the checkout

--case-sensitive BOOL

Override the case-sensitive setting

-n|--dry-run

If given, display instead of run actions

See also: changes, status

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

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

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

Options:

--template

FILE Copy settings from repository file

-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"

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

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

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

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

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

Options:

--empty

Initialize checkout as being empty, but still connected with the local repository. If you commit this checkout, it will become a new "initial" commit in the repository.

-f|--force

Continue with the open even if the working directory is not empty.

--force-missing

Force opening a repository with missing content

--keep

Only modify the manifest and manifest.uuid files

--nested

Allow opening a repository inside an opened checkout

--repodir DIR

If REPOSITORY is a URI that will be cloned, store the clone in DIR rather than in "."

--setmtime

Set timestamps of all files to match their SCM-side times (the timestamp of the last checkin which modified them).

--workdir DIR

Use DIR as the working directory instead of ".". The DIR directory is created if it does not exist.

See also: close, clone

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).

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 checkout 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.

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

See also: info, finfo, timeline

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.

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

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

Options:

-B|--httpauth USER:PASS

Credentials for the simple HTTP auth protocol, if required by the remote website

--from-parent-project

Pull content from the parent project

--ipv4

Use only IPv4, not IPv6

--once

Do not remember URL for subsequent syncs

--private

Pull private branches too

--project-code CODE

Use CODE as the project code

--proxy PROXY

Use the specified HTTP proxy

-R|--repository REPO

Local repository to pull into

--ssl-identity FILE

Local SSL credentials, if requested by remote

--ssh-command SSH

Use SSH as the "ssh" command

-v|--verbose

Additional (debugging) output

--verily

Exchange extra information with the remote to ensure no content is overlooked

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

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

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

Options:

-B|--httpauth USER:PASS

Credentials for the simple HTTP auth protocol, if required by the remote website

--ipv4

Use only IPv4, not IPv6

--once

Do not remember URL for subsequent syncs

--proxy PROXY

Use the specified HTTP proxy

--private

Push private branches too

-R|--repository REPO

Local repository to push from

--ssl-identity FILE

Local SSL credentials, if requested by remote

--ssh-command SSH

Use SSH as the "ssh" command

-v|--verbose

Additional (debugging) output

--verily

Exchange extra information with the remote to ensure no content is overlooked

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

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

Options:

--analyze

Run ANALYZE on the database after rebuilding

--cluster

Compute clusters for unclustered artifacts

--compress

Strive to make the database as small as possible

--compress-only

Skip the rebuilding step. Do --compress only

--deanalyze

Remove ANALYZE tables from the database

--force

Force the rebuild to complete even if errors are seen

--ifneeded

Only do the rebuild if it would change the schema version

--index

Always add in the full-text search index

--noverify

Skip the verification of changes to the BLOB table

--noindex

Always omit the full-text search index

--pagesize N

Set the database pagesize to N. (512..65536 and power of 2)

--quiet

Only show output if there are errors

--randomize

Scan artifacts in a random order

--stats

Show artifact statistics after rebuilding

--vacuum

Run VACUUM on the database after rebuilding

--wal

Set Write-Ahead-Log journalling mode on the database

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.

The undo command reverts the changes caused by the previous command if the previous command is one of the following:

• fossil update
• fossil merge
• fossil revert
• fossil stash pop
• fossil stash apply
• fossil stash drop
• fossil stash goto
• fossil clean (*see note below*)

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

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

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

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

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

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

Options:

-n|--dry-run

Do not make changes but show what would be done

See also: commit, status

View or modify the set of remote repository sync URLs used as the target in any command that uses the sync protocol: "sync", "push", and "pull", plus all other commands that trigger Fossil's autosync feature. (Collectively, "sync operations".)

See "fossil help clone" for the format of these sync URLs.

Fossil implicitly sets the default remote sync URL from the initial "clone" or "open URL" command for a repository, then may subsequently change it when given a URL in commands that take a sync URL, except when given the --once flag. Fossil uses this new sync URL as its default when not explicitly given one in subsequent sync operations.

Named remotes added by "remote add" allow use of those names in place of a sync URL in any command that takes one.

The full name of this command is "remote-url", but we anticipate no future collision from use of its shortened form "remote".

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 to the set of remote sync URLs for use in place of a sync URL in commands that take one.

fossil remote delete NAME

Delete a sync URL previously added by the "add" subcommand.

fossil remote list|ls

Show all remote repository sync URLs.

fossil remote off

Forget the default sync URL, disabling autosync. Combined with named sync URLs, it allows canceling this "airplane mode" with "fossil remote NAME" to select a previously-set named URL.

To disable use of the default remote without forgetting its URL, say "fossil set autosync 0" instead.

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".

View or modify the set of remote repository sync URLs used as the target in any command that uses the sync protocol: "sync", "push", and "pull", plus all other commands that trigger Fossil's autosync feature. (Collectively, "sync operations".)

See "fossil help clone" for the format of these sync URLs.

Fossil implicitly sets the default remote sync URL from the initial "clone" or "open URL" command for a repository, then may subsequently change it when given a URL in commands that take a sync URL, except when given the --once flag. Fossil uses this new sync URL as its default when not explicitly given one in subsequent sync operations.

Named remotes added by "remote add" allow use of those names in place of a sync URL in any command that takes one.

The full name of this command is "remote-url", but we anticipate no future collision from use of its shortened form "remote".

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 to the set of remote sync URLs for use in place of a sync URL in commands that take one.

fossil remote delete NAME

Delete a sync URL previously added by the "add" subcommand.

fossil remote list|ls

Show all remote repository sync URLs.

fossil remote off

Forget the default sync URL, disabling autosync. Combined with named sync URLs, it allows canceling this "airplane mode" with "fossil remote NAME" to select a previously-set named URL.

To disable use of the default remote without forgetting its URL, say "fossil set autosync 0" instead.

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".

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

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

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

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

Options:

--soft

Skip moving files within the checkout. This supersedes the --hard option.

--hard

Move files within the checkout

--case-sensitive BOOL

Override the case-sensitive setting

-n|--dry-run

If given, display instead of run actions

See also: changes, status

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|--dryrun

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

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 to the current repository version of FILE, or to the baseline VERSION specified with -r flag.

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

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

Revert all files if no file name is provided.

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

Options:

-r|--revision VERSION

Revert given FILE(s) back to given VERSION

See also: redo, undo, checkout, update

Remove one or more files or directories from the repository.

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

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

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

Options:

--soft

Skip removing files from the checkout. This supersedes the --hard option.

--hard

Remove files from the checkout.

--case-sensitive BOOL

Override the case-sensitive setting.

-n|--dry-run

If given, display instead of run actions.

--reset

Reset the DELETED state of a checkout, such that all newly-rm'd (but not yet committed) files are no longer removed. No flags other than --verbose or --dry-run may be used with --reset.

-v|--verbose

Outputs information about each --reset file. Only usable with --reset.

See also: addremove, add

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).

- 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

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 for timeline entries matching all words provided on the command line. Whole-word matches scope more highly than partial matches.

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

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

Options:

-a|--all

Output all matches, not just best matches.

-n|--limit N

Limit output to N matches.

-W|--width WIDTH

Set display width to WIDTH columns, 0 for unlimited. Defaults the terminal's width.

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

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

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

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

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

Options:

--baseurl URL

Use URL as the base (useful for reverse proxies)

--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

--extroot DIR

Document root for the /ext extension mechanism

--files GLOBLIST

Comma-separated list of glob patterns for static files

--localauth

enable automatic login for requests from localhost

--localhost

listen on 127.0.0.1 only (always true for "ui")

--https

Indicates that the input is coming through a reverse proxy that has already translated HTTPS into HTTP.

--jsmode MODE

Determine how JavaScript is delivered with pages. Mode can be one of:

inline

All JavaScript is inserted inline at the end of the HTML file.

separate

Separate HTTP requests are made for each JavaScript file.

bundled

One single separate HTTP fetches all JavaScript concatenated together.

Depending on the needs of any given page, inline and bundled modes might result in a single amalgamated script or several, but both approaches result in fewer HTTP requests than the separate mode.

--max-latency N

Do not let any single HTTP request run for more than N seconds (only works on unix)

--nocompress

Do not compress HTTP replies

--nojail

Drop root privileges but do not enter the chroot jail

--nossl

signal that no SSL connections are available (Always set by default for the "ui" command)

--notfound URL

Redirect

--page PAGE

Start "ui" on PAGE. ex: --page "timeline?y=ci"

-P|--port TCPPORT

listen to request on port TCPPORT

--th-trace

trace TH1 execution (for debugging purposes)

--repolist

If REPOSITORY is dir, URL "/" lists repos.

--scgi

Accept SCGI rather than HTTP

--skin LABEL

Use override skin LABEL

--mainmenu FILE

Override the mainmenu config setting with the contents of the given file.

--usepidkey

Use saved encryption key from parent process. This is only necessary when using SEE on Windows.

See also: cgi, http, winsrv

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

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

The "unset" command clears a setting.

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

Options:

--global

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

--exact

only consider exact name matches.

See also: configuration

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.

See also: md5sum, sha3sum

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

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

Options:

--224

Compute a SHA3-224 hash

--256

Compute a SHA3-256 hash (the default)

--384

Compute a SHA3-384 hash

--512

Compute a SHA3-512 hash

--size N

An N-bit hash. N must be a multiple of 32 between 128 and 512.

-h|--dereference

If FILE is a symbolic link, compute the hash on the object pointed to, not on the link itself.

See also: md5sum, sha1sum

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.

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 evalutes 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.

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.

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 filename 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

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.

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 identity will be presented to SSL servers to authenticate this client, in addition to the normal password authentication.

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 checkout 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 checkout. 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 checkout 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.

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

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

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

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

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

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

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

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

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

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

General options:

--abs-paths

Display absolute pathnames.

--rel-paths

Display pathnames relative to the current working directory.

--hash

Verify file status using hashing rather than relying on file mtimes.

--case-sensitive BOOL

Override case-sensitive setting.

--dotfiles

Include unmanaged files beginning with a dot.

--ignore <CSG>

Ignore unmanaged files matching CSG glob patterns.

Options specific to the changes command:

--header

Identify the repository if report is non-empty.

-v|--verbose

Say "(none)" if the change report is empty.

--classify

Start each line with the file's change type.

--no-classify

Do not print file change types.

Filter options:

--edited

Display edited, merged, and conflicted files.

--updated

Display files updated by merge/integrate.

--changed

Combination of the above two options.

--missing

Display missing files.

--added

Display added files.

--deleted

Display deleted files.

--renamed

Display renamed files.

--conflict

Display files having merge conflicts.

--meta

Display files with metadata changes.

--unchanged

Display unchanged files.

--all

Display all managed files, i.e. all of the above.

--extra

Display unmanaged files.

--differ

Display modified and extra files.

--merge

Display merge contributors.

--no-merge

Do not display merge contributors.

See also: extras, ls

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

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

Options:

-B|--httpauth USER:PASS

Credentials for the simple HTTP auth protocol, if required by the remote website

--ipv4

Use only IPv4, not IPv6

--once

Do not remember URL for subsequent syncs

--proxy PROXY

Use the specified HTTP proxy

--private

Sync private branches too

-R|--repository REPO

Local repository to sync with

--ssl-identity FILE

Local SSL credentials, if requested by remote

--ssh-command SSH

Use SSH as the "ssh" command

-u|--unversioned

Also sync unversioned content

-v|--verbose

Additional (debugging) output

--verily

Exchange extra information with the remote to ensure no content is overlooked

See also: clone, pull, push, remote

Run various subcommands to control tags and properties.

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

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

Options:

--raw

Raw tag name.

--propagate

Propagating tag.

--date-override DATETIME

Set date and time added.

--user-override USER

Name USER when adding the tag.

-n|--dryrun

Display the tag text, but do not actually insert it into the database.

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

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

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

Options:

--raw

Raw tag name.

--date-override DATETIME

Set date and time deleted.

--user-override USER

Name USER when deleting the tag.

-n|--dryrun

Display the control artifact, but do not insert it into the database.

fossil tag find ?OPTIONS? TAGNAME

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

Options:

--raw

Raw tag name.

-t|--type TYPE

One of "ci", or "e".

-n|--limit N

Limit to N results.

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

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

Options:

--raw

List tags raw names of tags

--tagtype TYPE

List only tags of type TYPE

-v|--inverse

Inverse the meaning of --tagtype TYPE.

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

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

fossil update decaf

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

fossil update tag:decaf

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

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 filename that would be in the tarball had it actually been generated. Note that --list shows only filenames. "tar tzf" shows both filesnames 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

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".

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:

-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 deleted)

%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 checkout'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 ust be zero 0 to indicate no limit, resulting in a single line per entry.