Task Management

Task Management

Command reference for creating, reading, and mutating individual tasks. Every command below also accepts the global --format json flag; see JSON Output for the response shapes.

Creating

git task new "Fix login timeout" \
  --kind bug --priority high --assignee alice@example.com \
  --label auth --fixed-version 1.2.1 --due 2026-08-20 \
  --milestone v2.0 --parent SRV-epic

Flag	Notes
title (positional)	Required. Prompted for if omitted, interactively only.
--kind	bug | story | task | epic | subtask. Defaults to task.
--desc	Description. Required, same as title.
--priority	low | medium | high.
--assignee	Must be a real email address, not a free-form name.
--label	Repeatable: --label x --label y.
--fixed-version / --affected-version	Repeatable.
--due	Free-form date text.
--milestone	Free-form text.
--parent	An epic's id or KEY-hash address.
--status	Land directly on a status instead of the default todo. Emitted in the same operation package as the creation, so no peer syncing mid-write ever observes an intermediate "just created, still todo" state.

Whether --priority, --assignee, and --due are actually required depends on the repo's configuration; see Configuration. Check the effective set with git task fields --format json before scripting a non-interactive new.

Reading

git task show SRV-9057e58a                # boxed detail view
git task show SRV-9057e58a --markdown     # markdown rendering
git task show SRV-9057e58a --format json  # full detail, including op history

show's JSON response is the only one that populates children[]: every task whose parent points back at this one, same-repo and cross-repo (see Epics and Links).

git task ls
git task ls --status doing --kind bug --mine
git task ls --parent SRV-epic             # one epic's same-repo children
git task ls --deleted                     # include soft-deleted tasks
git task ls --label urgent --fixed-version 1.2.0 --affected-version 1.1.0

ls filters compose (every supplied filter must match). --mine and --assignee are mutually exclusive. By default ls shows just the current repo; see Sync and Multi-Repo for aggregating across every registered repo.

git task log SRV-9057e58a

Prints the full, human-readable audit trail: every operation, with its timestamp and author, in causal order. This command does not currently branch on --format json; for machine-readable history, read the history array from git task show <id> --format json instead (also present in export's output).

git task export --all --format json        # every task in the repo
git task export SRV-9057e58a --format md   # a single task

export takes exactly one of a task id or --all.

Editing

git task edit SRV-9057e58a --priority critical --assignee alice@example.com
git task edit SRV-9057e58a --status doing --parent SRV-epic --label urgent
git task edit SRV-9057e58a --clear-assignee --clear-due

Each --clear-* flag (--clear-assignee, --clear-priority, --clear-due, --clear-milestone, --clear-parent) conflicts with its corresponding set flag; pass one or the other, never both.

--label, --fixed-version, and --affected-version on edit are repeatable and additive only. To remove one, use the dedicated commands below, not edit.

git task edit <id> with no flags at all is interactive: it walks every field, showing the current value as the default (enter keeps it). This only triggers on a real terminal and never under --format json. Never invoke bare edit from a script; always pass explicit flags, or it will hang waiting on stdin.

Status, comments, labels, versions

git task status SRV-9057e58a doing         # free-form string, no fixed workflow
git task comment SRV-9057e58a "found the root cause"
git task comment SRV-9057e58a --edit 1 "revised note"   # edit comment #1 (shown in `show`)
git task label SRV-9057e58a add urgent
git task label SRV-9057e58a rm urgent
git task version SRV-9057e58a fixed-add 1.2.0
git task version SRV-9057e58a fixed-rm 1.2.0
git task version SRV-9057e58a affected-add 1.1.0
git task version SRV-9057e58a affected-rm 1.1.0

Fixed/affected versions are multi-value sets, empty by default. Empty sets are hidden from text/markdown rendering but always present, as an empty array, in JSON.

Deleting tasks

Two different commands, easy to confuse:

• git task delete <id>, soft delete. Appends an event, syncs to every peer on their next pull, hidden from ls by default (ls --deleted to see it). There is no restore. This is almost always what "delete" or "close" means.
• git task drop <id> --force, hard delete. Removes the local ref outright, no history entry, does not sync (a peer's later pull can bring the task right back). Add --remote [name] to also remove it on that one remote; any other clone that already has the task is unaffected and can reintroduce it.

git task delete SRV-9057e58a
git task drop SRV-9057e58a --force
git task drop SRV-9057e58a --force --remote origin

Identity behind a write

git task whoami

Shows the repo-level, global-level, and effective (what a write would actually use) identity, without writing anything. Useful to run before scripting a new/comment/etc. in an environment where git config might not be what you expect, such as CI runners or freshly provisioned machines.

Next: Epics and Links for parent/child and relation modeling.