{"id":45915129,"url":"https://github.com/serpro69/gh-arc","last_synced_at":"2026-02-28T07:36:33.842Z","repository":{"id":323929597,"uuid":"1073645332","full_name":"serpro69/gh-arc","owner":"serpro69","description":"Github CLI extension that implements an opinionated trunk-based development workflow with Github, built upon the great traditions of tools like phacility/arcanist and phorge/arcanist","archived":false,"fork":false,"pushed_at":"2026-02-01T19:17:23.000Z","size":711,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-02T00:51:16.312Z","etag":null,"topics":["arcanist","cli","gh-extension","gh-extensions","github","linting","phabricator","phorge","trunk-based-development","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Go","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/serpro69.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":null,"dco":null,"cla":null}},"created_at":"2025-10-10T12:13:08.000Z","updated_at":"2026-02-01T19:17:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/serpro69/gh-arc","commit_stats":null,"previous_names":["serpro69/gh-arc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/serpro69/gh-arc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fgh-arc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fgh-arc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fgh-arc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fgh-arc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serpro69","download_url":"https://codeload.github.com/serpro69/gh-arc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpro69%2Fgh-arc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29927623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"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":["arcanist","cli","gh-extension","gh-extensions","github","linting","phabricator","phorge","trunk-based-development","unit-testing"],"created_at":"2026-02-28T07:36:33.185Z","updated_at":"2026-02-28T07:36:33.837Z","avatar_url":"https://github.com/serpro69.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-arc\n\n\u003cdiv markdown=\"1\" style=\"text-align: center; font-size: 1.2em;\"\u003e\n\n\u003cb\u003e🚧 Fork in progress, expect some dust 🚧\u003c/b\u003e\n\n[![github-tag](https://img.shields.io/github/v/tag/serpro69/gh-arc?style=for-the-badge\u0026logo=semver\u0026logoColor=white)](https://github.com/serpro69/gh-arc/tags)\n[![github-license](https://img.shields.io/github/license/serpro69/gh-arc?style=for-the-badge\u0026logo=unlicense\u0026logoColor=white)](https://opensource.org/license/mit)\n[![github-stars](https://img.shields.io/github/stars/serpro69/gh-arc?logo=github\u0026logoColor=white\u0026color=gold\u0026style=for-the-badge)](https://github.com/serpro69/gh-arc)\n\n\u003c/div\u003e\n\n`gh-arc` is a [github cli extension](https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions#about-github-cli-extensions) that implements an opinionated [trunk-based development workflow](https://martinfowler.com/articles/branching-patterns.html#Trunk-basedDevelopment) with Github, built upon the great traditions of tools like [phacility/arcanist](https://github.com/phacility/arcanist/tree/master) and [phorge/arcanist](https://github.com/phorgeit/arcanist.git).\n\n\u003e [!TIP]\n\u003e Check out this [DORA Trunk-based development](https://dora.dev/capabilities/trunk-based-development/) page if, by any chance, this is the first time you're hearing about it and interested to learn more about about this methodology.\n\n\u003e [!WARNING]\n\u003e This project was created with the help of Claude-Code and I'm using it as a \"pet project\" to try out different CC workflows. That said, I try (yeah, I know, \"do or do not...\", but you know, our desires don't always conicide with our possibiltiies) not to compromise on quality and testing. I also use this extension daily when working with github code reviews. That said, if you have any problems with code that is written by AI - you've been warned.\n\n## Installation\n\nInstall the latest release using the GitHub CLI:\n\n```bash\ngh extension install serpro69/gh-arc\n```\n\n### Installation from Source\n\n```bash\ngit clone https://github.com/serpro69/gh-arc.git\ncd gh-arc \u0026\u0026 go build . \u0026\u0026 gh extension install .\n```\n\n\u003e [!TIP]\n\u003e Clone the repo to a permanent location, gh cli will alias the binary when you run `gh extension install .` command.\n\n## Usage\n\n### Authentication\n\n`gh-arc` requires GitHub CLI authentication with specific OAuth scopes to access user information and repository data. The required _additional_ scopes are:\n\n- `user:email` - Access to user email addresses\n- `read:user` - Read user profile data\n\n#### Setting up authentication\n\n**If you're already logged in to GitHub CLI**, refresh your token with the additional required scopes:\n\n```bash\ngh auth refresh --scopes \"user:email,read:user\"\n```\n\n**If you're not logged in**, authenticate with the additional required scopes:\n\n```bash\ngh auth login --scopes \"user:email,read:user\"\n```\n\n**Alternatively**, you can provide your own personal access token:\n\n```bash\necho \"your-token-here\" | gh auth login --with-token\n```\n\n\u003e [!NOTE]\n\u003e Personal access tokens must include the `user:email` and `read:user` scopes, in addition to the scopes needed by `gh` cli itself, to work with `gh-arc`.\n\nTo verify your authentication and scopes:\n\n```bash\ngh arc auth\n```\n\n### Commands Overview\n\n`gh-arc` is a \"wrapper\" that sits on top of other tools: Github (naturally, being a github-cli extension) and Linear (if you use it for issue management instead of Github), but also linters, formatters, unit test frameworks and others. It provides a simple command-line API to manage code review and some related revision control operations.\n\nFor a detailed list of all available commands, run:\n\n```bash\ngh arc help\n```\n\nFor detailed information about a specific command, run:\n\n```bash\ngh arc help \u003ccommand\u003e\n```\n\nIn a gist, `gh arc` allows you to do things like:\n\n- get detailed help about available commands with `gh arc help`\n- create a new, short-lived, feature branch from an up-to-date `origin/HEAD` with `gh arc work`\n- send your code to Github for review with `gh arc diff`\n- show pending revision information with `gh arc list`\n- find likely reviewers for a change with `gh arc cover`\n- apply changes in a revision to the working copy with `gh arc patch`\n- download a patch from Github with `gh arc export`\n- update Git commit messages after review with `gh arc amend`\n- push changes with `gh arc land`\n- view enhanced information about Git branches with `gh arc branch`\n\nOnce you've [configured lint and unit test integration](TODO), you can also:\n\n- check your code for syntax and style errors with `gh arc lint`\n- run unit tests that cover your changes with `gh arc unit`\n\nThis extension also integrates with other tools:\n\n- create and view github gists with `gh arc gist`\n\nIt has some advanced features as well, you can:\n\n- enable tab completion with `gh arc completion`\n- ...or extend the extension and add new commands\n\n### Shell Completion\n\nGithub CLI does not currently support shell completion for extensions (See [cli/cli#5309](https://github.com/cli/cli/issues/5309)), but even if it did, who wants to type `gh arc \u003cTAB\u003e \u003cTAB\u003e \u003cTAB\u003e` ...that's just too much work if you ask me 🤷\n\nSo we've come up with a \"simple as a rock\" (is that a thing? 🤔) solution to both of the above problems 💡\n\n- Find out where github cli installs extensions on your machine. On Linux (and maybe on Mac), it's usually under `~/.local/share/gh/extensions`. \n\n- Create a simple `arc` shell script file with the following contents:\n\n    ```bash\n    #!/usr/bin/env bash\n    # Simple wrapper to enable completions for 'gh-arc' extension\n\n    gh arc \"$@\"\n    ```\n\n- Make it executable and place it on your `PATH`.\n\n- Get the completion script for your shell from the [releases](https://github.com/serpro69/gh-arc/releases/latest) page. Don't forget to source it or whatever, you know what to do.\n\n- Then try typing `arc \u003cTAB\u003e` ...you should see the command completion for the extension; and as an added bonus, you've shortened the overall `gh ...` command as well... 🤯 Who said ingenious can't be simple?\n\n- Profit... ⏱️\n\n## Configuration\n\n`gh-arc` can be configured using either JSON or YAML configuration files. The extension looks for configuration files in the following locations (in order of precedence):\n\n1. Current directory: `./.arc.json`, `./.arc.yaml`, or `./.arc.yml`\n2. User config: `~/.config/gh-arc/.arc.json`, `~/.config/gh-arc/.arc.yaml`, or `~/.config/gh-arc/.arc.yml`\n3. System-wide: `/etc/gh-arc/.arc.json`, `/etc/gh-arc/.arc.yaml`, or `/etc/gh-arc/.arc.yml`\n\nWithin each directory, JSON files take precedence over YAML files (`.arc.json` \u003e `.arc.yaml` \u003e `.arc.yml`).\n\n### Configuration Format\n\nCreate a `.arc.json` or `.arc.yaml` file in your project root or user config directory:\n\n**JSON format (`.arc.json`):**\n\n```json\n{\n  \"github\": {\n    \"defaultBranch\": \"main\",\n    \"defaultReviewers\": [],\n    \"autoAssignReviewer\": false\n  },\n  \"diff\": {\n    \"createAsDraft\": true,\n    \"autoUpdatePR\": true,\n    \"includeCommitMessages\": true,\n    \"enableStacking\": true,\n    \"defaultBase\": \"\",\n    \"showStackingWarnings\": true,\n    \"templatePath\": \"\",\n    \"requireTestPlan\": true,\n    \"linearEnabled\": false,\n    \"linearDefaultProject\": \"\"\n  },\n  \"land\": {\n    \"defaultMergeMethod\": \"squash\",\n    \"deleteLocalBranch\": true,\n    \"deleteRemoteBranch\": true,\n    \"requireApproval\": true,\n    \"requireCI\": true\n  },\n  \"output\": {\n    \"verbose\": false,\n    \"quiet\": false,\n    \"json\": false,\n    \"color\": true\n  }\n}\n```\n\n**YAML format (`.arc.yaml` or `.arc.yml`):**\n\n```yaml\ngithub:\n  defaultBranch: main\n  defaultReviewers: []\n  autoAssignReviewer: false\n\ndiff:\n  createAsDraft: true\n  autoUpdatePR: true\n  includeCommitMessages: true\n  enableStacking: true\n  defaultBase: \"\"\n  showStackingWarnings: true\n  templatePath: \"\"\n  requireTestPlan: true\n  linearEnabled: false\n  linearDefaultProject: \"\"\n\nland:\n  defaultMergeMethod: squash\n  deleteLocalBranch: true\n  deleteRemoteBranch: true\n  requireApproval: true\n  requireCI: true\n\noutput:\n  verbose: false\n  quiet: false\n  json: false\n  color: true\n```\n\n### Configuration Options\n\n#### GitHub Settings\n\n- **`github.defaultBranch`** (string, default: `\"main\"`): The default base branch for new PRs\n- **`github.defaultReviewer`** (string, default: `\"\"`): Default reviewer to assign to PRs\n- **`github.autoAssignReviewer`** (bool, default: `false`): Automatically assign the default reviewer to new PRs\n\n#### Diff (PR Creation) Settings\n\n- **`diff.createAsDraft`** (bool, default: `true`): Create PRs as drafts by default\n- **`diff.autoUpdatePR`** (bool, default: `true`): Automatically update existing PRs when running `gh arc diff`\n- **`diff.includeCommitMessages`** (bool, default: `true`): Include commit messages in PR description\n- **`diff.enableStacking`** (bool, default: `true`): Enable automatic stacked PR detection\n- **`diff.defaultBase`** (string, default: `\"\"`): Force a specific base branch (empty = auto-detect)\n- **`diff.showStackingWarnings`** (bool, default: `true`): Show warnings when dependent PRs exist\n- **`diff.templatePath`** (string, default: `\"\"`): Path to custom PR template (empty = use built-in)\n- **`diff.requireTestPlan`** (bool, default: `true`): Require test plan in PR template\n- **`diff.linearEnabled`** (bool, default: `false`): Enable Linear issue integration\n- **`diff.linearDefaultProject`** (string, default: `\"\"`): Default Linear project for issue references\n\n#### Land (Merge) Settings\n\n- **`land.defaultMergeMethod`** (string, default: `\"squash\"`): Default merge method (`squash`, `merge`, or `rebase`)\n- **`land.deleteLocalBranch`** (bool, default: `true`): Delete local branch after landing\n- **`land.deleteRemoteBranch`** (bool, default: `true`): Delete remote branch after landing\n- **`land.requireApproval`** (bool, default: `true`): Require PR approval before landing\n- **`land.requireCI`** (bool, default: `true`): Require CI checks to pass before landing\n\n#### Output Settings\n\n- **`output.verbose`** (bool, default: `false`): Enable verbose output\n- **`output.quiet`** (bool, default: `false`): Suppress non-essential output\n- **`output.json`** (bool, default: `false`): Output results in JSON format\n- **`output.color`** (bool, default: `true`): Enable colored output\n\n### Environment Variables\n\nAll configuration options can be overridden using environment variables with the `GHARC_` prefix. Use underscores to separate nested keys:\n\n```bash\n# Override diff.createAsDraft\nexport GHARC_DIFF_CREATEASDRAFT=false\n\n# Override github.defaultBranch\nexport GHARC_GITHUB_DEFAULTBRANCH=master\n\n# Override land.defaultMergeMethod\nexport GHARC_LAND_DEFAULTMERGEMETHOD=merge\n```\n\n### Advanced Configuration\n\n#### Test Runners\n\nConfigure custom test runners in your `.arc.json`:\n\n```json\n{\n  \"test\": {\n    \"runners\": [\n      {\n        \"name\": \"go-test\",\n        \"command\": \"go\",\n        \"args\": [\"test\", \"./...\"],\n        \"workingDir\": \"\",\n        \"timeout\": \"5m\"\n      }\n    ]\n  }\n}\n```\n\n#### Lint Runners\n\nConfigure custom linters:\n\n```json\n{\n  \"lint\": {\n    \"runners\": [\n      {\n        \"name\": \"golangci-lint\",\n        \"command\": \"golangci-lint\",\n        \"args\": [\"run\"],\n        \"workingDir\": \"\",\n        \"autoFix\": true\n      }\n    ],\n    \"megaLinter\": {\n      \"enabled\": \"auto\",\n      \"config\": \".mega-linter.yml\",\n      \"fixIssues\": false\n    }\n  }\n}\n```\n\n### Example: Minimal Configuration\n\nFor most projects, you only need to override a few settings:\n\n**JSON (`.arc.json`):**\n\n```json\n{\n  \"diff\": {\n    \"createAsDraft\": false,\n    \"requireTestPlan\": false\n  }\n}\n```\n\n**YAML (`.arc.yaml`):**\n\n```yaml\ndiff:\n  createAsDraft: false\n  requireTestPlan: false\n```\n\nThis configuration:\n- Creates PRs as ready-for-review by default\n- Makes the test plan field optional\n\nAll other settings will use their default values.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpro69%2Fgh-arc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserpro69%2Fgh-arc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpro69%2Fgh-arc/lists"}