Sync and Multi Repo

Sync and Multi-Repo

Tasks move over their own explicit refspecs (refs/tasks/*); a plain git fetch/git pull/ git push never touches them at all. Use the git task subcommands below instead of a manual refspec.

Push and pull

git task push [remote]     # default remote "origin"
git task pull [remote]     # fetch + reconcile

pull reconciles each task independently:

Situation	Outcome
Task you don't have yet	created outright (new)
Remote strictly ahead	fast-forwarded
Edited on both sides since last sync	a real two-parent git merge commit (merged)
Already matches	up_to_date

No data is lost in a merge: both branches' full operation histories remain reachable, and loading a task always replays every reachable commit in topological order, so it doesn't matter which side happened to run the merge. If your local tasks have diverged from the remote, push is rejected exactly like a non-fast-forward branch push; run git task pull first rather than forcing anything.

pull's config-ref handling uses the same reconcile machinery, since refs/tasks/config is stored the same way as a task. If a pulled change to project automation rules would affect your next mutating command, pull warns about it by name.

Tasks-only clone

For someone who only needs to read or triage tasks, with no source checkout:

git task clone git@github.com:you/your-repo.git    # -> ./your-repo-tasks
cd your-repo-tasks
git task ls

This sets up origin on the way in, so push/pull work immediately; it's a real (if minimal) git-task install, not a one-off export. The repo's config (address key, required fields, automation rules) comes along too, since it's just another ref under refs/tasks/*, so ls/ show display the real key prefix right away, with no separate setup step.

Cross-repo registration

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

git task register                     # register the current repo, project "main"
git task register --project web       # register under an explicit project group
git task register --project other     # already registered: moves it there instead
git task repos                        # list registered repos
git task repos --format json --deep   # + per-repo probe: task counts, remotes, identity
git task projects                     # projects and the repos grouped under each
git task unregister <name>            # remove a registration

Registration is user-level state (~/.config/git-task/config.toml), personal to this machine: registering a repo on one clone doesn't register it anywhere else. Run register again on each machine or clone that should be included in an aggregated ls.

register also captures the repo's origin remote URL, if it has one, alongside its local path. That's what makes a cross-repo link --repo <name> or epic --repo <name> (see Epics and Links) portable across machines: the URL is what's stored, not the local path, and it's compared in a protocol/host-form-agnostic way.

Aggregated listing

Once repos are registered, a bare git task ls aggregates tasks across every one of them, falling back to just the current repo if nothing is registered yet:

git task ls                          # everything, every registered repo
git task ls --project backend        # only repos in one project group
git task ls --repo web               # only one named repo
git task ls --here                   # only the current repo, ignoring the registry entirely

--here and the registry selectors (--repo/--project/--all) are mutually exclusive.

Projects

A project is just a label repos are grouped under, for filtering ls/repos/projects. Manage the label set itself with git task project:

git task project create web
git task project set-default web
git task project rename web frontend
git task project delete web           # must be empty and non-default

Next: JSON Output if you're consuming this data programmatically rather than by eye.