Skip to content

ff branch

List local branches and remote-only branches. Give a name to create a branch without switching to it; with no revision, the new branch starts at trunk's tip. ff br and ff bookmark are aliases.

Usage

Usage: ff branch [OPTIONS] [name] [rev]

Examples

ff branch                       # List branches
ff branch --all                 # Include every remote-only branch
ff branch spike                 # Create at trunk without switching
ff branch spike HEAD~2          # Create at a revision
ff branch spike @               # Copy open work to the new branch
ff branch -d old-experiment      # Delete a local branch
ff branch --prune -n            # Preview pruning; still may fetch
ff describe -b unicode-cleanup  # Rename the current branch

Options

Arguments:
  [name]
          Create a branch by this name, and stay where you are

  [rev]
          Where it forks from: a revision, `@`, or a branch; trunk when omitted

Options:
  -d, --delete <branch>
          Delete a local branch; retained history allows `ff undo`

      --shared
          Also delete its remote copy, which `ff undo` cannot restore

      --prune
          Delete eligible branches whose remote copies are gone

      --json
          Emit machine-readable JSON

  -n, --dry-run
          Preview branch pruning without deleting branches; fetching can still run

      --all
          Every remote-only branch, not just the newest few

      --fetch
          Fetch now on commands that support fetching, regardless of cadence

      --at-op <op>
          Read as of this operation (a hex id or prefix, `@`, `@^`, `@~3`)

      --no-fetch
          Skip the fetch: read the tracking refs as they stand

      --at <time>
          Read as of the operation current at this time (30m/2h/3d, or a date)

      --session <name>
          Session name for this invocation

      --fields <list>
          Keep only these dotted paths of the JSON data, comma-separated

  -C, --cwd <dir>
          Run as if fufu had been started in <dir>

  -h, --help
          Print help (see a summary with '-h')

Listing and creating

The list groups chosen names before automatically generated names. Rows show tips, subjects, parked work, pending descriptions, and remote relationships. Remote-only rows represent tracking refs with no local branch tracking them; ff switch origin/<branch> creates and checks out a local tracking branch. --all removes the remote-only list limit. --at and --at-op are declared but currently refused for listing.

An explicit revision creates the branch there. A branch target also records that branch as the new base. @ means the open change: create below it and park a copy on the new branch, without changing current files. ff start creates and switches in one command. ff describe -b renames the current branch.

Deleting and recovery

-d <name> deletes a local branch and saves its timeline pointer in trash. Its tip and parked work remain pinned by retained operations; ff undo restores the branch and timeline. Deletion does not require a merged check and creates no Git stash.

A plain delete leaves the remote copy, tracking ref, and upstream in place. Add --shared to delete them too. A seen/tracking mismatch refuses before local deletion, unless the branch's own reflog shows it holding the tracking tip, on that commit or on one containing it. The remote send then checks the seen value as its lease; a remote race or rejection can leave the local branch deleted while the remote copy survives. Inspect the error and use ff undo to recover the local deletion. Undo cannot recreate a successfully deleted remote copy.

Pruning deleted remote copies

--prune fetches, then deletes eligible local branches whose remote copies are gone. All three conditions are required: an upstream is configured, its tracking ref is absent, and fufu recorded a previous seen or pushed copy. A never-published branch does not qualify.

Branches with commits the copy never held are kept and reported, as are the current branch, branches checked out elsewhere, and held branches. Use explicit -d when you intend to delete a particular branch. Dependents of a pruned branch are assigned its former base. One undo restores the local prune, timelines, base links, and tracking sections.

--dry-run previews local deletion; fetch and maintenance can still run. --no-fetch uses existing tracking refs. fufu.pruneGone enables the same pruning within ff pull.