Skip to content

index.md

Latest commit

 

History

History
144 lines (109 loc) · 4.3 KB

index.md

File metadata and controls

144 lines (109 loc) · 4.3 KB

TicGit

TicGit is a Git-native issue tracker. Tickets live in the repository as structured git-meta metadata instead of files on an orphan branch. The command-line tool is named ti.

Quick Start

git init
git config user.email you@example.com
git config user.name "Your Name"

ti init
ti new --title "fix the parser" --tags bug,parser --comment "fails on empty input"
ti list
ti show <ticket-id-or-prefix>

Most commands accept a full UUID or any unique UUID prefix.

Common Commands

Create tickets:

ti new --title "add docs"
ti new --title "fix crash" --tags bug,cli --assigned you@example.com
ti new --title "investigate flaky test" --comment "seen on CI twice"

List and filter:

ti list
ti list --status open
ti list --state blocked
ti list --tag bug
ti list --assigned you@example.com
ti list --order title.desc
ti list --json
ti list --markdown

Show details:

ti show <id>
ti show <id> --json
ti show <id> --markdown
ti show <id> --filter .title
ti show <id> --filter .comments[0].body

Select a current ticket:

ti checkout <id>
ti show
ti comment "follow-up note"
ti checkout --clear

Mutate tickets:

ti state blocked --ticket <id>
ti state closed --ticket <id>
ti state closed:wontfix --ticket <id>
ti status review --ticket <id>
ti assign you@example.com --ticket <id>
ti points 3 --ticket <id>
ti milestone v1.0 --ticket <id>
ti tag --ticket <id> bug ui
ti edit <id>
ti comment --ticket <id> "fixed in the latest patch"
ti close <id>

Lifecycle values are split into a broad status and a specific state. Open tickets use new, assigned, in-progress, blocked, or review. Closed tickets use resolved, wontfix, duplicate, or invalid. New tickets start as open:new; ti state closed defaults to closed:resolved.

Machine Output

Use --markdown for agent workflows and --json for scripts that need stable schema output:

ti list --markdown
ti show <id> --markdown
ti new --title "agent task" --markdown
ti state blocked --ticket <id> --markdown
ti comment --ticket <id> "blocked on parser fixture" --markdown

The stable machine-output schema is published at schema/v1.json. ti show --json and JSON mutation commands emit a ticket object. ti list --json emits an array of ticket objects. Commands that support --json also support --markdown, which renders the same ticket data as Markdown and includes suggested next commands. Ticket metadata appears under .meta as an object whose values are strings.

--json is the stable machine interface:

  • successful JSON commands write parseable JSON to stdout only
  • diagnostic and error text goes to stderr
  • JSON output does not include ANSI color escapes
  • non-zero exit status means the command failed
  • ticket ids may be full UUIDs or unique UUID prefixes
  • ambiguous or missing prefixes fail with a non-zero exit status and stderr diagnostic

--porcelain and --format json are not supported compatibility aliases today; use --json for schema-stable output.

Agents can also run:

ti help --agent

That prints an agent-focused Markdown guide directly from the installed CLI.

Sync

Ticket metadata is separate from normal Git commits. Sync it explicitly when collaborating:

ti sync

ti sync performs a pull followed by a push through git-meta.

What TicGit Stores

All TicGit data is written on the git-meta project target under the ticgit: namespace:

ticgit:schema-version                    string
ticgit:owners                            set
ticgit:views:<name>                      set of ticket UUIDs
ticgit:tickets:<uuid>:title              string
ticgit:tickets:<uuid>:description        string (optional)
ticgit:tickets:<uuid>:status             string
ticgit:tickets:<uuid>:state              string
ticgit:tickets:<uuid>:assigned           string
ticgit:tickets:<uuid>:points             string
ticgit:tickets:<uuid>:milestone          string
ticgit:tickets:<uuid>:tags               set
ticgit:tickets:<uuid>:comments           list
ticgit:tickets:<uuid>:created-at         string
ticgit:tickets:<uuid>:created-by         string

Ticket existence is implied by the presence of fields under ticgit:tickets:<uuid>:*; there is no separate ticket index. Exchange with other clones happens through refs/meta/* using normal Git transfer.