.\"
.\" Copyright (c) 2021 Mark Jamsek <mark@jamsek.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt FNC 1
.Os
.Sh NAME
.Nm fnc
.Nd Read-only ncurses-based Fossil repository browser
.Sh SYNOPSIS
.Nm
.Op Ar command
.Op Fl h | -help
.Nm
.Op Fl h | -help
.Op Fl v | -version
.Nm
.Cm config
.Op Fl hu
.Op Fl -ls
.Op Fl R Ar path
.Op Ar setting Op Ar value
.Nm
.Cm timeline
.Op Fl Cz
.Op Fl b Ar branch
.Op Fl c Ar commit
.Op Fl f Ar glob
.Op Fl n Ar number
.Op Fl R Ar path
.Op Fl T Ar tag
.Op Fl t Ar type
.Op Fl u Ar user
.Op Ar path
.Nm
.Cm diff
.Op Fl Ciw
.Op Fl R Ar path
.Op Fl x Ar number
.Op Ar artifact1 Op Ar artifact2
.Op Ar path ...
.Nm
.Cm tree
.Op Fl C
.Op Fl c Ar commit
.Op Fl R Ar path
.Op Ar path
.Nm
.Cm blame
.Op Fl C
.Op Fl c Ar commit Op Fl r
.Op Fl n Ar number
.Op Fl R Ar path
.Ar path
.Nm
.Cm branch
.Op Fl Ccopr
.Op Fl a Ar date | Fl b Ar date
.Op Fl R Ar path
.Op Fl s Ar order
.Op Ar glob
.Nm
.Op Ar path
.Sh DESCRIPTION
.Nm
is an interactive read-only browser for
.Xr fossil 1
repositories,
and supports multiple views to display repository data:
.Bl -tag -width Ds
.It Timeline view
Display commits from the repository's history in chronologically
descending order.
.Br
If no
.Ar command
or
.Ar arg
are specified, or just a
.Ar path
is passed,
.Nm
will default to displaying this view.
.It Diff view
Display changes introduced in the specified commit, or between two repository
artifacts.
.It Tree view
Display navigable tree reflecting the repository state as at the specified
commit.
.It Blame view
Display and annotate each line in the given file with the hyperlinked historical
version that last modified the line.
.It Branch view
Display navigable list of all repository branches.
.El
.Pp
.Nm
provides both global and command-specific options and in-app key
bindings. Global options are as follows:
.Bl -tag -width 6v
.It Fl h , -help
Display program help and usage information then exit.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Nm
session. See command specific options for details.
.It Fl v , -version
Display program version then exit.
.El
.Pp
Note that any global options preceding a command name will be
interpreted as the command-specific variant if such an option exists.
.Pp
Global key bindings are as follows:
.Bl -tag -width Ds
.It Cm H, ?, F1
Display in-app help.
.It Cm Tab
Switch focus between open views.
.It Cm f
Toggle the active view between fullscreen and splitscreen mode. Note
that
.Nm
will open nested views in splitscreen mode if the terminal window is
equal to or greater than 110 columns wide.
.It Cm Q
Immediatey quit
.Nm .
.It Cm q
Quit the active view.
.El
.Pp
Commands available to
.Nm
are as follows:
.Bl -tag -width 4v
.Tg conf
.It Cm config Oo Fl h | -help Oc Oo Fl -ls Oc Oo Fl R | -repo Ar path Oc \
Oo Ar setting Op Ar value | Fl -unset Oc
.Dl Pq aliases: Cm conf , Cm cfg , Cm settings , Cm set
Retrieve the current, or set a new,
.Ar value
for
.Ar setting
in the local repository. When specified,
.Ar value
will become the new value for
.Ar setting ,
otherwise
.Nm
will display the current value of
.Ar setting .
With no arguments,
.Cm fnc config
will display a list of all configurable settings. Alternatively, see
.Sx ENVIRONMENT
for a detailed list of available settings
used in the display or processing of data. When no value is found for a given
setting in the local repository, environment variables will be searched.
If still not found, default values will be used. Unless the
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
Options for
.Cm fnc config
are as follows:
.Bl -tag -width Ds
.It Fl h , -help
Display config command help and usage information then exit.
.It Fl -ls
List all currently defined settings.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc config
invocation.
.It Fl u , -unset
Clear the specified
.Ar setting.
.El
.Tg log
.It Cm timeline Oo Fl C | -no-colour Oc Oo Fl T | -tag Ar tag Oc \
Oo Fl b | -branch Ar branch Oc Oo Fl c | -commit Ar commit Oc \
Oo Fl f | -filter Ar glob Oc Oo Fl h | -help Oc Oo Fl n | -limit Ar n Oc \
Oo Fl R | -repo Ar path Oc Oo Fl t | -type Ar type Oc \
Oo Fl u | -username Ar user Oc Oo Fl z | -utc Oc \
Op Ar path
.Dl Pq aliases: Cm log , Cm tl , Cm time , Cm ti
Display commit history of a repository. If
.Ar path
is specified, only commits that modified the file(s) at this path will populate
the timeline. The
.Ar path
may be absolute, relative to the current working directory, or relative to the
repository root. Unless the
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
.Pp
If no command is explicitly specified, this command will be executed by
default.
.Pp
Options for
.Cm fnc timeline
are as follows:
.Bl -tag -width Ds
.It Fl b , -branch Ar branch
Display commits that are members of the specified
.Ar branch .
The expected argument is the symbolic name of a branch. By default,
.Nm
will display all commits irrespective of the branch on which they
reside.
.It Fl C , -no-colour
Disable colourised timeline, which is enabled by default on supported
terminals. If this option is not used, colour can be toggled with the
.Sy c
timeline view key binding as documented below.
User-defined colours are also supported, see
.Sx ENVIRONMENT
for details.
.It Fl c , -commit Ar commit
Open the timeline from the check-in identified by
.Ar commit .
The expected argument is either the name of a branch, which will resolve
to the latest commit on the given branch, or (a unique abbreviated
prefix of) a valid commit UUID SHA1 or SHA3 hash. When this option is
not supplied,
.Nm
will open the timeline to the latest leaf on the repository tree. For a
complete list of valid arguments this option accepts, see
.Lk https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki \
"Fossil's Check-in Names".
.It Fl f , -filter Ar glob
Filter timeline by commits containing
.Ar glob
in any of the commit comment, user, or branch fields. Pattern matching depends
on the
.Xr sqlite3 1
.B
LIKE
operator, which only folds case for the ASCII character set. Filtering can also
be performed in-session with the
.Sy F
timeline view key binding as documented below.
.It Fl h , -help
Display timeline command help and usage information then exit.
.It Fl n , -limit Ar n
Limit timeline to the
latest
.Ar n
commits.
By default,
.Nm
will load the entire history of the repository's local checkout.
Negative values are a no-op.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc timeline
invocation. When this option is used, the checkout-related Fossil special
tags
.Qq current ,
.Qq prev ,
and
.Qq next
are invalid arguments to the
.Sy --commit
option. When
.Sy --commit
is not specified,
.Nm
will default to populating the timeline from the latest commit.
.It Fl T , -tag Ar tag
Only display commits with T cards containing
.Ar tag .
By default,
.Nm
will indiscriminately display all commits irrespective of which T cards
are attached to the commit manifest.
.It Fl t , -type Ar type
Only display
.Ar type
commits. Valid
.Ar type
values are as follows:
.Bl -column -offset 2s YXZ description
.Sy ci Ta check-in
.Sy w Ta wiki
.Sy t Ta ticket
.Sy e Ta technote
.Sy f Ta forum post
.Sy g Ta tag artifact
.El
.Pp
By default, when this option is not supplied,
.Nm
will indiscriminately load all commits irrespective of
.Ar type .
Note that this is a repeatable flag (e.g.,
.Nm
.Cm timeline
.Cm -t e -t t Ns
).
.It Fl u , -username Ar user
Only display commits authored by
.Ar user .
.It Fl z , -utc
Use Coordinated Universal Time (UTC) rather than local time when
displaying commit dates and timestamps.
.El
.Pp
Key bindings for
.Cm fnc timeline
are as follows:
.Bl -tag -width Ds
.It Cm Arrow-down, j, >, \&.
Move selection cursor down the timeline.
.It Cm Arrow-up, k, <, \&,
Move selection cursor up the timeline.
.It Cm C-f, Page-down
Move selection cursor one page down the timeline.
.It Cm C-b, Page-up
Move selection cursor one page up the timeline.
.It Cm G, End
Move selection cursor to the last commit on the timeline (i.e., oldest commit
in the repository).
.It Cm gg, Home
Move selection cursor to the first commit on the timeline (i.e., newest commit
in the repository).
.It Cm Enter, Space
Open a
.Cm diff
view displaying the changeset of the currently selected commit.
.It Cm b
Open and populate branch view with all repository branches.
.It Cm c
Toggle colourised timeline. On supported terminals,
.Nm
will default to displaying the timeline in colour.
.It Cm F
Prompt to enter a search term to filter a new timeline view by commits with
comment, user, or branch fields that match the entered pattern. If no commits
match, a message is displayed on screen.
.It Cm t
Display the tree of the repository corresponding to the currently selected
commit.
.It Cm /
Prompt to enter a search term to begin searching for commits matching
the pattern provided. The search term is an extended regular expression,
which is cross-referenced against a commit's comment, the username of
its author, branch, and UUID SHA1 or SHA3 hash. See
.Xr re_format 7
for regular expression syntax.
.It Cm n
Find the next commit that matches the current search term. The search
will continue until either a match is found or the earliest commit on
the timeline is consumed.
.It Cm N
Find the previous commit that matches the current search term. The
search will continue until either a match is found or the latest commit
on the timeline is consumed.
.El
.Tg di
.It Cm diff Oo Fl C | -no-colour Oc Oo Fl h | -help Oc Oo Fl i | -invert Oc \
Oo Fl R | -repo Ar path Oc Oo Fl w | -whitespace Oc Oo Fl x | -context Ar n Oc \
Oo Ar artifact1 Oo Ar artifact2 Oc Oc Op Ar path ...
.Dl Pq alias: Cm di
Display the differences between two repository artifacts, or between the local
changes on disk and a given commit. If neither
.Ar artifact1
nor
.Ar artifact2
are specified,
.Nm
will diff the local changes on disk against the version on which the current
checkout is based. If only
.Ar artifact1
is specified,
.Nm
will diff the current checkout, including any local changes on disk, against
this version. When both arguments are specified, the changes between these two
versions will be displayed. If supplied,
.Nm
will filter diffs between commits by
.Ar path
so that only changes involving the file(s) identified are displayed. Paths may
be absolute, relative to the current working directory, or relative to the
repository root. Both
.Ar artifact1
and
.Ar artifact2
must be of the same type, which is expected to be either a symbolic check-in
name, tag, (unique abbreviated prefix of) a commit or blob artifact UUID SHA1
or SHA3 hash, or an ISO 8601 formatted date. Both artifact arguments must be
supplied when diffing blobs; any following non-option arguments are invalid
and will be ignored. Unless the
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
.Pp
Options for
.Cm fnc diff
are as follows:
.Bl -tag -width Ds
.It Fl C , -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
.Sy c
diff view key binding as documented below.
User-defined colours are also supported, see
.Sx ENVIRONMENT
for details.
.It Fl h , -help
Display diff command help and usage information then exit.
.It Fl i , -invert
Invert the difference between artifacts when displaying the diff.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc diff
invocation. When this option is used, both
.Ar artifact1
and
.Ar artifact2
are required, and the checkout-related Fossil special tags
.Qq current ,
.Qq prev ,
and
.Qq next
are invalid
.Sy artifact
operands.
.It Fl w , -whitespace
Ignore whitespace-only changes when displaying the diff.
.It Fl x , -context Ar n
Set
.Ar n
context lines to be shown in the diff. By default, 5 context lines are
shown. Negative values are a no-op.
.El
.Pp
Key bindings for
.Cm fnc diff
are as follows:
.Bl -tag -width Ds
.It Cm Arrow-down, j
Scroll down one line of diff output.
.It Cm Arrow-up, k
Scroll up one line of diff output.
.It Cm C-f, Page-down, Space
Scroll down one page of diff output.
.It Cm C-b, Page-up
Scroll up one page of diff output.
.It Cm G, End
Scroll to the end of the view (i.e., last line of diff output).
.It Cm gg, Home
Scroll to the top of the view (i.e., first line of diff output).
.It Cm C-k, K, <, \&,
Move up the
.Cm timeline
to the previous (i.e., newer) commit and display its diff. (Only available
if the diff was accessed from the timeline.)
.It Cm C-j, J, >, \&.
Move down the
.Cm timeline
to the next (i.e., older) commit and display its diff. (Only available
if the diff was accessed from the timeline.)
.It Cm \&-, \&_
Decrease the number of context lines shown in diff output.
.It Cm \&=, \&+
Increase the number of context lines shown in diff output.
.It Cm b
Open and populate branch view with all repository branches.
.It Cm c
Toggle coloured diff output. On supported terminals,
.Nm
will default to displaying changes and diff metadata in colour.
.It Cm i
Toggle inversion of diff output.
.It Cm v
Toggle verbosity of diff output. By default,
.Nm
will display the entire content of newly added or deleted files.
.It Cm w
Toggle whether whitespace-only changes are ignored when comparing lines in the
diff.
.It Cm /
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
.Xr re_format 7 .
.It Cm n
Find the next line that matches the current search term.
.It Cm N
Find the previous line that matches the current search term.
.El
.Tg dir
.It Cm tree Oo Fl C | -no-colour Oc Oo Fl c | -commit Ar commit Oc \
Oo Fl h | -help Oc Oo Fl R | -repo Ar path Oc Op Ar path
.Dl Pq aliases: Cm dir , Cm tr
Display navigable, hierarchical tree of a repository. If a
.Ar path
is specified, display tree nodes of this path. The
.Ar 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
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
.Pp
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
.Xr lstat 2 :
.Bl -column -offset Ds YXZ description
.It / Ta directory
.It * Ta executable
.It @ Ta symbolic link
.El
.Pp
Nodes representing symbolic links are also annotated with the path of the
source file.
.Pp
Options for
.Cm fnc tree
are as follows:
.Bl -tag -width Ds
.It Fl C , -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
.Sy c
tree view key binding as documented below.
User-defined colours are also supported, see
.Sx ENVIRONMENT
for details.
.It Fl c , -commit Ar commit
The displayed tree will reflect the state of the repository as at the check-in
identified by
.Ar commit .
The expected argument is either the name of a branch, which will resolve
to the latest commit on the given branch, or (a unique abbreviated
prefix of) a valid commit UUID SHA1 or SHA3 hash. For a complete list of valid
arguments this option accepts, see
.Lk https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki \
"Fossil's Check-in Names".
.It Fl h , -help
Display tree command help and usage information then exit.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc tree
invocation. When this option is used, the checkout-related Fossil special
tags
.Qq current ,
.Qq prev ,
and
.Qq next
are invalid arguments to the
.Sy --commit
option.
.El
.Pp
Key bindings for
.Cm fnc tree
are as follows:
.Bl -tag -width Ds
.It Cm Enter, Arrow-right, l
Enter the currently selected directory, or open a
.Cm blame
view of the currently selected file.
.It Cm Backspace, Arrow-left, h
Move up a level to the parent directory. This is a no-op when in the root tree.
.It Cm Arrow-down, j
Move selection cursor one node down the tree.
.It Cm Arrow-up, k
Move selection cursor one node up the tree.
.It Cm Page-down, C-f
Move selection cursor one page down the tree.
.It Cm Page-up, C-b
Move selection cursor one page up the tree.
.It Cm Home, gg
Move selection cursor to the first node in the tree.
.It Cm End, G
Move selection cursor to the last node in the tree.
.It Cm b
Open and populate branch view with all repository branches.
.It Cm c
Toggle coloured output. On supported terminals,
.Nm
will default to displaying the tree in colour.
.It Cm t
Open
.Cm timeline
view for the currently selected tree node. This will display the timeline of
all commits that involve the versioned file(s) corresponding to the selected
node.
.It Cm i
Show SHA hash UUID for all file nodes displayed in the tree.
.It Cm /
Prompt to enter a search term to begin searching the tree for nodes matching the
entered pattern. The search term is an extended regular expression, as
documented in
.Xr re_format 7 ,
and is matched against the path of each tree node.
.It Cm n
Find the next tree node that matches the current search pattern.
.It Cm N
Find the previous tree node that matches the current search pattern.
.El
.Tg praise
.It Cm blame Oo Fl C | -no-colour Oc \
Oo Fl c | -commit Ar commit Oo Fl r | -reverse Oc Oc Oo Fl h | -help Oc \
Oo Fl n | -limit Ar n Oc Oo Fl R | -repo Ar path Oc Ar path
.Dl Pq aliases: Cm praise , Cm annotate , Cm bl , Cm pr , Cm an
Show commit attribution history for each line of the file at the specified
.Ar path ,
which may be absolute, relative to the current working directory, or relative to
the repository root. Unless the
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
.Pp
Options for
.Cm fnc blame
are as follows:
.Bl -tag -width Ds
.It Fl C , -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
.Sy c
blame view key binding as documented below.
User-defined colours are also supported, see
.Sx ENVIRONMENT
for details.
.It Fl c , -commit Ar commit
Start blame of file at the specified
.Ar path
from the check-in identified by
.Ar commit .
The expected argument is either the name of a branch, which will resolve
to the latest commit on the given branch, or (a unique abbreviated
prefix of) a valid commit UUID SHA1 or SHA3 hash. When this option is
not supplied,
.Nm
will blame the version of the file from the current checkout. For a complete
list of valid arguments this option accepts, see
.Lk https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki \
"Fossil's Check-in Names".
.It Fl h , -help
Display blame command help and usage information then exit.
.It Fl n , -limit Ar n
Limit depth of blame history to
.Ar n
commits or seconds. The latter is denoted by a postfixed 's' (e.g., 30s).
With this option,
.Nm
will traverse either as many commits as specified, or as possible in the
specified time limit. By default,
.Nm
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.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc blame
invocation. When this option is used, the checkout-related Fossil special
tags
.Qq current ,
.Qq prev ,
and
.Qq next
are invalid arguments to the
.Sy --commit
option. When
.Sy --commit
is not specified,
.Nm
will default to blaming the version of the file found in the latest commit.
.It Fl r , -reverse
Reverse annotate the file starting from a historical commit and move forward in
time. That is, rather than show the most recent change to each line, show the
first time each line was modified by a subsequent commit after the specified
.Ar commit .
(Requires \fB\-c\fP|\fB\-\-commit\fP.)
.El
.Pp
Key bindings for
.Cm fnc blame
are as follows:
.Bl -tag -width Ds
.It Cm Arrow-down, j
Move selection cursor down one line.
.It Cm Arrow-up, k
Move selection cursor up one line.
.It Cm Page-down, C-f
Move selection cursor down one page.
.It Cm Page-up, C-b
Move selection cursor up one page.
.It Cm Home, gg
Move selection cursor to the first line in the file.
.It Cm End, G
Move selection cursor to the last line in the file.
.It Cm Enter
Display the
.Cm diff
of the commit corresponding to the currently selected line.
.It Cm b
Blame the version of the file corresponding to the commit in the currently
selected line.
.It Cm p
Blame the version of the file corresponding to the parent of the commit in
the currently selected line.
.It Cm B, Backspace
Reload the previous blamed version of the file.
.It Cm T
Open and populate branch view with all repository branches.
.It Cm c
Toggle coloured output. On supported terminals,
.Nm
will default to displaying the blamed file in colour.
.It Cm /
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
.Xr re_format 7 .
.It Cm n
Find the next token that matches the current search pattern.
.It Cm N
Find the previous token that matches the current search pattern.
.El
.Tg tag
.It Cm branch Oo Fl C | -no-colour Oc Oo Fl -after Ar date | \
Fl -before Ar date Oc Oo Fl h | -help Oc Oo Fl -open | Fl -closed Oc \
Oo Fl p | -no-private Oc Oo Fl R | -repo Ar path Oc Oo Fl r | -reverse Oc \
Oo Fl s | -sort Ar order Oc Op Ar glob
.Dl Pq aliases: Cm tag , Cm br
Display navigable list of repository branches. If
.Ar glob ,
is specified, only display branches matching the pattern provided. Pattern
matching comparisons depend on the
.Xr sqlite3 1
.B
LIKE
operator, which only folds case for the ASCII character set. Unless the
.Sy --repo
option is used, this command must be executed from within the repository
hierarchy; that is,
.Nm
assumes a local checkout is open in or above the current working directory.
.Pp
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 additionally annotated with a postfixed
identifier:
.Bl -column -offset Ds ABCDEFGHIJ description
.It +dev-foo Ta open
.It -rm-bar Ta closed
.It +trunk@ Ta current
.It +wip-baz* Ta private
.El
.Pp
All branches, irrespective of state or privacy, are displayed by default, but
can be filtered based on several characteristics.
.Pp
Options for
.Cm fnc branch
are as follows:
.Bl -tag -width Ds
.It Fl a , -after Ar date
Display only those branches with activity after the specified
.Ar date ,
which is expected to be either an ISO8601
.Po e.g.,
.Sy 2020-10-10
.Pc
or unambiguous
.Sy DD/MM/YYYY
or
.Sy MM/DD/YYYY
formatted date.
.It Fl b , -before Ar date
Display only those branches with activity before the specified
.Ar date ,
which is expected to be either an ISO8601
.Po e.g.,
.Sy 2020-10-10
.Pc
or unambiguous
.Sy DD/MM/YYYY
or
.Sy MM/DD/YYYY
formatted date.
.It Fl C , -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
.Sy c
branch view key binding as documented below.
User-defined colours are also supported, see
.Sx ENVIRONMENT
for details.
.It Fl c , -close
Display only closed branches.
.It Fl h , -help
Display branch command help and usage information then exit.
.It Fl o , -open
Display only opened branches.
.It Fl p , -no-private
Do not show private branches, which are included in the list of displayed
branches by default.
.It Fl R , -repo Ar path
Use the
.Xr fossil 1
repository database at the specified
.Ar path
for the current
.Cm fnc branch
invocation.
.It Fl r , -reverse
Reverse the order in which branches are displayed.
.It Fl s , -sort Ar order
Sort branches by
.Ar order .
Valid
.Ar order
values are as follows:
.Bl -column -offset 2s YXZ description
.Sy mru Ta most recently used
.Sy state Ta open/closed state
.El
.Pp
Branches are sorted in lexicographical order by default.
.El
.Pp
Key bindings for
.Cm fnc branch
are as follows:
.Bl -tag -width Ds
.It Cm Arrow-down, j
Move selection cursor down one branch.
.It Cm Arrow-up, k
Move selection cursor up one branch.
.It Cm Page-down, C-f
Move selection cursor down one page.
.It Cm Page-up, C-b
Move selection cursor up one page.
.It Cm Home, gg
Move selection cursor to the first branch in the list.
.It Cm End, G
Move selection cursor to the last branch in the list.
.It Cm Enter, Space
Display the
.Cm timeline
of the currently selected branch.
.It Cm c
Toggle coloured output. On supported terminals,
.Nm
will default to displaying the branch list in colour.
.It Cm d
Toggle display of the date on which the branch last received changes.
.It Cm i
Toggle display of the SHA{1,3} hash that identifies branch, which is the hash
of the commit on the tip of said branch.
.It Cm t
Open the
.Cm tree
view of the currently selected branch.
.It Cm R, C-l
Reload the view with all repository branches, irrespective of which options
were used in this
.Cm fnc branch
invocation.
.It Cm /
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
.Xr re_format 7 .
.It Cm n
Find the next branch that matches the current search pattern.
.It Cm N
Find the previous branch that matches the current search pattern.
.El
.El
.Sh ENVIRONMENT
.Nm
displays coloured output by default in supported terminals. Each colour object
identified below can be defined by either exporting environment variables
.Po e.g.,
.Cm export FNC_COLOUR_COMMIT=red
.Pc ,
or with
.Nm Cm config
as documented above. At startup,
.Nm
will search for user-defined colours in the following order:
.Bl -column " environment variables " description -offset Ds
.It 1. repository settings Ta Pa repo.fossil
.It 3. environment variables Ta Sy shell
.El
.Pp
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 settings configured. Colours supported in
.Nm
are:
.Bl -column "black" "yellow" "magenta" "default" -offset indent-two
.It Qq black Ta Qq green Ta Qq blue Ta Qq cyan
.It Qq red Ta Qq yellow Ta Qq magenta Ta Qq default
.El
.Pp
Where
.Qq default
is the current foreground (i.e., text) colour in the terminal.
User-definable colour objects displayed in various
.Nm
views are as follows:
.Bl -tag -width FNC_COLOUR_BRANCH_PRIVATE
.It Ev FNC_COLOUR_COMMIT
The commit hash ID field displayed in the timeline, diff, tree, and blame views.
If not defined, the default value is
.Qq green .
.It Ev FNC_COLOUR_USER
The username field displayed in the timeline and diff views. If not defined,
the default value is
.Qq cyan .
.It Ev FNC_COLOUR_DATE
The date field displayed in the timeline and diff views. If not defined, the
default value is
.Qq yellow .
.It Ev FNC_COLOUR_DIFF_MINUS
Removed lines displayed in the diff view. If not defined, the default value is
.Qq magenta .
.It Ev FNC_COLOUR_DIFF_PLUS
Added lines displayed in the diff view. If not defined, the default value is
.Qq cyan .
.It Ev FNC_COLOUR_DIFF_CHUNK
Chunk header lines
.Po e.g.,
.Ql @@ -732,34 +747,40 @@
.Pc
displayed in the diff view. If not defined, the default value is
.Qq yellow .
.It Ev FNC_COLOUR_DIFF_META
Metadata displayed in the diff view. If not defined, the default value is
.Qq green .
.It Ev FNC_COLOUR_DIFF_TAGS
The tag field displayed in the diff view. If not defined, the default value is
.Qq magenta .
.It Ev FNC_COLOUR_TREE_DIR
Directory entries displayed in the tree view. If not defined, the default value
is
.Qq cyan .
.It Ev FNC_COLOUR_TREE_EXEC
Executable file entries displayed in the tree view. If not defined, the default
value is
.Qq green .
.It Ev FNC_COLOUR_TREE_LINK
Symbolic link entries displayed in the tree view. If not defined, the default
value is
.Qq magenta .
.It Ev FNC_COLOUR_BRANCH_OPEN
Open branches displayed in the branch view. If not defined, the default value
is
.Qq cyan .
.It Ev FNC_COLOUR_BRANCH_CLOSED
Closed branches displayed in the branch view. If not defined, the default value
is
.Qq magenta .
.It Ev FNC_COLOUR_BRANCH_CURRENT
The branch corresponding to the current checkout displayed in the branch view.
If not defined, the default value is
.Qq green .
.It Ev FNC_COLOUR_BRANCH_PRIVATE
Private branches displayed in the branch view. If not defined, the default
value is
.Qq yellow .
.El
.Pp
To clear environment variables, issue
.Cm unset Ar ENVIRONMENT_VARIABLE
in the shell.
.Sh EXIT STATUS
.Ex -std fnc
.Sh SEE ALSO
.Xr fossil 1 ,
.Xr re_format 7
.Xr sqlite3 1
.Sh AUTHOR
.An Mark Jamsek Aq Mt mark@jamsek.com