git-fi

A git plugin that maintains a temporary integration branch named fi. Merge multiple in-progress feature branches together to detect conflicts early and test features in collaboration — before they land on main.

Documentation & install | Specification

This README is for working on git-fi itself. To install and use it, see the documentation site.

Local development

Requires Node.js >= 18 and git >= 2.50.0.

git clone https://github.com/gettyimages/git-fi.git
cd git-fi
npm install                 # dev dependencies (tsx, typescript)

Day-to-day, git-fi runs straight from source — no global install needed:

npm start -- --help         # run src/ directly via tsx
npm run build               # compile TypeScript to dist/
npm test                    # build, then run the integration suite

npm test is the primary feedback loop: it drives the compiled binary against throwaway git repositories (a bare origin plus a working clone), exercising real git fetch/merge/push behavior end-to-end.

To try your local build as the git fi subcommand in another repository, install the checkout globally:

npm install -g .            # puts your build on PATH as `git fi`

The published package — npm install -g @gettyimages/git-fi, documented on the docs site — is the official install for end users. Reach for it here mainly to test the distribution itself; local development runs from source.

The implementation follows SPEC.md, which defines every requirement with a unique ID and includes mermaid diagrams for the major flows.

Project Structure

SPEC.md        Behavioral specification
STATUS.md      Requirement coverage
src/           TypeScript implementation
test/          Integration suite (Node test runner)
docs/          Docsify documentation site
scripts/       Build-time generators
man/           Generated man page (git-fi.1)
completions/   Generated bash + zsh completions

The man page and shell completions are generated by scripts/gen-docs.ts, which draws the flag list from src/help.ts — the single source of truth for git-fi's flags. The completion logic itself lives in real shell files under scripts/completion/ (*.tmpl); the generator injects the flag list and stamps a banner. npm run build regenerates the outputs (via npm run gen:docs); those under man/ and completions/ are committed, so edit src/help.ts (flags) or scripts/completion/*.tmpl (completion logic) and rebuild rather than editing the generated files by hand.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT — Copyright (c) 2017-2026 Getty Images.