fnc: interactive text-based user interface for Fossil

fnc uses ncurses and libfossil to create a fossil ui experience for navigating fossil repositories in the terminal. fnc also supports interactive stash (cf. git stash -p) for parsing local changes at the hunk level to prepare atomic commits, and editing of commit history (cf. git rebase -i) to fold, drop, and edit local commits.

Tested and confirmed to run on the following amd64 systems (additional platforms noted inline):

1. OpenBSD 6.8 through 7.4-{current,release}
2. macOS Catalina 10.15.7, Big Sur 11.5.2, and Ventura 13.6.1
3. Linux Mint 20.2 (32- and 64-bit ARM)
4. Ubuntu 18.04, 21.04, 21.10, and 22.04 running Linux 5.1{1,3} (32-bit ARM)
5. Debian GNU/Linux 8, 9, and 10
6. CentOS 6.5 (32-bit)
7. Alpine Linux 3.19_rc1

Alpha development notwithstanding, the timeline, diff, tree, blame, branch, config, and stash commands are relatively stable; however, there is no commitment to refrain from breaking changes.

Install

• OpenBSD
  • doas pkg_add fnc
• macOS
  • sudo port install fnc
• FreeBSD
  • package: pkg install fnc
  • port: cd /usr/ports/devel/fnc/ && make install clean
• NixOS
  • nix-env -iA nixos.fnc
• Alpine Linux
  • apk add fnc
    n.b. Ensure community repository is enabled (see https://wiki.alpinelinux.org/wiki/Repositories#Community)

Check repology to find if a package is provided for your operating system. If no package exists, download and install the binary on your path.

Build

1. clone the repository¹
   • fossil clone https://fnc.sh
2. move into the work tree
   • cd fnc
3. build fnc²
   • make³
4. install the fnc binary⁴
   • doas make install
5. run it in the fnc work tree
   • fnc

This installs the fnc executable and man page into /usr/local/bin and /usr/local/share/man/man1, respectively. Alternatively, cryptographically signed tarballs of the source code and binaries for some of the abovementioned platforms are available to download.

Doc

Commands available in fnc:

1. stash
   • interactively select hunks to stash from the diff of local changes on disk
2. histedit
   • edit commit history by dropping, editing, or folding commits
3. timeline
   • hyperlinked chronological commit history of the repository
4. diff
   • diff of all changes between commits or blobs
5. blame
   • annotated file displaying commit attribution history of each line
6. tree
   • navigable file hierarchy of the repository tree
7. branch
   • hyperlinked list of all public and private branches
8. config
   • configure or view fnc settings

See fnc -h for a quick reference and the fnc(1) manual page for more comprehensive documentation. Runtime help can also be accessed with the ?, F1, or H key binding. There are screenshots that illustrate various views, and the following video briefly demonstrates some of the key bindings in use.

Why

fnc is heavily inspired by tog, which I missed when I left Got behind and started using Fossil. The objective is to provide an alternative to fossil ui without leaving the terminal.

Problems & Patches

Please submit bug reports via email to the mailing list. All reports should include a bug reproduction recipe in the form of either: (1) a list of steps from fossil init to create a new repository to the fnc command that triggers the unexpected behaviour; or (2) a shell script containing all necessary ingredients to reproduce the problem. Regression tests in regress/ provide exemplar reference implementations.

Patches are thoughtfully considered and can be sent to the mailing list. While patches produced with diff(1) -up or fnc (i.e., fnc diff -o or the diff view's p keymap) are preferred, any unified diffs (e.g., fossil diff) are welcome. Please ensure code conforms to the C99 standard and OpenBSD KNF style(9). Any user-visible change (i.e., code that impacts user interfaces) should also update documentation if affected by the change.

Trivia

fnc [fɪŋk]
noun (n.)

1. an interactive ncurses browser for Fossil repositories
   verb (v.)
   
2. to inform
   etymology
   From the German word Fink, meaning "finch", a type of bird.

---

1. ^{^} creates the fnc.fossil repository file and fnc work tree in $PWD
2. ^{^} creates the fnc binary in $PWD/src
3. ^{^} if using clang(1), make ccdb generates a compile_commands.json style compilation database for your language server
4. ^{^} requires privileges