gh-commit

gh-commit

A fast, GitHub-native CLI tool to commit files using the GitHub API.

✨ Overview

gh-commit is a GitHub CLI extension that allows you to commit changes directly to your repositories using the GitHub API. It is ideal for use in ephemeral environments, CI workflows, or anywhere you want fast, authenticated commits without a local Git identity.

Supports both direct commits and pull request-based workflows.

🚀 Features

• 📂 Commit selected files or all changes
• 📎 Create commits using the GitHub API (signed in CI)
• 🌟 Automatically create branches and PRs
• 🔍 Smart file detection (staged, tracked, untracked)
• ✨ Fully styled CLI output with colorized logging

💡 Usage

gh commit [files...] -B <branch> -m <message> [flags]

Example

Commit all changes:

gh commit -B main -A -m "fix: update configs"

Create a PR from a new branch:

gh commit -B main -A -P -T "Update Configs" -D "This PR updates the configs." -l feature -l ci

Dry run (shows what would be committed):

gh commit -B main -A -d

🔧 Flags

📆 GitHub Actions

- name: Commit and Push Changes
  run: |
    gh commit -B main -A -m "ci: auto-commit"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Signed commits are automatically created when using GitHub Actions.

🔄 Base Commit and Fast-Forward

The --base-commit flag allows you to specify a specific commit SHA to use as the base for your new commit. This is particularly useful for:

• Avoiding duplicate commits after rebases
• Simulating force pushes without actually force pushing
• Maintaining clean commit history in PRs

Usage Examples

Basic base commit usage:

gh commit -B main -m "fix: update configs" -b a1b2c3d4e5f6789012345678901234567890abcd file.txt

With fast-forward (simulates force push):

gh commit -B main -m "fix: update configs" -b a1b2c3d4e5f6789012345678901234567890abcd -f file.txt

How It Works

• --base-commit only: Creates a new commit on top of the specified commit, but doesn't modify the branch pointer
• --base-commit + --allow-fast-forward: Fast-forwards the branch to the specified commit, then creates the new commit on top

This effectively simulates a force push by allowing you to "rewrite history" from a specific point, preventing the "Update is not a fast forward" error.

📂 Project Structure

• cmd/
  • CLI definitions and flag parsing
  • Commit/PR creation logic

🚨 Errors & Validation

• Ensures repo has a remote and is a Git repo
• Validates presence of commit message and branch
• Prevents mixed usage of --all, --untracked, and file args
• PRs auto-create branches if not found
• Label validation before PR creation

📄 License

MIT © github.com/kassett

🌐 Links

• GitHub: kassett/gh-commit
• GH CLI: cli.github.com