gut-cli 0.1.9 → 0.1.11

package/README.md

@@ -2,6 +2,14 @@
 
 **Git Utility Tool** - AI-powered git commands for smarter workflows.
 
+## Why gut?
+
+Working with git involves many small decisions that add up: writing clear commit messages, naming branches, describing pull requests, coming up with stash names you'll actually remember. These tasks aren't hard, but they interrupt your flow and take more time than they should.
+
+gut handles these for you. Unlike AI coding assistants that analyze your entire codebase, gut focuses only on git operations—so it's fast. You get results in seconds, not minutes.
+
+No subscription required. Just bring your own API key from Gemini, OpenAI, or Anthropic. Your keys are stored securely in your system's native keychain, never in plain text.
+
 ## Installation
 
 ```bash
@@ -10,22 +18,23 @@ npm install -g gut-cli
 
 ## Commands
 
-All AI commands support short aliases (without `ai-` prefix):
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `gut ai-commit` | `gut commit` | Generate commit messages |
-| `gut ai-pr` | `gut pr` | Generate PR descriptions |
-| `gut ai-review` | `gut review` | Code review |
-| `gut ai-merge` | `gut merge` | Resolve merge conflicts |
-| `gut ai-explain` | `gut explain` | Explain changes, commits, PRs, or files |
-| `gut ai-find` | `gut find` | Find commits by vague description |
-| `gut ai-branch` | `gut branch` | Generate branch names from description |
-| `gut changelog` | - | Generate changelogs |
-| `gut sync` | - | Sync with remote (fetch + rebase/merge) |
-| `gut stash` | - | Stash with AI-generated names |
-| `gut config` | - | Manage configuration (language, etc.) |
-| `gut lang` | - | Set or show output language |
+| Command | Description |
+|---------|-------------|
+| `gut commit` | Generate commit messages |
+| `gut pr` | Generate PR descriptions |
+| `gut review` | Code review |
+| `gut merge` | Resolve merge conflicts |
+| `gut explain` | Explain changes, commits, PRs, or files |
+| `gut find` | Find commits by vague description |
+| `gut branch` | Generate branch names from description |
+| `gut checkout` | Generate branch name from diff and checkout |
+| `gut changelog` | Generate changelogs |
+| `gut sync` | Sync with remote (fetch + rebase/merge) |
+| `gut stash` | Stash with AI-generated names |
+| `gut summary` | Generate work summary (daily/weekly reports) |
+| `gut config` | Manage configuration (language, etc.) |
+| `gut lang` | Set or show output language |
+| `gut init` | Initialize .gut/ templates in your project |
 
 ### `gut commit`
 
@@ -45,11 +54,7 @@ gut commit --all
 gut commit --provider openai
 ```
 
-**Commit Convention Support**: If a convention file exists in your repo, gut will follow it:
-- `.gut/commit-convention.md`
-- `.github/commit-convention.md`
-- `.commit-convention.md`
-- `.gitmessage`
+**Template Support**: Create `.gut/commit.md` to customize the commit message prompt.
 
 ### `gut pr`
 
@@ -69,7 +74,7 @@ gut pr --create
 gut pr --copy
 ```
 
-**PR Template Support**: Automatically uses `.github/pull_request_template.md` if present.
+**Template Support**: Automatically uses GitHub's `.github/pull_request_template.md` if present, or falls back to `.gut/pr.md`.
 
 ### `gut review`
 
@@ -191,7 +196,27 @@ gut branch 123 --type fix
 gut branch -d "add user authentication"
 ```
 
-**Branch Convention Support**: Create `.gut/branch-convention.md` for custom naming rules.
+**Template Support**: Create `.gut/branch.md` for custom naming rules.
+
+### `gut checkout`
+
+Generate a branch name from current diff and checkout.
+
+```bash
+# Generate branch name from uncommitted changes
+gut checkout
+
+# Auto-checkout without confirmation
+gut checkout --yes
+
+# Use only staged changes
+gut checkout --staged
+
+# Use specific provider
+gut checkout --provider openai
+```
+
+**Template Support**: Create `.gut/checkout.md` to customize the prompt.
 
 ### `gut sync`
 
@@ -241,6 +266,46 @@ gut stash --drop 1
 gut stash --clear
 ```
 
+### `gut summary`
+
+Generate a work summary from your commits (for daily/weekly reports).
+
+```bash
+# Today's summary (default: your commits)
+gut summary
+
+# Daily report
+gut summary --daily
+
+# Weekly report
+gut summary --weekly
+
+# Custom date range
+gut summary --since "2024-01-01" --until "2024-01-31"
+
+# Include diff for more detail
+gut summary --weekly --with-diff
+
+# Output as markdown (great for Slack/docs)
+gut summary --weekly --markdown
+
+# Copy to clipboard
+gut summary --daily --copy
+
+# Specify different author
+gut summary --author "John Doe"
+```
+
+**Options:**
+- `--daily` - Generate daily report (since today)
+- `--weekly` - Generate weekly report (since 1 week ago)
+- `--since <date>` - Start date (default: today)
+- `--until <date>` - End date
+- `--author <author>` - Filter by author (default: current git user)
+- `--with-diff` - Include diff analysis for more detail
+- `--markdown` - Output as markdown
+- `--copy` - Copy to clipboard
+
 ### `gut changelog`
 
 Generate a changelog from commits.
@@ -259,7 +324,7 @@ gut changelog --tag v1.0.0
 gut changelog --json
 ```
 
-**Changelog Template Support**: If `CHANGELOG.md` exists, gut will match its style.
+**Template Support**: Create `.gut/changelog.md` to customize the changelog format.
 
 ### `gut lang`
 
@@ -304,6 +369,26 @@ gut config get lang
 1. Local: `.gut/config.json` (per-repository)
 2. Global: `~/.config/gut/config.json`
 
+### `gut init`
+
+Initialize `.gut/` templates in your project for customization.
+
+```bash
+# Copy all templates to .gut/ (translates if language is not English)
+gut init
+
+# Force overwrite existing templates
+gut init --force
+
+# Skip translation (copy English templates as-is)
+gut init --no-translate
+
+# Use specific provider for translation
+gut init --provider openai
+```
+
+Templates are automatically translated to your configured language (set via `gut lang`).
+
 ### `gut cleanup`
 
 Delete merged branches safely.
@@ -344,21 +429,35 @@ API keys can also be set via environment variables:
 - `GUT_OPENAI_API_KEY` or `OPENAI_API_KEY`
 - `GUT_ANTHROPIC_API_KEY` or `ANTHROPIC_API_KEY`
 
+## Security
+
+API keys are stored securely using your operating system's native credential storage:
+
+- **macOS**: Keychain
+- **Windows**: Credential Vault
+- **Linux**: Secret Service API (libsecret)
+
+Keys are never stored in plain text files or configuration files. When you run `gut auth login`, the key is encrypted and managed by your OS.
+
 ## Project Configuration
 
-gut looks for these configuration files in your repository:
+gut looks for template files in your repository's `.gut/` folder. Each template uses `{{variable}}` syntax for dynamic content.
 
 | File | Purpose |
 |------|---------|
-| `.gut/commit-convention.md` | Custom commit message rules |
-| `.gut/pr-template.md` | PR description template |
-| `.gut/changelog-template.md` | Changelog style template |
-| `.gut/merge-strategy.md` | Merge conflict resolution rules |
-| `.gut/explain.md` | Project context for explanations |
-| `.gut/find.md` | Project context for commit search |
-| `.gut/branch-convention.md` | Custom branch naming rules |
-| `.github/pull_request_template.md` | PR template (fallback) |
-| `CHANGELOG.md` | Changelog style (fallback) |
+| `.gut/commit.md` | Commit message prompt |
+| `.gut/pr.md` | PR description prompt |
+| `.gut/branch.md` | Branch naming rules |
+| `.gut/checkout.md` | Checkout branch name prompt |
+| `.gut/merge.md` | Merge conflict resolution rules |
+| `.gut/review.md` | Code review criteria |
+| `.gut/explain.md` | Explanation context |
+| `.gut/explain-file.md` | File explanation context |
+| `.gut/find.md` | Commit search context |
+| `.gut/changelog.md` | Changelog format |
+| `.gut/stash.md` | Stash name prompt |
+| `.gut/summary.md` | Work summary format |
+| `.github/pull_request_template.md` | GitHub PR template (prioritized over `.gut/pr.md`) |
 
 ## Development