Real commands with real output — personal account and team/org scenarios side by side.
Run once per platform. Tokens are stored in ~/.gitcollect/config. Every command that touches the platform reads from there.
GitHub token scopes needed: repo, read:org (for team import), admin:org (to add collaborators to org repos). GitLab: api scope on a glpat-… token.
Group your own repos — dotfiles, side projects, configs — into a named collection you can clone on any machine in one command.
Set --namespace to your GitHub org or GitLab group. gitcollect uses the namespace for all API calls and repo lookups — it does not have to match the collection name.
Members are platform users who can access repos. Groups are named subsets — use them to restrict specific repos to specific roles without giving everyone access to everything.
gitcollect stores members by their immutable platform user ID, never by login. Renaming a GitHub or GitLab account never breaks membership — the cached login is kept alongside the ID for display only.
By default every member can reach every repo. Narrow that with per-repo rules: restrict to groups, specific users, or reopen to everyone.
Per-repo rules outrank visibility. A public collection opens its
unrestricted repos to everyone, and leaves group- and user-restricted repos restricted. Marking a
collection public is not a way to grant blanket access. Changed in v3.1.0 — earlier versions
ignored per-repo rules entirely on public collections and sync pushed the resulting grants to
the platform; run gitcollect diff after upgrading.
Requires v3.2.0 or newer. Earlier binaries do not carry this command.
Check with gitcollect --version; if you are behind, upgrade once using the Method 1 or
Method 2 commands on the install page, and get-update carries itself
forward from then on.
The upgrade follows however gitcollect was installed:
checksums.txt, and replaces the binary in
place. A download whose checksum does not match is refused, never installed.go install github.com/alby-tomy/gitcollect/v3@latest rather than overwriting
the file, so the Go toolchain stays the source of truth for the binary it manages.go build in a
checkout reports a development version such as
v3.0.2-0.20260914175157-eb4982ebc6d1+dirty; overwriting your own build with a
published one would lose work.Aliases: update, upgrade, self-update.
If the binary lives somewhere unwritable (/usr/local/bin on most systems),
get-update reports the permission error rather than half-replacing it — re-run with
elevated privileges.
Every access-changing action is appended to ~/.gitcollect/audit/<collection>.log. Logs are local — export them with --json for off-machine backup.
Four commands added in v3: find repos to collect, then see across them.
scan never overwrites. A collection that already exists is skipped, so re-running --apply cannot lose members, groups or per-repo access rules.
Choosing a grouping strategy. token (the default) buckets on the most widely shared meaningful word wherever it sits in the name, so china-pricing, eu-pricing and us-pricing form one pricing collection. A word must appear in at least two repos to name a group, and generic terms (service, api, core, …) are skipped so cart-service and search-service do not collapse into service. --group-by prefix uses only the first hyphenated segment — correct for a deliberate namespace like payments-gateway, but it splits regional variants of one module apart. --group-by flat puts everything in one collection.
Personal accounts. An org and a user are different API endpoints, so a personal account needs --user; --org with a username fails. Your own login includes private repos, someone else's returns only what your token can see.
Grouping by name is a guess. --interactive confirms each repo before anything is written — Enter accepts the suggested category, d drops the repo, and typing a name files it under that category instead. This is the check for an account holding several unrelated projects, where a repo can be matched to the wrong one.
Unreadable repos are named, not counted as zero. If the platform refuses a repo — a 403, or a rate limit — pr and health say which repos they could not read and exclude them from the totals, rather than silently reporting no open PRs.
Archive is not delete. The YAML file, its repos and every access rule stay exactly as they were — only the collection's visibility in list, sync --all and status --all changes. Only the collection owner can archive or unarchive.
Quick-reference table. See the full docs for every flag.
| Command | Scope | Description |
|---|---|---|
| gitcollect auth | Both | Store a platform token |
| gitcollect whoami | Both | Show authenticated identities |
| gitcollect init | Both | Create a new collection |
| gitcollect add | Both | Add repos to a collection |
| gitcollect remove | Both | Remove a repo (revokes platform access) |
| gitcollect list | Both | List all local collections |
| gitcollect show | Both | Show a collection's contents |
| gitcollect inspect | Both | Full access matrix — who can reach what |
| gitcollect clone | Both | Clone all accessible repos |
| gitcollect pull | Both | Pull updates in every local repo |
| gitcollect sync | Both | Clone missing + pull existing |
| gitcollect member add | Org | Add a member and grant platform access |
| gitcollect member remove | Org | Remove a member and revoke access |
| gitcollect member list | Org | List members with group/repo breakdown |
| gitcollect group add | Org | Create a group or add members to it |
| gitcollect group remove | Org | Remove a group or member from it |
| gitcollect repo access | Org | Restrict a repo to groups or users |
| gitcollect repo show | Org | Show who can access a specific repo |
| gitcollect visibility | Org | Change collection visibility |
| gitcollect publish | Org | Push collection YAML to a shared config repo |
| gitcollect pull-config | Org | Fetch collection files from a config repo |
| gitcollect join | Org | One-command new-hire onboarding |
| gitcollect import | Org | Import a team from the platform API |
| gitcollect sync-config | Org | Refresh local collection from platform team state |
| gitcollect export | Both | Print collection(s) as YAML or JSON |
| gitcollect audit | Org | View the local audit log |
| gitcollect verify | Both | Check repos are still reachable |
| gitcollect doctor | Both | Health-check auth and collections |
| gitcollect get-update | Both | Upgrade to the latest release |
| gitcollect --version | Both | Print the running version (also -v) |
| gitcollect delete | Both | Delete a collection (revokes all access) |
| gitcollect concepts | Both | Explain core concepts and mental model |
| gitcollect status | Both | git status across every cloned repo |
| gitcollect diff | Org | Compare the manifest against platform reality |
| gitcollect find | Both | Search local collections for a repo or member |
| gitcollect scan | Both | Discover org or personal repos and group them into collections |
| gitcollect pr | Both | Open pull/merge requests across a collection |
| gitcollect health | Both | Cloned / dirty / behind / open-PR dashboard |
| gitcollect archive | Both | Hide a collection from list/sync/status (owner only) |
| gitcollect unarchive | Both | Restore an archived collection (owner only) |
| gitcollect activity | Both | Recent commits across a collection (experimental) |
| gitcollect describe | Both | Set or clear a collection's description |
| gitcollect rename | Both | Rename a collection |
| gitcollect copy | Both | Copy a collection to a new name |
| gitcollect move | Both | Move a repo, or a whole module, between collections |
| gitcollect transfer | Org | Transfer ownership to another member |
| gitcollect scale | Org | Switch between team and organisation tier |
| gitcollect completion | Both | Shell completion for bash/zsh/fish/powershell |
| gitcollect version | Both | Print build version — also -v / --version |
--offline: Pass to any command to disable all network calls. Commands that require the platform API return a clear error instead of attempting a connection.
Full flag reference: See index.html → Commands for every flag on every command.