FNC(1) General Commands Manual FNC(1)

fnc — interactive text-based user interface for Fossil repositories

fnc command [arg ...]

fnc [-hv]

fnc path


fnc blame [-ChRz] [-c commit] [-l lineno] [-n n] [-r path] path

fnc branch [-CchopRz] [-a date] [-b date] [-r path] [-s order] [glob]

fnc commit [-h] [-m msg] [path ...]

fnc config [-hl] [-r path] [-u option] [option [value]]

fnc diff [-bCDhiloPqsWwz] [-r path] [-x n] [artifact1 [artifact2]] [path ...]

fnc histedit [-aCcdefhlm] [-F path] [-X [reference]]

fnc stash [-hP] [-C n] [(get|pop) [id]]

fnc timeline [-ChPz] [-b branch] [-c commit] [-f glob] [-n n] [-r path] [-T tag] [-t type] [-u user] [path]

fnc tree [-Chz] [-c commit] [-r path] [path]

fnc is an interactive text-based user interface for exploring fossil(1) repositories, and managing local changes in a Fossil work tree.

To facilitate navigation and display repository data, fnc supports multiple views:

Display commits from the repository's history in chronologically descending order. If no command or only a path is specified, fnc will default to displaying this view.
Display changes introduced in the specified commit, between two repository artifacts, or local changes in the work tree.
Display navigable tree reflecting the repository state as at the specified commit.
Display and annotate each line in the given file with the hyperlinked commit in which the line was last modified.
Display navigable list of all repository branches.

fnc provides both global and command-specific options, and runtime key bindings. Some command-specific key maps may be prefixed with an integer, which is denoted by ‘N’ in the descriptions below, and is used as a modifier to the operation as indicated. fnc echoes digits to the view when count modifiers are entered, and completes the sequence on input of the first non-numeric character. Count modifiers can be aborted by entering an unmapped key. Inflight compound commands can be canceled with ^G or backspace. Global options are as follows:

, --help
Display program help and usage information then exit.
, --version
Display program version then exit.

Global key bindings are as follows:

Display runtime help.
Toggle between coloured and monochromatic output. On supported terminals, fnc will default to displaying all views in colour. Colours can be customised using the config command or environment variables (see ENVIRONMENT for details).
Switch focus between open views.
Toggle between fullscreen and splitscreen mode. By default, fnc will open child views in a vertical split if the terminal window is ≥ 120 columns wide. Set FNC_VIEW_SPLIT_MODE as documented in the ENVIRONMENT section to change this behaviour.
Switch between horizontal and vertical splitscreen layout, and render all active views in the new layout. If the terminal is not wide enough when switching to a vertical split, views will render in fullscreen.
When in a splitscreen view, decrease the size of the active split N increments (default: 1).
When in a splitscreen view, increase the size of the active split N increments (default: 1).
Scroll to the last line in the view.
Scroll to the first line in the view.
Quit fnc.
Quit the active view.

Commands available to fnc are as follows:

[-h] [-m msg] [path ...]
(alias: ci)
Create a new commit in the repository from changes in the work tree while a histedit operation is paused for an edit command. If no path arguments are specified, commit all changes in the work tree. Otherwise, commit changes at or within the specified paths.

This command is currently only supported while a histedit operation is paused; use fossil(1) commit otherwise. The options for fnc commit are as follows:

, --help
Display commit command help and usage information then exit.
, --message msg
Use msg as the commit message instead of opening an editor.
[-hl] [-r path] [-u option | option [value]]
(aliases: conf, set)
Retrieve the current or set a new value for option in the local repository. When specified, value will become the new value for option, otherwise fnc will display the current value of option. With no arguments, fnc config will list all user-defined options; see ENVIRONMENT for a detailed list of all available options and their default values.

During initialisation, if no value is defined for a given option in the local repository, environment variables will be searched. If still not found, fnc will fallback to default values.

Unless the -r option is used to specify a path to the fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

Options for fnc config are as follows:

, --help
Display config command help and usage information then exit.
, --ls
List all available options.
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --unset option
Clear the specified option.
[-aCcdefhlm] [-F path] [-X [reference]]
(alias: he)
Edit the commit history between the work tree's current base commit (exclusive) and the tip commit of the work tree's current branch (inclusive).

Before running fnc histedit, the work tree's base commit must be updated to a commit preceding the first commit to be edited; for example, with the fossil(1) update command. This base commit is the lower (exclusive) bound of the edited range, and the tip of the work tree's branch is the upper (inclusive) bound. The work tree must not contain uncommitted local changes.

Unless one of the -d, -e, -f, or -m options is used, fnc opens VISUAL, EDITOR, or /usr/bin/vi, in that order of preference, with a line-based script listing one commit per line in order from oldest to newest. Each line begins with a followed by whitespace and an abbreviated commit hash. Lines beginning with ‘#’ are ignored. Quitting the editor without saving aborts the operation.

The available histedit script commands are as follows:

commit use the commit as-is
commit combine the commit with the next commit that is used
commit remove the commit from the edited history
commit open an editor to reword the commit's log message
commit apply the commit, then pause for amending

Lines may be reordered to reorder commits in the edited history. Every commit in the edited range must be listed exactly once.

The edited history is constructed by replaying the selected commits as a new linear sequence on top of the base commit. Each replayed commit retains its original author. Where possible, original commit timestamps are preserved but reordered commits are given a new commit timestamp that increases monotonically along the edited line. The edited branch is left with a single linear history and the work tree is updated to the newly edited tip.

The original commits are not deleted; instead, the original line is marked private and moved onto a private branch named “backup/histedit/HASH-PREFIX” (where "HASH-PREFIX" is an abbreviated SHA hash of the original branch tip), and its leaf is closed. Private commits are hidden from the default fnc timeline, so the backup does not clutter the edited history, but it remains browsable with fnc timeline -P or fnc timeline -b backup/histedit/HASH-PREFIX, and the original commits can be recovered from it if needed. Backups can be listed with -l and deleted with -X.

The original branch is not modified until the operation completes, so an unexpected error rolls the repository and work tree back to their starting state.

An edit command, or a merge conflict encountered while replaying any commit, pauses the operation: the applied changes are left in the work tree and fnc histedit returns. After amending the work tree (or resolving the conflict), resume with fnc histedit -c; the paused commit is created from the work tree as it then stands and the remaining commits are replayed. During an edit pause the applied changes are presented as ordinary pending changes, so arbitrary commits may be created with fnc commit before resuming; whatever changes remain in the work tree become the edited commit when the operation is continued. Commits made during a pause must be created with fnc commit, which performs extra bookkeeping. fossil(1) commit behavior is undefined during an fnc histedit operation and may produce inconsistent state. Alternatively, fnc histedit -a aborts the paused operation, discarding the partially replayed line and restoring the work tree to the original branch tip. While an operation is paused, other fnc histedit operations are refused until it is continued or aborted.

The options for fnc histedit are as follows:

, --abort
Abort an interrupted histedit operation, discarding the partially replayed line and restoring the work tree to the original branch tip. Can only be used while an operation is paused.
, --allow-conflict
When continuing, allow the paused commit to be created even if files in the work tree still contain merge conflict markers. Can only be used together with -c.
, --continue
Continue an interrupted histedit operation that was paused by an edit command or a merge conflict. Can only be used while an operation is paused.
, --drop
Drop all commits. This is a quick equivalent to a histedit script that specifies drop for every commit in the edited range, reducing the branch to its base commit. Cannot be used with any other command-line arguments.
, --edit
Edit all commits. This is a quick equivalent to a histedit script that specifies edit for every commit in the edited range, pausing the operation at each commit so the work tree can be amended before continuing. Cannot be used with any other command-line arguments.
, --script path
Use the histedit script at path instead of opening an editor.
, --fold
Fold all commits into a single commit. This is a quick equivalent to a histedit script that specifies fold for every commit except the last, which is pick. Cannot be used with any other command-line arguments.
, --help
Display histedit command help and usage information then exit.
, --list
List backups created by previous histedit operations, showing each backup branch with the date, hash, and log message summary of its tip commit.
, --message
Edit log messages only. This is a quick equivalent to a histedit script that specifies mesg for every commit. Cannot be used with any other command-line arguments.
, --delete [reference]
Delete backups created by previous histedit operations by permanently removing the backup commits from the repository. If a reference argument is given, only the named backup is deleted; otherwise all histedit backups are deleted. The reference argument may be given either as the bare hash or as the full “backup/histedit/hash” reference as printed by -l. No copy is retained, so this cannot be undone.
[-hP] [-C n] [(get|pop) [id]]
(aliases: save, sta)
When run with neither the get nor pop subcommands, fnc stash interactively emits each hunk in the work tree diff to the standard output and prompts the user to stash or keep it. Pressing without entering a character defaults to ‘y’.

Valid answers are as follows:

yes, stash the current hunk (default)
no, do not stash the current hunk
quit; do not stash any hunks and leave the work tree unchanged
yes, stash this hunk and all remaining hunks in the current file
no, do not stash this hunk nor any remaining hunks in the current file
yes, stash this hunk and all remaining hunks in the diff
no, do not stash this hunk nor any remaining hunks in the diff
display help

When all hunks have been selected, fnc opens VISUAL, EDITOR, or /usr/bin/vi, in that order of preference, for the user to compose a stash message. If the message is left empty, a default of "fnc stash HASH-PREFIX", where "HASH-PREFIX" is an abbreviated SHA hash of the current checkout, will be used. At any time prior to the final hunk being selected, the operation can be aborted by answering "q" at the prompt. This will discard any previous selections and leave the work tree unchanged.

Available subcommands for fnc stash are as follows:

[id]
(aliases: apply)
Retrieve the stash changeset corresponding to the specified id and apply it to the current checkout. If id is omitted, the most recent stash entry will be applied.
[id]
Like get, but also remove the changeset from the stash cache.

Options only apply to fnc stash (i.e., neither the get nor pop subcommands) and are as follows:

, --help
Display stash command help and usage information then exit.
, --no-prototype
Do not display the enclosing function or scope in the hunk header. The heuristic used to determine the enclosing scope will produce reliable results for all C-like languages (e.g., C/C++, Java, Python, JavaScript); however, Lisps and non-source code (e.g., make(1), Markdown, reStructuredText) will return meaningless results.
, --context n
Set n context lines to be shown around each hunk such that 0 ≤ n ≤ 64 (default: 5).

[-Chz] [-b branch] [-c commit] [-f glob] [-n n] [-r path] [-T tag] [-t type] [-u user] [path]
(aliases: log, tl)
Display repository history with a chronological log of all commits. If path is specified, only show commits that modified the file(s) at this path. The path may be absolute, relative to the current working directory, or relative to the repository root.

Unless the -r option is used to specify a fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

If invoked in a work tree, the log entry of the commit on which the checkout is based will be prefixed with one of the following annotations:

@ work tree of the checked-out commit contains no local changes
~ work tree of the checked-out commit contains local changes

This command will be executed by default if fnc is invoked without an explicit command.

Options for fnc timeline are as follows:

, --branch branch
Display commits on the specified branch. The expected argument is a glob of the symbolic branch name, with the most recent branch to match being selected. Pattern matching is case-insensitive unless branch has at least one uppercase character, which will make the search case-sensitive. By default, fnc will display all commits irrespective of the branch on which they reside.
, --no-colour
Disable coloured timeline, which is enabled by default on supported terminals. If this option is not used, colour can be toggled with the c timeline view key binding as documented below. User-defined colours are also supported (see ENVIRONMENT for details).
, --commit commit
Start timeline traversal from the specified commit. The expected argument is either a symbolic reference (e.g., branch name, tag), or (a unique abbreviated prefix of) a valid commit SHA1 or SHA3 hash, or an ISO 8601 formatted date. When this option is not used, fnc will begin traversing history from the latest commit. For a complete list of valid arguments this option accepts, see Fossil's Check-in Names.
, --filter glob
Filter timeline by commits containing glob in any of the commit comment, user, or branch fields. Pattern matching is case-insensitive unless glob has at least one uppercase character, which will make the search case-sensitive. Filtering can also be performed at runtime with the F timeline view key binding as documented below.
, --help
Display timeline command help and usage information then exit.
, --limit n
Limit timeline to the latest n commits. By default, fnc will load the entire repository history. Negative values are a no-op.
, --private
Include commits on private branches. By default, commits on private branches (such as the “backup/histedit/*” branches created by fnc histedit) are hidden. As an exception, when the timeline is restricted to a single private branch (either with -b or by opening a private branch's timeline from the branch view), its commits are shown even without this option.
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --tag tag
Only display commits with T cards containing tag. The expected argument is a glob of a commit manifest's T card argument, with the most recent tag to match being selected. Pattern matching is case-insensitive unless tag has at least one uppercase character, which will make the search case-sensitive. By default, fnc will display all commits irrespective of which T cards are attached to the commit manifest.
, --type type
Only display type commits. Valid type values are as follows:
check-in
wiki
ticket
technote
forum post
tag artifact

By default, fnc will load all commits irrespective of type. This is a repeatable flag (e.g., fnc timeline -t e -t t).

, --username user
Only display commits authored by user. The search is case-insensitive by default unless user contains at least one uppercase character, which will make the search case-sensitive.
, --utc
Display dates and timestamps in Coordinated Universal Time (UTC) rather than local time. This can also be configured with the FNC_UTC option (see ENVIRONMENT for details).

Key bindings for fnc timeline are as follows:

Move selection cursor down the timeline.
Move selection cursor up the timeline.
Scroll view to the right N increments in the buffer (default: 1). Comment field contents move left on the screen.
Scroll view to the left N increments in the buffer (default: 1) Comment field contents move right on the screen.
Scroll view to the rightmost position. This corresponds to the end of the longest log message summary line on the page.
Scroll view left to the start of the line.
Scroll timeline view N pages downwards in the buffer (default: 1).
Scroll timeline view N pages upwards in the buffer (default: 1).
Scroll timeline view half of N pages downwards in the buffer (default: 1).
Scroll timeline view half of N pages upwards in the buffer (default: 1).
Open a diff view displaying the changeset of the currently selected commit.
Tag or untag the currently selected commit as the base commit for the next tagged commit to be diffed against. If another commit is already tagged, open a diff view showing the changes between it and the currently selected commit.
Open and populate a branch view with all repository branches. One of the listed branches can be selected to display a new timeline view of its commit history.
Diff local changes on disk in the current work tree against the currently selected commit.
Prompt to enter a search term to filter a new timeline view that displays commits with comment, user, or branch fields that match the entered pattern.
Open a tree view displaying the tree of the repository corresponding to the currently selected commit.
Prompt to enter a search term to begin searching for commits matching the pattern provided. The search term is an extended regular expression that is matched against the comment, author username, branch, and SHA1 or SHA3 hash of each commit in the repository. See re_format(7) for regular expression syntax.
Find the Nth next commit that matches the current search term (default: 1). The search will continue until a match is found, the earliest commit on the timeline is consumed, or ^G or backspace are input.
Find the Nth previous commit that matches the current search term (default: 1). The search will continue until a match is found, the latest commit on the timeline is consumed, or ^G or backspace are input.
Cancel the current search or timeline traversal in progress (i.e., operations executed with / or G/End).
[-bCDhiloPqsWwz] [-r path] [-x n] [artifact1 [artifact2]] [path ...]
(alias: di)
Display the differences between two repository artifacts, or between the local changes in the work tree and a given commit.

If invoked in a work tree with no artifact arguments specified, fnc will show the differences between the local changes in the work tree and the commit on which the current checkout is based. If invoked in a work tree and only artifact1 is specified, fnc will show the differences between the local changes in the work tree and the commit referenced by artifact1. When artifact1 and artifact2 are specified, the differences between these two versions will be displayed. Both artifact arguments must resolve to the same type (i.e., commits or blobs), and are expected to be either: symbolic references (e.g., branch names, tags); a commit or blob SHA1 or SHA3 (unique abbreviated) hash; or an ISO 8601 formatted date. If one or more path arguments are supplied, fnc will filter diffs so that only changes involving the file(s) in the named paths are displayed. Paths may be absolute, relative to the current working directory, or relative to the repository root.

When invoked outside a work tree with the -r option or requesting the differences between blobs, both artifact arguments must be specified; in the latter case, any trailing arguments are invalid and will be ignored.

Unless the -r option is used to specify a fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

Options for fnc diff are as follows:

, --brief
Omit all changes. Show the file index and hash lines only.
, --no-colour
Disable coloured diff output, which is enabled by default on supported terminals. If this option is not used, colour can be toggled with the c diff view key binding as documented below. User-defined colours are also supported (see ENVIRONMENT for details).
, --min-diffstat
Show minimal diffstat instead of the more verbose plot bar histogram.
, --help
Display diff command help and usage information then exit.
, --invert
Invert the differences between artifacts.
, --line-numbers
Display actual file line numbers in diff output.
, --no-curses
Do not initialise curses to render the diff view. Write the diff directly to the standard output.
, --no-prototype
Do not display the enclosing function or scope in the hunk header. The heuristic used to determine the enclosing scope will produce reliable results for all C-like languages (e.g., C/C++, Java, Python, JavaScript); however, Lisps and non-source code (e.g., make(1), Markdown, reStructuredText) will return meaningless results. This option is mutually exclusive with -l and -s, which produce incompatible hunk headers.
, --quiet
Do not output complete content of newly added or deleted files, which are displayed by default. Only show the file index and hash lines.
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --sbs
Display a side-by-side formatted diff. This option is mutually exclusive with -l.
, --wrap
Wrap lines that are longer than the width of the diff view or terminal in fnc diff -o invocations. Can be toggled at runtime with the W key map as documented below.
, --whitespace
Ignore whitespace-only changes.
, --context n
Set n context lines to be shown in the diff such that 0 ≤ n ≤ 64. Illegal values are a no-op (default: 5).
, --utc
Display dates and timestamps in Coordinated Universal Time (UTC) rather than local time. This can also be configured with the FNC_UTC option (see ENVIRONMENT for details).

All the above options (except -h, -o, and -r) can be made persistent as global or repository options via the FNC_DIFF_FLAGS and FNC_DIFF_CONTEXT options (see ENVIRONMENT for details).

Key bindings for fnc diff are as follows:

Scroll view N lines downwards in the buffer (default: 1). Diff output moves upwards on the screen.
Scroll view N lines upwards in the buffer (default: 1). Diff output moves downwards on the screen.
Scroll view to the right N increments in the buffer (default: 1). Diff output moves left on the screen.
Scroll view to the left N increments in the buffer (default: 1). Diff output moves right on the screen.
Scroll view to the rightmost position. This corresponds to the end of the longest line on the page.
Scroll view left to the start of the line.
Move the selection cursor down N lines (default: 1).
Move the selection cursor up N lines (default: 1).
Scroll diff view N pages downwards in the buffer (default: 1).
Scroll diff view N pages upwards in the buffer (default: 1).
Scroll diff view half of N pages downwards in the buffer (default: 1).
Scroll diff view half of N pages upwards in the buffer (default: 1).
If the diff view is derived from the timeline view, move up to the Nth previous (i.e., newer) commit and display its diff. If derived from the blame view, move up to the Nth previous line in the annotated file and display the corresponding diff (default: 1).
If the diff view is derived from the timeline view, move down the timeline to the Nth next (i.e., older) commit and display its diff. If derived from the blame view, move down to the Nth next line in the annotated file and display the corresponding diff (default: 1).
Navigate to the Nth previous file in the diff (default: 1).
Navigate to the Nth next file in the diff (default: 1).
Navigate to the Nth previous hunk in the diff (default: 1).
Navigate to the Nth next hunk in the diff (default: 1).
Decrease the number of context lines in the diff by N (default: 1).
Increase the number of context lines in the diff by N (default: 1).
Toggle the display of diff view (not actual file) line numbers.
Open prompt to enter a line number and navigate to that line in the view.
Toggle brief diff mode by only displaying file index and hash lines.
Open and populate the branch view with all repository branches.
Toggle between minimal and histogram diffstat.
Toggle inversion of diff output.
Toggle file line number formatted diff.
Toggle display in diff hunk headers of which function or scope each change belongs; for example:
Write the currently viewed diff to a patch file on disk in the /tmp directory. The pathname comprises abbreviated hashes of the commits in the diff (e.g., /tmp/fnc-c1024062-f4467173-7IuqgOKaP2.diff) and is drawn to the status line.
Toggle display of a side-by-side formatted diff.
Toggle verbosity of diff output. By default, fnc will display the entire content of newly added or deleted files.
Toggle word wrap. When enabled, lines longer than the width of the diff view are wrapped and continue on the next line. Lines are broken at whitespace if possible, otherwise lines are broken at the last glyph that fits in the view width.
Toggle whether whitespace-only changes are ignored when comparing lines in the diff.
Prompt to enter a search term to begin searching the diff output for lines matching the pattern provided. The search term is an extended regular expression, which is documented in re_format(7).
Find the Nth next line that matches the current search term (default: 1).
Find the Nth previous line that matches the current search term (default: 1).
[-Chz] [-c commit] [-r path] [path]
(aliases: dir, tr)
Display a navigable tree of the repository.

If a path is specified, display the corresponding subtree, otherwise display the root of the tree. The path may be absolute, relative to the current working directory, or relative to the repository root. With no options passed, the tree will reflect the state of the latest commit on trunk.

Unless the -r option is used to specify a fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

Tree nodes are lexicographically ordered and may be postfixed with an identifier corresponding to the mode of the file object on disk as returned by lstat(2):

/ directory
* executable
@ symbolic link

Nodes representing symbolic links are further annotated with the path of the source file (e.g., symlink@ -> targetpath)

Options for fnc tree are as follows:

, --no-colour
Disable coloured output, which is enabled by default on supported terminals. If this option is not used, colour can be toggled with the c tree view key binding as documented below. User-defined colours are also supported (see ENVIRONMENT for details).
, --commit commit
Display the repository tree corresponding to the checkin identified by commit. The expected argument is either a symbolic reference (e.g., branch name, tag), or (a unique abbreviated prefix of) a valid commit SHA1 or SHA3 hash, or an ISO 8601 formatted date. When this option is not used, fnc will display the tree of the latest commit. For a complete list of valid arguments this option accepts, see Fossil's Check-in Names.
, --help
Display tree command help and usage information then exit.
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --utc
Display dates and timestamps in Coordinated Universal Time (UTC) rather than local time. This can also be configured with the FNC_UTC option (see ENVIRONMENT for details).

Key bindings for fnc tree are as follows:

Enter the currently selected directory, or open a blame view of the currently selected file.
Move up to the Nth parent directory (default: 1). This is a no-op when in the root tree.
Move selection cursor N nodes down the tree (default: 1).
Move selection cursor N nodes up the tree (default: 1).
Scroll tree view N pages downwards in the buffer (default: 1).
Scroll tree view N pages upwards in the buffer (default: 1).
Scroll tree view half of N pages downwards in the buffer (default: 1).
Scroll tree view half of N pages upwards in the buffer (default: 1).
Move selection cursor to the first node in the tree.
Move selection cursor to the last node in the tree.
Open and populate the branch view with all repository branches.
Toggle display of the last modified timestamp for each tree entry.
Toggle display of the hash ID for all file nodes in the tree.
Open the timeline view of the currently selected tree entry. This will display the log of all commits involving the tracked file(s) corresponding to the selected tree node.
Prompt to enter a search term to begin searching the tree for entries matching the entered pattern. The search term is an extended regular expression, as documented in re_format(7), and is matched against the path of each tree node.
Find the Nth next tree node that matches the current search pattern (default: 1).
Find the Nth previous tree node that matches the current search pattern (default: 1).
[-ChRz] [-c commit] [-l lineno] [-n n] [-r path] path
(aliases: praise, bl)
Show commit attribution history for each line of the file at the named path, which may be absolute, relative to the current working directory, or relative to the repository root.

Unless the -r option is used to specifiy a fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

Options for fnc blame are as follows:

, --no-colour
Disable coloured output, which is enabled by default on supported terminals. If this option is not used, colour can be toggled with the c blame view key binding as documented below. User-defined colours are also supported (see ENVIRONMENT for details).
, --commit commit
Start annotation of the tracked file from the specified commit. The expected argument is either a symbolic reference (e.g., branch name, tag), or (a unique abbreviated prefix of) a valid commit SHA1 or SHA3 hash, or an ISO 8601 formatted date. When this option is not used, fnc will begin annotation from the latest commit. For a complete list of valid arguments this option accepts, see Fossil's Check-in Names.
, --help
Display blame command help and usage information then exit.
, --line lineno
Open the annotated file and navigate directly to lineno.
, --limit n
Limit depth of blame history to n commits or seconds. The latter is denoted by a postfixed 's' (e.g., 30s). With this option, fnc will traverse either as many commits as specified or as possible in the specified time limit. By default, fnc will traverse the entire historical record of the file, which can be expensive for large files that span many commits. Use this option for a faster, more targeted annotation.
, --reverse
Reverse annotate the file starting from a historical commit and move forward in time so that instead of showing the most recent commit that changed each line, show the first commit that modified each line after the specified commit (requires -c).
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --utc
Display dates and timestamps in Coordinated Universal Time (UTC) rather than local time. This can also be configured with the FNC_UTC option (see ENVIRONMENT for details).

Key bindings for fnc blame are as follows:

Move selection cursor down N lines (default: 1).
Move selection cursor up N lines (default: 1).
Scroll view to the right N increments in the buffer (default: 1). File contents move left on the screen.
Scroll view to the left N increments in the buffer (default: 1). File contents move right on the screen.
Scroll view to the rightmost position. This corresponds to the end of the longest line on the page.
Scroll the view left to the beginning of the line.
Scroll blame view N pages downwards in the buffer (default: 1).
Scroll blame view N pages upwards in the buffer (default: 1).
Scroll blame view half of N pages downwards in the buffer (default: 1).
Scroll blame view half of N pages upwards in the buffer (default: 1).
Move selection cursor to the first line in the file.
Move selection cursor to the last line in the file.
Open a diff view of the commit corresponding to the currently selected line.
Toggle display of file line numbers.
Open prompt to enter a line number and navigate to that line in the file.
Reload the previously blamed version of the file.
Blame the version of the file corresponding to the commit in the currently selected line.
Blame the version of the file corresponding to the parent of the commit in the currently selected line.
Open and populate a branch view with all repository branches.
Open a timeline view that begins traversing the timeline from the commit corresponding to the currently selected annotated line.
Prompt to enter a search term to begin searching the file for tokens matching the entered pattern. The search term is an extended regular expression, as documented in re_format(7).
Find the Nth previous token that matches the current search pattern (default: 1).
Find the Nth next token that matches the current search pattern (default: 1).
[-CchopRz] [-a date] [-b date] [-r path] [-s order] [glob]
(aliases: br, ref)
Display navigable list of repository branches.

If glob is specified, only display branches matching the pattern provided. Pattern matching is case-insensitive unless glob contains at least one uppercase character, which will make the search case-sensitive.

Unless the -r option is used to specify a fossil(1) repository, this command must be invoked from within a work tree; that is, fnc assumes a local checkout is open in or above the current working directory.

Branches are lexicographically ordered by default, and are prefixed with an identifier corresponding to the branch state (i.e., open/closed). The current and private branches are further annotated with a postfixed identifier:

+dev-foo open
-rm-bar closed
+trunk@ current
+wip-baz* private

All branches, irrespective of state or privacy, are displayed by default, but can be filtered based on several characteristics.

Options for fnc branch are as follows:

, --after date
Display only those branches with activity after the specified date, which is expected to be either an ISO 8601 (e.g., 2020-10-10) or unambiguous DD/MM/YYYY or MM/DD/YYYY formatted date.
, --before date
Display only those branches with activity before the specified date, which is expected to be either an ISO 8601 (e.g., 2020-10-10) or unambiguous DD/MM/YYYY or MM/DD/YYYY formatted date.
, --no-colour
Disable coloured output, which is enabled by default on supported terminals. If this option is not used, colour can be toggled with the c branch view key binding as documented below. User-defined colours are also supported (see ENVIRONMENT for details).
, --closed
Display only closed branches.
, --help
Display branch command help and usage information then exit.
, --open
Display only opened branches.
, --no-private
Do not show private branches, which are included in the list of displayed branches by default.
, --reverse
Reverse the order in which branches are displayed.
, --repo path
Use the repository at the specified path. If not specified, assume a fossil(1) work tree is located in or above the current working directory, and use its configured repository path.
, --sort order
Sort branches by order. Valid order values are as follows:
most recently used
open/closed state

Branches are sorted in lexicographical order by default.

, --utc
Display dates and timestamps in Coordinated Universal Time (UTC) rather than local time. This can also be configured with the FNC_UTC option (see ENVIRONMENT for details).

Key bindings for fnc branch are as follows:

Move selection cursor down N branches (default: 1).
Move selection cursor up N branches (default: 1).
Scroll branch view N pages downwards in the buffer (default: 1).
Scroll branch view N pages upwards in the buffer (default: 1).
Scroll branch view half of N pages downwards in the buffer (default: 1).
Scroll branch view half of N pages upwards in the buffer (default: 1).
Move selection cursor to the first branch in the list.
Move selection cursor to the last branch in the list.
Display a timeline view of the currently selected branch.
Toggle display of the date on which the branch last received changes.
Toggle display of the SHA1 or SHA3 hash that identifies each branch, which is the commit hash of the branch tip.
Toggle sort order of currently displayed branches. fnc will cycle from lexicographical order to most recently used and then open/closed state.
Open a tree view of the currently selected branch.
Reload the view with all repository branches, irrespective of which options were used in this fnc branch invocation.
Prompt to enter a search term to begin searching the list for branches matching the entered pattern. The search term is an extended regular expression, as documented in re_format(7).
Find the Nth next branch that matches the current search pattern (default: 1).
Find the Nth previous branch that matches the current search pattern (default: 1).

When the terminal window is ≥ 120 columns wide, fnc will display child views in a vertical split at least 80 columns wide, otherwise a fullscreen will be used. To open child views in a horizontal split instead, configure the following option as either an exported environment variable or with fnc config as documented above.

Open child views in a horizontal or vertical split. Value can be either "horizontal" or "vertical" (default: vertical).

fnc displays all dates and timestamps in local time unless the -z option is specified, in which case all dates and timestamps are in Coordinated Universal Time (UTC). This can be made persistent without using the -z option by setting the following option as either an exported environment variable or with fnc config as documented above.

If set to a non-empty value, display dates and timestamps in Coordinated Universal Time (UTC).

Similarly, diff options can be persistently applied to all diff views whether directly accessed with fnc diff or as a child view of the timeline or blame views by configuring the following options:

String containing any or all of the available short form diff boolean flag options documented above except for the -h and -o options (i.e., bCDilPqsWwz). If mutually exclusive options "l" and "s" are both specified, whichever is last will take precedence; for example, "lqs" will display side-by-side formatted diffs (default: "").
Numeric value as per the above documented -x option (i.e., 0 ≤ n ≤ 64) specifying the number of context lines (default: 5).

Any options passed to fnc diff will override the above settings.

fnc displays coloured output by default in supported terminals. Each colour object identified below can be defined by either exporting environment variables (e.g., export FNC_COLOUR_COMMIT=red), or with fnc config as documented above. At startup, fnc will search for user-defined colours in the following order:

1. repository options repo.fossil
2. environment variables

If none are found, the default colour scheme will be displayed. This enables setting per-project colours to visually distinguish the current repository being viewed, and globally changing the colour scheme for all repositories with no local options configured. Except where documented below, colours supported in fnc are:

"black" "green" "blue" "cyan"
"red" "yellow" "magenta" "default"

Where "default" is the current foreground (i.e., text) colour in the terminal. User-definable colour objects displayed in various fnc views are as follows:

The commit hash ID field displayed in the timeline, diff, tree, and blame views (default: "green").
The username field displayed in the timeline and diff views (default: "cyan").
The date field displayed in the timeline and diff views (default: "yellow").
Removed lines displayed in the diff view (default: "magenta").
Added lines displayed in the diff view (default: "cyan").
Hunk header lines (e.g., @@ -732,34 +747,40 @@) displayed in the diff view (default: "yellow").
Metadata displayed in the diff view (default: "green").
The tag field displayed in the diff view (default: "magenta").
Changed (i.e., not added or removed) lines in the diff view when displaying side-by-side diffs (default: "red").
Directory entries displayed in the tree view (default: "cyan").
Executable file entries displayed in the tree view (default: "green").
Symbolic link entries displayed in the tree view (default: "magenta").
Open branches displayed in the branch view (default: "cyan").
Closed branches displayed in the branch view (default: "magenta").
The branch corresponding to the current checkout displayed in the branch view (default: "green").
Private branches displayed in the branch view (default: "yellow").
Selected line highlight in the diff view. Value can be one of or . The former will invert the foreground colour of the selected line, while the latter will use a monochromatic highlight (default: "auto").
Search term highlight in the blame and diff views (default: "yellow").

To clear environment variables, invoke the shell builtin unset; for example, "unset FNC_DIFF_CONTEXT". As documented above, local options can be unset with fnc config -u option.

The fnc utility exits 0 on success, and >0 if an error occurs.

fossil(1), sqlite3(1), ascii(7), re_format(7)

Mark Jamsek <mark@jamsek.com>

fnc displays best with a Unicode character set. If fnc is invoked in an environment with UTF-8 character encoding selected, it assumes the Unicode character set is supported; otherwise, fnc defaults to the ASCII character set. Some fonts may fail to render Unicode characters in the help view if they lack the requisite glyphs. If your font does not support these Unicode characters, invoke fnc with "LC_CTYPE=C fnc" to select the ASCII character set and encoding.

OpenBSD 7.9 July 2, 2026 FNC(1)