Skip to content

ff describe

Set the draft message for your open change, reword an existing commit, or rename the current branch. With no revision or -b, edit the draft message in $EDITOR; -m sets it directly. ff desc is the short spelling.

Usage

Usage: ff describe [OPTIONS] [rev]

Examples

ff describe -m "parser: handle unicode escapes"  # Draft message
ff describe                     # Edit the draft in $EDITOR
ff describe HEAD~2 -m "parser: fix escapes"  # Existing commit
ff describe -b unicode-cleanup  # Rename the current branch

Options

Arguments:
  [rev]
          The revision to reword; omitted describes the open change

Options:
  -m <msg>
          The description text; omitted opens $EDITOR

  -b <branch>
          Rename the current branch instead of editing a message

      --no-verify
          Skip commit-msg when rewording a recorded commit

      --json
          Emit machine-readable JSON

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

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

      --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')

Three modes

  • Draft message: omit the revision, or use @. ff commit uses this pending description unless its own -m overrides it. Describing updates internal open metadata without advancing branch history, and runs no commit hooks.
  • Existing message: name one recorded revision. Its message changes and commits above it re-parent in the same operation, including branches inside that range. Surviving change IDs stay the same; commit hashes change.
  • Branch rename: -b <name> renames the current branch, whether its old name was automatic or chosen. Its capture history, parked work, and pending description remain associated with it. This mode cannot be combined with a revision or -m.

The revision expression must select exactly one member. Without -m, message modes open $EDITOR with the current text.

Dependent branches and recovery

After a reword, dependent local branches replay parent before child in the same operation. One ff undo takes back the reword and cascade.

A reword preserves its commit's tree, but an already stale dependent branch can conflict. That branch records a hold while the reword stands. This outcome currently exits 0; scripts must inspect reword.cascade.held. Branches checked out elsewhere or already held are skipped and named, along with the dependents left alone above them. Use ff switch and ff resolve on a held branch. A held restack or merge already on the branch stays and follows the reword; a held absorb, lift, done, or parked-change arrival refuses it.

Hooks

Rewording a recorded commit runs prepare-commit-msg and commit-msg; a failing hook refuses it before replay planning. --no-verify skips commit-msg. No file content is committed, so pre-commit does not run. Draft descriptions run their hooks later, when committed.