Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "git-task"
version = "1.0.7"
version = "1.0.8"
edition = "2021"

[lib]
Expand Down
62 changes: 39 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

![git-task](assets/banner.png)

A git-native task manager. Tasks live inside the repo as git objects under `refs/tasks/*` —
event-sourced, no working-tree files, full history, synced with `push`/`pull` like any other ref.
A git-native task manager. Tasks live inside the repo as git objects under `refs/tasks/*`.
Event-sourced, no working-tree files, full history, synced with `push`/`pull` like any other ref.

## Get Started

Expand All @@ -14,15 +14,15 @@ brew tap imohsenb/tap
brew install git-task
```

**From source** (fallback — any platform, requires a Rust toolchain):
**From source** (fallback, any platform, requires a Rust toolchain):

```sh
git clone https://github.com/<you>/git-task && cd git-task && ./install.sh
git clone https://github.com/imohsenb/git-task && cd git-task && ./install.sh
# or: cargo install --locked --path .
```

Both install two binaries from the same codebase — `git-task` (so `git task ...` works) and
`gtask` (a standalone alias, e.g. `gtask new "title"`). Pick whichever fits how you invoke it.
Both install two binaries from the same codebase: `git-task` (so `git task ...` works) and
`gtask` (a standalone alias, e.g. `gtask new "title"`). Use whichever you prefer.

Then, inside any repo:

Expand All @@ -36,6 +36,17 @@ git task comment <id> "found the root cause"

That's the core loop. Everything below is reference for when you need more.

## Agent skills

`git task skills install` teaches a coding agent (e.g. Claude Code) this CLI: addressing,
`--format json`, task CRUD, config/automation, cross-repo sync, from `SKILL.md` files embedded in
the binary:

```sh
git task skills install # best-effort install into known agent dirs (e.g. ~/.claude/skills)
git task skills install --project # + this repo's .claude/skills, so it travels with the repo via git
```

## Common commands

```sh
Expand All @@ -53,7 +64,7 @@ git task export --all --format md # dump every task
git task whoami # identity a write would be attributed to
```

`<id>` accepts either the display form (`SRV-9057e58a`) or a bare hash prefix (`9057e58a`) — the
`<id>` accepts either the display form (`SRV-9057e58a`) or a bare hash prefix (`9057e58a`). The
`KEY-` part is cosmetic and stripped before lookup.

## Epics and links
Expand All @@ -68,12 +79,12 @@ git task show SRV-epic # full detail, incl. every child
```

Both also work across repos with `--repo <name|path|url>` (e.g.
`git task link SRV-1 add blocks LB-abc123 --repo backend`) — the target repo doesn't need to
`git task link SRV-1 add blocks LB-abc123 --repo backend`). The target repo doesn't need to
share git history. `epic --repo` additionally requires both repos registered under the same
project (see below) and opens the target to confirm the epic exists; `link --repo` just records
the reference without validating it (except a URL, stored verbatim).

## Working across repos
## Working across repos (multi-repo support)

Register repos so `git task ls` aggregates across all of them without `cd`-ing:

Expand All @@ -96,27 +107,27 @@ git task pull # fetch + reconcile
```

`pull` handles each task independently: new tasks are created, remote-ahead tasks fast-forward,
and tasks edited on both sides get a real two-parent merge commit — no data is lost, everyone
and tasks edited on both sides get a real two-parent merge commit. No data is lost, and everyone
converges on the same result regardless of which side merged. If your side has diverged, `push`
is rejected until you `pull` first, same as a normal git branch.

`git task clone` fetches only `refs/tasks/*` into a fresh repo — handy for a PM or stakeholder who
`git task clone` fetches only `refs/tasks/*` into a fresh repo, which is handy for a PM or stakeholder who
just wants to read/triage tasks without the source checkout. It sets up `origin`, so `push`/`pull`
work right away.

## Deleting tasks

- **`git task delete <id>`** — soft delete. Recorded as an event, syncs to every peer on their
- **`git task delete <id>`**: soft delete. Recorded as an event, syncs to every peer on their
next `pull`. `ls` hides deleted tasks by default (`--deleted` to include them). No `restore`.
- **`git task drop <id> --force`** — hard delete. Removes the local ref outright, no history
- **`git task drop <id> --force`**: hard delete. Removes the local ref outright, no history
entry, local-only (a peer's `pull` brings the task right back). Add `--remote [name]` to also
delete it on that remote.

## Configuration

Two layers:

- **User-level** (personal, not shared): `~/.config/git-task/config.toml` — registered repos,
- **User-level** (personal, not shared): `~/.config/git-task/config.toml`: registered repos,
their project grouping, default field requirements.
- **Per-repo** (shared, travels with every clone): event-sourced under `refs/tasks/config`, edited
only via `git task config`, never by hand.
Expand Down Expand Up @@ -151,14 +162,14 @@ back into itself.

## JSON output

Every command accepts `--format json`. Output is a single JSON document on stdout — safe to pipe
Every command accepts `--format json`. Output is a single JSON document on stdout, safe to pipe
into `serde_json`/`JSON.parse`/etc:

```jsonc
// success
{ "ok": true, "command": "new", "version": "1.0.0", "data": { /* command-specific */ } }

// failure — still on stdout, process still exits 1
// failure: still on stdout, process still exits 1
{ "ok": false, "command": "show", "version": "1.0.0",
"error": { "kind": "not_found", "message": "no task matching 'deadbeef'" } }
```
Expand All @@ -168,17 +179,22 @@ into `serde_json`/`JSON.parse`/etc:
`display_id`/`key` and resolved `*_name` fields (`assignee_name`, etc.) beyond the plain domain
model.

## Agent skills
## Web UI

`git task skills install` teaches a coding agent (e.g. Claude Code) this CLI — addressing,
`--format json`, task CRUD, config/automation, cross-repo sync — from `SKILL.md` files embedded in
the binary:
Prefer a browser? [git-task-web](https://github.com/imohsenb/git-task-web) is a local web app on top
of the same git objects: board, list and table views, milestones, members, sync, and markdown
descriptions with code blocks, tables and Mermaid diagrams. No database, no account, nothing to host.

```sh
git task skills install # best-effort install into known agent dirs (e.g. ~/.claude/skills)
git task skills install --project # + this repo's .claude/skills, so it travels with the repo via git
git task web start # installs git-task-web via npm on first run, serves http://localhost:4600
git task web stop
git task web upgrade
```

![Board view](assets/screenshots/board.png)

![Task view with markdown and a Mermaid diagram](assets/screenshots/task.png)

## Development

```sh
Expand All @@ -187,6 +203,6 @@ cargo test # unit + integration tests (real temp re
git task completions bash > ... # also: zsh, fish, powershell, elvish
```

`git task --help` (bare) is intercepted by git itself and runs `man git-task` — without a man page
`git task --help` (bare) is intercepted by git itself and runs `man git-task`. Without a man page
installed that just prints an error. `git task -h` / `git task help` / `git task <cmd> --help` all
work regardless. Run `git task man --install` once to fix the bare form too.
Binary file added assets/screenshots/board.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/screenshots/task.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading