diff --git a/Cargo.lock b/Cargo.lock index 7e94e29..a02ee33 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -451,7 +451,7 @@ dependencies = [ [[package]] name = "git-task" -version = "1.0.7" +version = "1.0.8" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 1583c4f..324c3a4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "git-task" -version = "1.0.7" +version = "1.0.8" edition = "2021" [lib] diff --git a/README.md b/README.md index 0cda669..c644db4 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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//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: @@ -36,6 +36,17 @@ git task comment "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 @@ -53,7 +64,7 @@ git task export --all --format md # dump every task git task whoami # identity a write would be attributed to ``` -`` accepts either the display form (`SRV-9057e58a`) or a bare hash prefix (`9057e58a`) — the +`` 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 @@ -68,12 +79,12 @@ git task show SRV-epic # full detail, incl. every child ``` Both also work across repos with `--repo ` (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: @@ -96,19 +107,19 @@ 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 `** — soft delete. Recorded as an event, syncs to every peer on their +- **`git task delete `**: 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 --force`** — hard delete. Removes the local ref outright, no history +- **`git task drop --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. @@ -116,7 +127,7 @@ work right away. 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. @@ -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'" } } ``` @@ -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 @@ -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 --help` all work regardless. Run `git task man --install` once to fix the bare form too. diff --git a/assets/screenshots/board.png b/assets/screenshots/board.png new file mode 100644 index 0000000..5a99dba Binary files /dev/null and b/assets/screenshots/board.png differ diff --git a/assets/screenshots/task.png b/assets/screenshots/task.png new file mode 100644 index 0000000..956cd3e Binary files /dev/null and b/assets/screenshots/task.png differ