{"id":51339595,"url":"https://github.com/async/auto-git","last_synced_at":"2026-07-02T06:04:26.884Z","repository":{"id":364417662,"uuid":"1267864260","full_name":"async/auto-git","owner":"async","description":"AI agent Git workflow for safe staging, intent-based commits, push/merge/land flows, worktree handling, topology-aware automation, large dirty diff splitting, unrelated edit protection, and audit/rewrite routing.","archived":false,"fork":false,"pushed_at":"2026-06-19T23:51:58.000Z","size":232,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T01:14:27.126Z","etag":null,"topics":["ai","codex","git","staging"],"latest_commit_sha":null,"homepage":"https://async.github.io/auto-git/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/async.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-12T23:36:49.000Z","updated_at":"2026-06-19T23:52:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/async/auto-git","commit_stats":null,"previous_names":["async/auto-git"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/async/auto-git","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/async%2Fauto-git","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/async%2Fauto-git/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/async%2Fauto-git/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/async%2Fauto-git/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/async","download_url":"https://codeload.github.com/async/auto-git/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/async%2Fauto-git/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35034995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","codex","git","staging"],"created_at":"2026-07-02T06:04:26.192Z","updated_at":"2026-07-02T06:04:26.871Z","avatar_url":"https://github.com/async.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auto Git\n\nAuto Git is a Codex skill suite for turning repository work into understandable Git history.\n\n## Skills\n\n- `auto-git`: supports local-review checkpoints plus coordinated worktrees, PR handoffs, and fanouts by change intent.\n- `git-intent-audit`: read-only evidence for large dirty worktrees, unclear intent, oversized commits, mixed commits, and message/diff mismatches.\n- `git-history-rewrite`: audit-backed local history replay by change intent, preserving authorship and never force-pushing by default.\n\n`auto-git` owns the canonical commit style. The audit and rewrite skills defer to `skills/auto-git/references/commit-by-intent.md` for intent type selection, scope selection, message wording, and `chore` as the last resort.\n\n## Source Layout\n\n```text\nskills/          Installable Codex skill folders\ndocs/gists/      README source for each published gist package\ngists/           Generated flat gist packages\nscripts/         Validation, packaging, and publishing tools\ntests/           Node test suite for package invariants\npipeline.ts      @async/pipeline workflow definition\napi-contract.json Semantic API surface manifest\nAPI_SURFACE.md   Generated API surface ledger\n```\n\nThe commit intent rules live in `skills/auto-git/references/commit-by-intent.md`.\nUse the most specific intent prefix that fits:\n\n```text\nfeat: new capability\nfix: broken behavior corrected\nsecurity: vulnerability or hardening change\nperf: performance improvement\nrefactor: internal change, same behavior\ntest: test-only change\ndocs: documentation-only change\nstyle: formatting-only change\ndeps: dependency-only update\nbuild: build/package system\nci: CI workflow change\nmigrate: database/schema/data migration\nrelease: version/changelog/release metadata\nrevert: undo a previous commit\nchore: maintenance that does not fit above\n```\n\nUse `chore: ` last. If `deps: `, `build: `, `ci: `, `release: `,\n`migrate: `, `security: `, `style: `, `test: `, `docs: `, or\n`refactor: ` fits, use that more specific intent instead.\n\nAuto Git supports two workflows. Local review is the original single-chat flow:\ncommit by intent in the current checkout so code can be reviewed as it evolves.\nCoordinated branch is the multi-chat flow: when work may collide, or the user\nasks for branch/PR/fanout/experiment/get-this-in/ship, Auto Git keeps trunk as\nthe coordination base and uses isolated branches/worktrees plus safe ledger\nmetadata under `~/.async/auto-git/v1/repos/\u003crepo-hash\u003e/ledger.json`. Live run\nleases also use Async lock records under\n`~/.async/locks/auto-git/repos/\u003crepo-hash\u003e/runs/*.lease.json`, with completion\nreceipts under `~/.async/locks/auto-git/history/`. Future chats can see active\nleases, stale work, verification state, and PR handoffs.\nAuto Git never merges merely because a PR is ready; merge stays tied to\nexplicit `land` or later merge intent.\n\nWhen the user says \"auto-git do everything\", Auto Git can take start-to-finish\nownership across git status, commit-by-feature, verification, sync/PR handoff,\nland/merge, and release. That mode still stops for safety gates such as\nsecrets, destructive cleanup, failed verification, force pushes, remote tag\nmovement, and missing release metadata.\n\n`auto-git yolo`, `$auto-git yolo`, and `[$auto-git] yolo` are stronger than\nordinary `everything`: they require coordinated worktree/branch handling,\ncommit-by-intent, verification gates, push/sync evidence, PR handoff or\nmerge/land evidence, release-preflight and release handling when a release\nsurface exists, return-to-main/default-branch evidence, and a completed ledger\nreceipt before reporting done. YOLO still stops for secret exposure,\ndestructive cleanup, force pushes, remote tag movement, failed verification,\nmissing release metadata, unavailable auth, or ambiguous repo targets.\n\nDone means cleaned up, not just committed: coordinated/everything/yolo branch\nwork should push the completed branch with upstream tracking and switch back to\nmain before the final receipt unless the user explicitly asks to stay on the\nbranch. The finish receipt should also check PR handoff or pushed merge\nevidence and confirm the ledger update, so completed work is either handed off,\nintegrated, or explicitly blocked.\nWhen finish runs after switching back to main, the ledger should still preserve\nthe completed branch and head for later handoff.\n\nDo not edit `gists/**` by hand. Update `skills/**` or `docs/gists/**`, then run:\n\n```sh\npnpm run gists:package\n```\n\nThat command is the source-to-generated implementation step for gist packages.\nNormal verification and publishing still route through the pipeline-owned\nscripts below.\n\n## Helper CLI\n\nThe npm package exposes an `auto-git` dispatcher plus individual helper bins:\n\n```sh\nauto-git snapshot --cwd \"$PWD\" --write-state\nauto-git gate --cwd \"$PWD\" --profile auto -- pnpm run pipeline:verify\nauto-git release-preflight --cwd \"$PWD\" --require-verification\n```\n\nWhen `auto-git` runs inside this source checkout, it dispatches to the local\n`skills/auto-git/scripts/*` helpers so development uses the working tree copy.\nWhen installed globally, the same commands dispatch to the packaged helpers.\nThe copied Codex skill can still fall back to its local `scripts/*.mjs` files\nwhen the npm CLI is not on `PATH`.\n\n## Releases\n\nRelease commits should use the `release(...)` intent. Keep the `package.json`\nversion bump, the matching `CHANGELOG.md` section, and any lockfile or package\nmetadata caused by the bump in the same release commit. `pnpm run pipeline:verify` checks\nthat the current package version has a changelog entry.\n\nBefore release, run the full release gate on the exact commit that will be\npublished. Push and merge the release-prep branch before using the generated\nworkflow. If a remote release tag already exists and does not match the release\ncommit, stop for explicit approval; do not move it from the local machine.\n\nPublished releases have four public surfaces that must agree: the git tag,\nGitHub Release, npm package, and GitHub Packages mirror. Normal releases use the\ngenerated `@async/pipeline` workflow with npm provenance:\n\n```sh\npnpm run pipeline:verify -- --force\n# In GitHub Actions, run \"Async Pipeline\" with the publish job selected.\npnpm run pipeline:release:doctor\n```\n\nThe generated workflow creates or verifies the tag and GitHub Release, publishes\nthe GitHub Packages mirror first, then publishes npm.\n`pnpm run pipeline:release:doctor` diagnoses missing or drifted tag/npm/GitHub\nstate and names only repairs that are safe to run.\n\n## Local Verification\n\n```sh\npnpm install\npnpm run pipeline:verify\n```\n\nUseful focused commands:\n\n```sh\npnpm run pipeline:api-surface\npnpm run pipeline:pack\npnpm run pipeline:pages\npnpm run pipeline:sync:check\npnpm run pipeline:github:check\npnpm run pipeline:release:doctor\n```\n\n## Gist Publishing\n\nThe published gist packages are generated from this repo:\n\n- Auto Git: https://gist.github.com/PatrickJS/2d858aca3211451a0cad7282971beb90\n- Git Intent Audit: https://gist.github.com/PatrickJS/b65dd814cde5d9c380b26ecdeba883d4\n- Git History Rewrite: https://gist.github.com/PatrickJS/7acdfd0d8d8d3948cbc7003651b68db6\n\nPublishing requires a token that can update those gists:\n\n```sh\nGIST_TOKEN=... pnpm run pipeline:publish-gists\n```\n\nOn GitHub Actions, configure a repository secret named `GIST_TOKEN`. The\ngenerated `@async/pipeline` workflow publishes gists on pushes to `main`; manual\npublishing uses the generated workflow dispatch `job` selector with\n`publish-gists`.\n\nThe lower-level `gists:*` scripts are implementation commands used by pipeline\ntasks and source-to-generated packaging checks.\n\n## Pipeline\n\n`@async/pipeline` owns the GitHub Actions workflow. Regenerate after editing `pipeline.ts`:\n\n```sh\npnpm run pipeline:sync:generate\npnpm run pipeline:sync:check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasync%2Fauto-git","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasync%2Fauto-git","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasync%2Fauto-git/lists"}