![\"grit\"](\"./docs/assets/grit.svg\")
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/@arsams/grit?style=flat-square&logo=npm\")
![\"npm](\"https://img.shields.io/npm/dm/@arsams/grit?style=flat-square&logo=npm\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/arsamsarabi/grit/ci.yml?branch=main&style=flat-square&label=CI\")
![\"MIT](\"https://img.shields.io/github/license/arsamsarabi/grit?style=flat-square\")
![\"Homebrew](\"https://img.shields.io/badge/Homebrew-arsamsarabi%2Fgrit-FBB040?style=flat-square&logo=homebrew&logoColor=black\"){kind=icon}
![\"Built](\"https://img.shields.io/badge/built_with-Bun-FBF0DF?style=flat-square&logo=bun&logoColor=black\"){kind=icon}
![\"PRs](\"https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square\"){kind=icon}
\n Opinionated Git assistant with an interactive TUI and scriptable CLI.\n
\n\n**Package:** [`@arsams/grit`](https://www.npmjs.com/package/@arsams/grit) \n**Binary:** `arsams-grit` (short alias via `init`)\n\n## Demo\n\nInteractive menu with a repo status dashboard:\n\n\n\nGuided branch naming and conventional commits:\n\n\n\n## Install\n\n```bash\n# Bun (recommended)\nbun add -g @arsams/grit\n\n# npm\nnpm install -g @arsams/grit\n\n# one-shot\nbunx @arsams/grit --help\n```\n\nThen run first-time setup:\n\n```bash\narsams-grit init\n```\n\n`init` checks for `git` / `gh`, lets you pick a shell alias (and avoids clobbering an existing command on PATH), and creates `~/.config/grit/config.json`.\n\n### Homebrew\n\n```bash\nbrew install arsamsarabi/grit/grit\narsams-grit --help\n```\n\nOne command: Homebrew trusts that formula for the install. No separate `brew trust` step.\n\n## Usage\n\n```bash\n# Interactive main menu\ngrit\n\n# Scriptable commands\ngrit status\ngrit status --json\ngrit branch new --type feat --ticket TRF-123 --slug add-login\ngrit commit --all --type feat --message \"add login\" --push\ngrit push --force\ngrit pull --rebase\ngrit fetch --all --prune\ngrit revert --hash abc1234\ngrit reset --mode soft\ngrit rebase --onto origin/main\ngrit stash push --message \"wip\"\ngrit tag create --name v1.0.0 --message \"Release v1.0.0\"\ngrit diff --cached\ngrit pr create\ngrit release --tag v0.2.0\n```\n\n### Commands\n\n| Command | Description |\n| ------------------------------------ | --------------------------------------- |\n| `init` | Guided setup |\n| `branch new \\| checkout \\| delete` | Branch workflows |\n| `commit` | Conventional commits (+ optional emoji) |\n| `push` | Push commits to remote |\n| `pull` | Pull changes from remote |\n| `fetch` | Fetch from remote |\n| `status` | Dashboard (ahead/behind, files, PR) |\n| `log` | Recent history |\n| `rebase` | Rebase onto upstream |\n| `revert` | Revert a commit (pushed or unpushed) |\n| `reset` | Reset to a previous commit |\n| `stash push \\| pop \\| apply \\| list` | Stash helpers |\n| `merge` | Merge a branch |\n| `cherry-pick` | Cherry-pick a commit |\n| `worktree list \\| add \\| remove` | Worktrees |\n| `diff` | Show changes |\n| `tag list \\| create \\| delete` | Tag management |\n| `pr create \\| status` | GitHub PRs via `gh` |\n| `release` | Tag + GitHub release via `gh` |\n\n## Configuration\n\n**Precedence:** CLI flags > repo `grit.config.json` > global config\n\n| Platform | Global config path |\n| ------------- | ---------------------------- |\n| macOS / Linux | `~/.config/grit/config.json` |\n| Windows | `%APPDATA%/grit/config.json` |\n\nExample:\n\n```json\n{\n \"alias\": \"grit\",\n \"branch\": {\n \"template\": \"{type}/{ticket}-{slug}\",\n \"types\": [\"fix\", \"feat\", \"docs\", \"chore\", \"refactor\"],\n \"ticketPattern\": \"[A-Z]+-[0-9]+\"\n },\n \"commit\": {\n \"emoji\": {\n \"enabled\": false,\n \"map\": { \"feat\": \"✨\", \"fix\": \"🐛\", \"docs\": \"📝\" }\n }\n },\n \"rebase\": {\n \"defaultUpstream\": \"origin/main\",\n \"confirmForcePush\": true\n },\n \"github\": {\n \"prTemplate\": true\n }\n}\n```\n\nCommit a `grit.config.json` in your repo to share team conventions.\n\n## Project support\n\ngrit is a solo-maintained project. Issues and pull requests are welcome, and I’ll respond as time allows.\n\n## Requirements\n\n- `git` on PATH\n- [`gh`](https://cli.github.com) (optional; required for `pr` / `release`)\n- [Bun](https://bun.sh) ≥ 1.1 (development only — published installs ship a standalone binary)\n\n## Development\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide.\n\n```bash\nbun install\nbun test\nbun run lint\nbun run src/index.ts --help\nbun run compile # cross-compile standalone binaries into dist/\n```\n\nPublishing (npm + Homebrew via CI): see [docs/publishing.md](./docs/publishing.md).\n\n### Homebrew\n\n```bash\nbrew install arsamsarabi/grit/grit\narsams-grit --help\n```\n\n## Why arsams-grit?\n\nThe installed binary is `arsams-grit`. During `init` you can add a short shell alias (`grit`, `g`, `gg`, or custom) if that name is free on your PATH.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}