{"id":42553139,"url":"https://github.com/claylo/git-pm","last_synced_at":"2026-01-28T19:23:03.002Z","repository":{"id":333043785,"uuid":"1136042557","full_name":"claylo/git-pm","owner":"claylo","description":"smart wrapper for gh CLI that validates conventional commits, creates PRs, waits for checks, and auto-merges.","archived":false,"fork":false,"pushed_at":"2026-01-17T06:44:47.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T13:54:04.977Z","etag":null,"topics":["gh-cli","git","github"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/claylo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":"2026-01-17T01:00:24.000Z","updated_at":"2026-01-17T06:47:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/claylo/git-pm","commit_stats":null,"previous_names":["claylo/git-pm"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/claylo/git-pm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fgit-pm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fgit-pm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fgit-pm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fgit-pm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claylo","download_url":"https://codeload.github.com/claylo/git-pm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fgit-pm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28849878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["gh-cli","git","github"],"created_at":"2026-01-28T19:23:02.267Z","updated_at":"2026-01-28T19:23:02.996Z","avatar_url":"https://github.com/claylo.png","language":"Shell","readme":"# git-pm\n\n**Git Push \u0026 Merge** – A smart wrapper for the GitHub CLI that validates conventional commits, creates PRs, waits for checks, and auto-merges.\n\n## Why?\n\nBecause `git push \u0026\u0026 gh pr create --fill \u0026\u0026 gh pr merge --auto --squash` is:\n1. Too many commands\n2. Uses your branch name as the PR title (gross)\n3. Doesn't validate your commit messages\n4. Blindly merges without waiting for CI/CD checks\n\n`git-pm` fixes all of this. Write a proper conventional commit, run one command, and let the robot handle the rest.\n\n## Features\n\n- ✅ **Conventional Commits Validation** – Blocks pushes that don't follow the spec\n- 🎯 **Proper PR Titles** – Uses your commit message, not your branch name\n- ⏱️ **Smart Check Waiting** – Polls GitHub checks and only merges when they pass\n- 🚀 **Configurable Merge Strategy** – Squash, merge, rebase – your choice\n- 🛡️ **Fail-Fast** – Aborts immediately if checks fail\n- 🔧 **Sane Defaults** – Works out of the box with zero config\n\n## Installation\n\n### Prerequisites\n\n- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated\n- A repository with a remote on GitHub\n\n### Install the Script\n\n```bash\n# Download to somewhere in your PATH\ncurl -o ~/.local/bin/git-pm https://raw.githubusercontent.com/claylo/git-pm/main/git-pm\nchmod +x ~/.local/bin/git-pm\n\n# Or clone and symlink\ngit clone https://github.com/claylo/git-pm.git\nln -s \"$(pwd)/git-pm/git-pm\" ~/.local/bin/git-pm\n```\n\n## Usage\n\n### Basic Workflow\n\n```bash\n# Write a conventional commit\ncat \u003e commit.txt \u003c\u003c 'EOF'\nfeat: add user authentication\n\nImplemented OAuth2 flow with Google and GitHub providers.\nAdded session management and token refresh logic.\nEOF\n\n# Commit it\ngit commit -F commit.txt\n\n# Push, create PR, wait for checks, and merge\ngit pm\n```\n\nThat's it. The script will:\n1. Validate your commit follows conventional commits\n2. Push your branch\n3. Create a PR with title `feat: add user authentication`\n4. Wait for all GitHub checks to pass\n5. Auto-merge with `--auto --squash` (default)\n\n### Skip Auto-Merge\n\n```bash\nGIT_PM_MERGE=false git pm\n```\n\nThis creates the PR but doesn't merge. Useful when you want manual review.\n\n### Custom Merge Strategy\n\n```bash\n# Use merge commits instead of squash\nGIT_PM_MERGE=\"--auto --merge\" git pm\n\n# Use rebase\nGIT_PM_MERGE=\"--auto --rebase\" git pm\n\n# Just squash, no auto\nGIT_PM_MERGE=\"--squash\" git pm\n```\n\n### Different Base Branch\n\n```bash\n# Merge into 'develop' instead of 'main'\nGIT_PM_BASE=develop git pm\n\n# Combine with custom merge strategy\nGIT_PM_BASE=alpha GIT_PM_MERGE=\"--auto --rebase\" git pm\n```\n\n### Set Defaults in Your Environment\n\nAdd to your project's `.envrc` (direnv):\n\n```bash\n# Always merge into 'develop' for now\nexport GIT_PM_BASE=develop\n\n# Always use merge commits\nexport GIT_PM_MERGE=\"--auto --merge\"\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `GIT_PM_BASE` | `main` | Target branch for the pull request |\n| `GIT_PM_MERGE` | `--auto --squash` | Flags passed to `gh pr merge`. Set to `false` to skip auto-merge |\n| `GIT_PM_MAX_WAIT` | `300` | Seconds to wait for checks to pass. (Default: 5 minutes) |\n| `GIT_PM_INTERVAL` | `5` | Polling interval for checking PR checks |\n\n### Conventional Commits\n\nThe script validates that your commit message follows the [Conventional Commits](https://www.conventionalcommits.org/) specification:\n\n```\n\u003ctype\u003e[optional scope]: \u003cdescription\u003e\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Valid types:**\n- `feat` – New feature\n- `fix` – Bug fix\n- `docs` – Documentation changes\n- `style` – Code style changes (formatting, etc.)\n- `refactor` – Code refactoring\n- `perf` – Performance improvements\n- `test` – Adding or updating tests\n- `build` – Build system changes\n- `ci` – CI/CD changes\n- `chore` – Maintenance tasks\n- `revert` – Reverting changes\n\n**Examples:**\n```\nfeat: add dark mode toggle\nfix(api): resolve null pointer in user service\ndocs: update installation instructions\nfeat!: remove deprecated v1 endpoints\n```\n\nThe `!` indicates a breaking change.\n\n### Check Polling\n\nWhen auto-merge is enabled, the script:\n- Polls GitHub checks every 5 seconds\n- Waits up to 5 minutes (300 seconds) for checks to complete\n- Shows live progress: `⋯ Checks: 2 passed, 1 pending (15/300s)`\n- Merges immediately if no checks are configured\n- Aborts if any check fails\n- Times out gracefully with manual merge instructions\n\n## Examples\n\n### Standard Feature\n\n```bash\n# commit.txt\nfeat: implement file upload with progress tracking\n\nAdded drag-and-drop support and chunked uploads for large files.\nIncludes retry logic and upload resume capability.\n```\n\n```bash\ngit commit -F commit.txt\ngit pm\n```\n\n**Output:**\n```\n✓ PR created: https://github.com/user/repo/pull/42\n⏳ Waiting for PR checks to complete...\n  ⋯ Checks: 0 passed, 3 pending (5/300s)\n  ⋯ Checks: 1 passed, 2 pending (10/300s)\n  ⋯ Checks: 2 passed, 1 pending (15/300s)\n✓ All checks passed (3/3)\n🚀 Merging PR with: gh pr merge --auto --squash\n✓ Done!\n```\n\n### Bug Fix to Alpha Branch\n\n```bash\n# commit.txt\nfix(auth): prevent token refresh race condition\n\nAdded mutex lock around token refresh to prevent duplicate requests.\n```\n\n```bash\ngit commit -F commit.txt\nGIT_PM_BASE=alpha git pm\n```\n\n### Breaking Change with Manual Review\n\n```bash\n# commit.txt\nfeat!: migrate to v2 API schema\n\nBREAKING CHANGE: All API endpoints now use the /v2/ prefix.\nClients must update their base URL configuration.\n```\n\n```bash\ngit commit -F commit.txt\nGIT_PM_MERGE=false git pm\n```\n\nThis creates the PR but doesn't auto-merge, allowing for manual review of breaking changes.\n\n## Error Handling\n\n### Invalid Commit Format\n\n```bash\n$ git pm\n❌ Error: Commit message does not follow conventional commits format\n\nFirst line: Add new feature\n\nExpected format: \u003ctype\u003e[optional scope]: \u003cdescription\u003e\nValid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert\n\nExamples:\n  feat: add new feature\n  fix(api): resolve null pointer exception\n  docs: update README with installation steps\n```\n\n### Failed Checks\n\n```bash\n$ git pm\n✓ PR created: https://github.com/user/repo/pull/42\n⏳ Waiting for PR checks to complete...\n  ⋯ Checks: 2 passed, 1 pending (10/300s)\n❌ Check(s) failed. Aborting auto-merge.\n\nView details: https://github.com/user/repo/pull/42\n\n[check status output from gh pr checks]\n```\n\n### Timeout\n\n```bash\n$ git pm\n✓ PR created: https://github.com/user/repo/pull/42\n⏳ Waiting for PR checks to complete...\n  ⋯ Checks: 2 passed, 1 pending (300/300s)\n⏱️  Timeout waiting for checks. You can merge manually:\n\ngh pr merge --auto --squash\n```\n\n## When NOT to Use This\n\n- **Large teams with complex review processes** – This is optimized for solo devs or small teams with automated checks\n- **Repos without CI/CD** – The smart waiting is overkill if you have no checks\n- **When you need multi-commit PRs** – This assumes one commit = one PR\n- **Complex PR templates** – The script uses minimal PR metadata\n\nFor those cases, just use `gh pr create` directly.\n\n## Troubleshooting\n\n### \"command not found: git-pm\"\n\nMake sure the script is:\n1. In a directory that's in your `$PATH`\n2. Executable (`chmod +x git-pm`)\n3. Named exactly `git-pm` (no `.sh` extension)\n\n### \"gh: command not found\"\n\nInstall the [GitHub CLI](https://cli.github.com/):\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh  # Debian/Ubuntu\nsudo dnf install gh  # Fedora\n\n# Windows\nwinget install GitHub.cli\n```\n\nThen authenticate:\n```bash\ngh auth login\n```\n\n### Checks Never Complete\n\nIf polling times out but checks are still running:\n1. Increase `GIT_PM_MAX_WAIT` in the environment\n2. Check your CI/CD configuration for hanging jobs\n3. Manually merge: `gh pr merge --auto --squash`\n\n## Development\n\nWant to modify the script? Here's the structure:\n\n1. **Validation** – Extracts and validates conventional commit format\n2. **Push** – Pushes current branch to remote\n3. **PR Creation** – Creates PR with explicit title/body from commit\n4. **Check Polling** – Waits for GitHub checks using `gh pr view --json`\n5. **Merge** – Auto-merges with configurable strategy\n\nThe script is pure Bash with no external dependencies except `gh` and standard Unix tools (`grep`, `sed`, `head`, `tail`).\n\n## Contributing\n\nPRs welcome! Please:\n1. Follow conventional commits (meta!)\n2. Test on both macOS and Linux\n3. Keep it dependency-free (except `gh`)\n4. Add examples to this README for new features\n\n## License\n\nMIT © 2026 Clay Loveless\n\n## See Also\n\n- [Conventional Commits](https://www.conventionalcommits.org/)\n- [GitHub CLI](https://cli.github.com/)\n- [Cocogitto](https://github.com/cocogitto/cocogitto) – For conventional commits-based versioning\n- [Commitizen](https://github.com/commitizen/cz-cli) – Interactive conventional commit tool\n\n---\n\n**Made with ☕ by a developer tired of typing the same 5 commands.**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fgit-pm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaylo%2Fgit-pm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fgit-pm/lists"}