Getting Started

Getting Started

This walks through the core loop: create a task, look at it, move it through statuses, and record progress. Run these inside any existing git repository.

Create a task

git task new "Fix login timeout" --kind bug --priority high

Every task needs a title and a description. If you omit --desc and you're at an interactive terminal, git-task prompts for it. Piped or scripted (no TTY), it fails fast instead, listing which required fields are missing, rather than hanging on stdin:

git task new "Fix login timeout" --kind bug --priority high --desc "Session drops after 5 minutes idle"

The command prints the task it created, including a display id such as SRV-9057e58a.

Look at it

git task show SRV-9057e58a

Prints a boxed detail view: title, description, status, priority, assignee, labels, comments, and any linked or parent tasks. Add --markdown for a markdown rendering instead, or --format json for a machine-readable document (see JSON Output).

List tasks

git task ls

Lists open tasks in the current repository as a table. Filters compose:

git task ls --status doing --kind bug
git task ls --mine                      # assigned to you (matches your git user.name/email)
git task ls --deleted                   # include soft-deleted tasks (hidden by default)

Move it along

git task status SRV-9057e58a doing
git task comment SRV-9057e58a "found the root cause, patch incoming"
git task status SRV-9057e58a done

Status is a free-form string, not a fixed workflow: todo, doing, done, blocked are conventions the interactive prompts suggest, not an enforced set. Use whatever vocabulary fits your team.

Edit fields

git task edit SRV-9057e58a --priority critical --assignee alice@example.com

Running git task edit SRV-9057e58a with no flags at all drops into an interactive prompt per field (press enter to keep the current value). That only happens on a real terminal; a script should always pass explicit flags.

Addressing a task

A task's real identity is a git object hash. SRV-9057e58a is a readable display form: the SRV- part is a cosmetic prefix (the repo's configured address key), stripped before every lookup. A bare hash prefix, 9057e58a, always works too. Get the id from a prior new/show/ls result rather than typing one from memory.

Where task data lives

Nothing above touched the working tree. Tasks are git objects under refs/tasks/*; git status in the same repo stays clean throughout. See Core Concepts for how that storage model works, and why it's what lets push/pull and multi-repo sync behave like ordinary git.

Next: skim Task Management for the full command reference, or Core Concepts if you'd rather have the model first.