gitxplain 0.1.3 → 0.1.8

package/README.md

@@ -18,8 +18,10 @@ Supported providers:
 - Supports AI-assisted commit splitting plans, with optional execution for the latest commit
 - Supports release-branch merge previews driven by detected version bumps in diffs
 - Supports automatic release tagging driven by the same version-bump detection used for release merges
+- Supports release health status checks that show missing tags, unmerged version bumps, branch drift, and next steps
 - Supports AI-assisted commit planning for uncommitted working tree changes
 - Supports quick repository log output for full history inspection
+- Supports repository-aware CI/CD workflow generation for the repo you are currently in
 - Supports single commits, commit ranges, and branch-vs-base comparisons
 - Truncates oversized diffs before sending them to the model and reports that truncation
 - Streams output for supported providers
@@ -27,7 +29,6 @@ Supported providers:
 - Supports plain, JSON, Markdown, and HTML output
 - Supports clipboard copy, verbosity controls, and hook installation
 - Supports project-level and user-level config files
-- Falls back to an interactive prompt when no analysis flag is supplied
 - Returns plain text or JSON output
 - Uses native Node APIs only, so the MVP has no runtime dependencies
 
@@ -37,7 +38,7 @@ Supported providers:
 - A Git repository in your current working directory
 - An API key for your chosen provider, or a local Ollama instance
 
-Optional environment variables:
+Optional advanced environment variables:
 
 - `LLM_PROVIDER` default: `openai`
 - `LLM_MODEL` optional shared model override
@@ -53,7 +54,7 @@ Optional environment variables:
 Optional config files:
 
 - Project: `.gitxplainrc` or `.gitxplainrc.json`
-- User: `~/.gitxplain/config.json`
+- User: `~/.gitxplain/config.json` on macOS/Linux, or `%USERPROFILE%\.gitxplain\config.json` on Windows
 
 You can start from:
 
@@ -63,74 +64,344 @@ cp .env.example .env
 
 ## Usage
 
+Show the built-in command reference.
+
+```bash
+gitxplain --help
+```
+
+Save the default AI provider.
+
+```bash
+gitxplain config set provider <name>
+```
+
+Save the API key for a provider.
+
+```bash
+gitxplain config set api-key <value> [--provider <name>]
+```
+
+Print one saved config value, or all of them.
+
+```bash
+gitxplain config get [key]
+```
+
+List saved user config values.
+
+```bash
+gitxplain config list
+```
+
+Analyze a single commit.
+
+```bash
+gitxplain <commit-id> [options]
+```
+
+Analyze a commit range.
+
+```bash
+gitxplain <start>..<end> [options]
+```
+
+Compare the current branch to a base branch.
+
+```bash
+gitxplain --branch [base-ref] [options]
+```
+
+Compare the current branch like a PR.
+
+```bash
+gitxplain --pr [base-ref] [options]
+```
+
+Plan commits for uncommitted working tree changes.
+
 ```bash
-gitxplain help
-gitxplain commit
 gitxplain --commit
-gitxplain merge
+```
+
+Show release branch health and next steps.
+
+```bash
+gitxplain --release [status]
+```
+
+Preview or execute a release merge.
+
+```bash
 gitxplain --merge
-gitxplain tag
+```
+
+Preview or create release tags.
+
+```bash
 gitxplain --tag
-gitxplore tag
-gitxplore --tag
-gitxplain log --log
-gitxplain status
+```
+
+Print repository log output.
+
+```bash
+gitxplain --log
+```
+
+Print repository status output.
+
+```bash
 gitxplain --status
-gitxplain add README.md
-gitxplain remove README.md
-gitxplain del scratch.txt
-gitxplain pop
-gitxplain pop 2
-gitxplain push
-gitxplain push origin main
-gitxplain <commit-id>
-gitxplain <commit-id> --summary
-gitxplain <commit-id> --issues
-gitxplain <commit-id> --fix
-gitxplain <commit-id> --impact
-gitxplain <commit-id> --full
-gitxplain <commit-id> --lines
-gitxplain <commit-id> --review
-gitxplain <commit-id> --security
-gitxplain <commit-id> --split
-gitxplain --commit --execute
-gitxplain merge
-gitxplain --merge --execute
-gitxplain tag
-gitxplain --tag --execute
-gitxplain <commit-id> --json
-gitxplain <commit-id> --markdown
-gitxplain <commit-id> --html
-gitxplain <commit-id> --stream
-gitxplain <commit-id> --clipboard
-gitxplain <commit-id> --verbose
-gitxplain <commit-id> --quiet
-gitxplain log --log
-gitxplain <start>..<end> --markdown
-gitxplain --branch main --review
-gitxplain --pr origin/main --security
-gitxplain install-hook
-gitxplain <commit-id> --provider openrouter --model anthropic/claude-3.7-sonnet
-gitxplain <commit-id> --provider chutes --model deepseek-ai/DeepSeek-V3-0324
-gitxplain <commit-id> --split --execute
 ```
 
-Examples:
+Detect and generate CI/CD workflow files.
+
+```bash
+gitxplain --pipeline
+```
+
+Analysis:
+
+Generate a one-line summary.
+
+```bash
+--summary
+```
+
+Focus on the issue being fixed.
+
+```bash
+--issues
+```
+
+Explain the fix in simple terms.
+
+```bash
+--fix
+```
+
+Explain behavior changes before vs after.
+
+```bash
+--impact
+```
+
+Generate the full structured analysis.
+
+```bash
+--full
+```
+
+Walk through the changed code file by file.
+
+```bash
+--lines
+```
+
+Generate review findings and risks.
+
+```bash
+--review
+```
+
+Focus on security-relevant changes.
+
+```bash
+--security
+```
+
+Propose splitting a commit into smaller commits.
+
+```bash
+--split
+```
+
+Propose commits for current working tree changes.
+
+```bash
+--commit
+```
+
+Apply a split, commit, merge, or tag plan.
+
+```bash
+--execute
+```
+
+Preview a plan without applying it.
+
+```bash
+--dry-run
+```
+
+Release:
+
+Show release status details.
+
+```bash
+--release [status]
+```
+
+Preview or apply a merge into the release branch.
+
+```bash
+--merge
+```
+
+Preview or create release tags from version bumps.
+
+```bash
+--tag
+```
+
+Repo:
+
+Print the current repository log.
+
+```bash
+--log
+```
+
+Print the current working tree status.
+
+```bash
+--status
+```
+
+Inspect the repo and create CI/CD workflow files.
+
+```bash
+--pipeline
+```
+
+Quick Actions:
+
+Persist provider, model, and API key settings.
+
+```bash
+config
+```
+
+Stage one or more files.
+
+```bash
+add
+```
+
+Unstage one or more files.
+
+```bash
+remove
+```
+
+Hard reset the repository to HEAD.
+
+```bash
+remove hard
+```
+
+Delete one or more files from the working tree.
+
+```bash
+del
+```
+
+Soft reset `HEAD~1` and keep your changes.
+
+```bash
+bin
+```
+
+Pop a stash entry.
+
+```bash
+pop
+```
+
+Run `git pull`.
+
+```bash
+pull
+```
+
+Run `git push`.
+
+```bash
+push
+```
+
+Install the `gitxplain` hook.
+
+```bash
+install-hook
+```
+
+Pass through to native Git commands.
+
+```bash
+git
+```
+
+Output:
+
+Override the configured provider for one command.
+
+```bash
+--provider <name>
+```
+
+Override the configured model for one command.
+
+```bash
+--model <name>
+```
+
+Return JSON output.
+
+```bash
+--json
+```
+
+Return Markdown output.
+
+```bash
+--markdown
+```
+
+Return HTML output.
+
+```bash
+--html
+```
+
+Reduce extra console output.
+
+```bash
+--quiet
+```
+
+Show extra response metadata.
+
+```bash
+--verbose
+```
+
+Copy the final output to the clipboard.
+
+```bash
+--clipboard
+```
+
+Stream model output as it arrives.
+
+```bash
+--stream
+```
+
+Limit diff size before sending it to the model.
 
 ```bash
-npm start -- HEAD~1 --summary
-npm start -- commit
-npm start -- merge
-npm start -- tag
-npm start -- log --log
-npm start -- a1b2c3d --full
-npm start -- HEAD~1 --lines
-npm start -- HEAD~5..HEAD --markdown
-npm start -- --branch main --review
-npm start -- HEAD~1 --provider groq --model llama-3.3-70b-versatile
-npm start -- HEAD~1 --provider gemini --model gemini-2.5-flash
-npm start -- HEAD~1 --provider chutes --model deepseek-ai/DeepSeek-V3-0324
-npm start -- HEAD --split --execute
+--max-diff-lines <n>
 ```
 
 ## Running The CLI
@@ -138,14 +409,15 @@ npm start -- HEAD --split --execute
 To use the actual `gitxplain` command directly:
 
 ```bash
-cd /home/guru/Dev/gitxplain
 npm link
 ```
 
+Run that from the repository root. `npm link` works on Windows, macOS, and Linux, though it may require elevated privileges depending on your Node/npm install prefix.
+
 Then from any Git repository:
 
 ```bash
-gitxplain help
+gitxplain --help
 gitxplain HEAD~1 --full
 gitxplain a1b2c3d --summary
 gitxplain HEAD~1 --lines
@@ -153,19 +425,10 @@ gitxplain HEAD~5..HEAD --markdown
 gitxplain --branch main --review
 ```
 
-The `gitxplain help` command also prints quick API-key setup examples for:
-
-- OpenAI
-- Groq
-- OpenRouter
-- Gemini
-- Ollama
-- Chutes AI
-
 If you do not want to link it globally, you can still run it locally:
 
 ```bash
-node /home/guru/Dev/gitxplain/cli/index.js HEAD~1 --full
+node ./cli/index.js HEAD~1 --full
 ```
 
 ## Output Modes
@@ -181,43 +444,63 @@ node /home/guru/Dev/gitxplain/cli/index.js HEAD~1 --full
 - `--split`: propose how to split a commit into multiple atomic commits
 - `--merge`: preview or execute a merge into the `release` branch based on detected version bumps
 - `--tag`: preview or create release tags from the same detected version windows
+- `--release [status]`: inspect release branch health, missing tags, source-vs-release drift, and the next recommended action
 - `--commit`: propose commits for current uncommitted changes
 - `--log`: print Git log entries for the current repository
 - `--status`: print Git working tree status for the current repository
+- `--pipeline`: inspect the current repository and generate GitHub Actions CI/CD workflows
 - `--execute`: apply a proposed split by rewriting history
 - `--dry-run`: preview the split or commit plan without applying it
 - `--json`: return structured JSON instead of formatted text
 - `--markdown`: return Markdown output
 - `--html`: return HTML output
 
-If no analysis flag is supplied, the CLI asks what kind of explanation you want.
-
 ## Repository Log
 
 Print recent log entries from the current repository:
 
 ```bash
-gitxplain log
 gitxplain --log
 ```
 
-Both forms print the repository history in a compact one-line format using the current repository, without calling the LLM.
+This prints the repository history in a compact one-line format using the current repository, without calling the LLM.
 
 ## Quick Actions
 
 Run a few common Git actions directly through `gitxplain`:
 
 ```bash
-gitxplain status
+gitxplain --status
 gitxplain add README.md
 gitxplain remove README.md
+gitxplain remove hard
 gitxplain del scratch.txt
+gitxplain bin
 gitxplain pop
 gitxplain pop 2
+gitxplain pull
+gitxplain pull origin main
 gitxplain push
 gitxplain push origin main
 ```
 
+For native Git commands that do not have a custom `gitxplain` workflow, use them directly:
+
+```bash
+gitxplain branch -a
+gitxplain checkout -b feature/demo
+gitxplain rebase origin/main
+gitxplain worktree list
+```
+
+If you want to force native Git for a reserved custom command name, use the `git` wrapper:
+
+```bash
+gitxplain git commit -m "native commit message"
+gitxplain git merge feature/demo
+gitxplain git tag -a v1.2.3 -m "release"
+```
+
 ## Comparison Modes
 
 Single commit:
@@ -270,7 +553,6 @@ Warning: `--split --execute` rewrites history. If the commit was already pushed,
 Preview the release merge plan for the current branch:
 
 ```bash
-gitxplain merge
 gitxplain --merge
 ```
 
@@ -287,9 +569,7 @@ This command scans commits on your current branch after the branch split point a
 Preview the release tags for the current branch:
 
 ```bash
-gitxplain tag
 gitxplain --tag
-gitxplore tag
 gitxplore --tag
 ```
 
@@ -300,14 +580,13 @@ gitxplain --tag --execute
 gitxplore --tag --execute
 ```
 
-This command uses the same release-window detection as `merge`. It scans commits on your current branch after the branch split point, detects version bumps from version-file diffs, and maps each unreleased version to the last commit in that release window. By default it creates annotated tags named exactly after the detected version, such as `1.2.3`.
+This command scans the full history of your current branch, detects version bumps from version-file diffs, and maps each untagged detected version to the last commit in that version window. It works independently from the `merge` workflow and does not require a `release` branch. By default it creates annotated tags named exactly after the detected version, such as `1.2.3`.
 
 ## Commit Working Tree
 
 Preview how the current uncommitted changes should be committed:
 
 ```bash
-gitxplain commit
 gitxplain --commit
 ```
 
@@ -343,6 +622,15 @@ Example `.gitxplainrc`:
 
 CLI flags still override config values for a single command.
 
+You can also save provider settings permanently with the CLI:
+
+```bash
+gitxplain config set provider openai
+gitxplain config set api-key your_key
+gitxplain config set model gpt-4.1-mini
+gitxplain config list
+```
+
 ## Clipboard, Streaming, And Hooks
 
 Copy the final output to your clipboard:
@@ -365,48 +653,34 @@ gitxplain install-hook
 
 ## Provider Setup
 
-OpenAI:
+Recommended persistent setup:
 
 ```bash
-export LLM_PROVIDER=openai
-export OPENAI_API_KEY=your_key
+gitxplain config set provider openai
+gitxplain config set api-key your_key
 ```
 
-Groq:
+You can also save a default model:
 
 ```bash
-export LLM_PROVIDER=groq
-export GROQ_API_KEY=your_key
+gitxplain config set model gpt-4.1-mini
 ```
 
-OpenRouter:
+You can switch providers later:
 
 ```bash
-export LLM_PROVIDER=openrouter
-export OPENROUTER_API_KEY=your_key
+gitxplain config set provider groq
+gitxplain config set api-key your_key
 ```
 
-Gemini:
+If you want to inspect what is saved:
 
 ```bash
-export LLM_PROVIDER=gemini
-export GEMINI_API_KEY=your_key
+gitxplain config list
+gitxplain config get provider
 ```
 
-Ollama:
-
-```bash
-export LLM_PROVIDER=ollama
-export OLLAMA_MODEL=llama3.2
-```
-
-Chutes AI:
-
-```bash
-export LLM_PROVIDER=chutes
-export CHUTES_API_KEY=your_key
-export CHUTES_MODEL=deepseek-ai/DeepSeek-V3-0324
-```
+Saved user settings live in `~/.gitxplain/config.json` on macOS/Linux, or `%USERPROFILE%\.gitxplain\config.json` on Windows.
 
 ## Development
 
@@ -420,3 +694,5 @@ To make the command globally available during local development:
 ```bash
 npm link
 ```
+
+Run this from the repository root. On some systems, you may need an elevated shell depending on where npm installs global links.