@johnowennixon/diffdash 1.0.0

package/README.md

@@ -0,0 +1,174 @@
+# DiffDash
+
+A command-line tool to generate Git commit messages using AI.
+
+## Features
+
+* Generates Git commit messages in natural English
+* Adds a footer to the generated commit messages
+* Options to disable or auto-approve various stages of the process
+* Able to add a prefix or suffix to the summary line
+* Optionally select from a choice of LLM models
+* Compare messages generated from all configured models
+* Configuration using standard API provider environment variables
+* Uses the Vercel AI SDK
+* Uses structured JSON with compatible models
+* Substantially written using AI coding (Claude Code, Roo Code, and Amp)
+
+## Installation from npmjs.com
+
+```bash
+npm install -g @johnowennixon/diffdash
+```
+
+## API Keys
+
+DiffDash requires at least one API key for an LLM provider. These must be provided as environment variables.
+
+```bash
+# For Anthropic
+export ANTHROPIC_API_KEY=your-api-key
+
+# For DeepSeek
+export DEEPSEEK_API_KEY=your-api-key
+
+# For Google Gemini
+export GEMINI_API_KEY=your-api-key
+
+# For OpenAI
+export OPENAI_API_KEY=your-api-key
+
+# For Requesty
+export REQUESTY_API_KEY=your-api-key
+
+# For OpenRouter
+export OPENROUTER_API_KEY=your-api-key
+```
+
+## Usage
+
+```bash
+# Basic usage (uses defaults)
+diffdash
+
+# Add a prefix to the commit message summary line
+diffdash --add-prefix "[FIX]"
+
+# Add a suffix to the commit message summary line
+diffdash --add-suffix "(closes #123)"
+
+# Automatically stage all changes, but still prompt for commit and push
+diffdash --auto-add
+
+# Automatically stage and commit changes, but still prompt for push
+diffdash --auto-add --auto-commit
+
+# Fully automated workflow (stage, commit, and push without prompts)
+diffdash --auto-add --auto-commit --auto-push
+
+# Generate message for already staged changes only (won't stage any new changes)
+diffdash --disable-add
+
+# Skip displaying the status of staged files before commit
+diffdash --disable-status
+
+# Don't display the generated commit message
+diffdash --disable-preview
+
+# Generate message but don't commit (exit after displaying the message)
+diffdash --disable-commit
+
+# Generate message and commit, but don't push or prompt to push
+diffdash --disable-push
+
+# Skip git hooks when pushing
+diffdash --no-verify
+
+# Display commit messages generated by all models
+diffdash --compare
+
+# Use the fallback LLM model
+diffdash --llm-fallback
+
+# Specify the LLM model by name
+diffdash --llm-model claude-3.5-haiku
+
+# Debug options
+diffdash --debug-llm-inputs --debug-llm-outputs
+```
+
+## Command Line Arguments
+
+All command-line arguments are optional.
+
+| Argument | Description |
+|--------|-------------|
+| `--help` | show a help message and exit |
+| `--version` | show program version information and exit |
+| `--add-prefix PREFIX` | add a prefix to the commit message summary line |
+| `--add-suffix SUFFIX` | add a suffix to the commit message summary line |
+| `--auto-add` | automatically stage all changes without confirmation |
+| `--auto-commit` | automatically commit changes without confirmation |
+| `--auto-push` | automatically push changes after commit without confirmation |
+| `--disable-add` | disable adding unstaged changes - exit if no changes staged |
+| `--disable-status` | disable listing the staged files before generating a message |
+| `--disable-preview` | disable previewing the generated message|
+| `--disable-commit` | disable committing changes - exit after generating the message |
+| `--disable-push` | disable pushing changes - exit after making the commit |
+| `--push-no-verify` | bypass git hooks when pushing to Git |
+| `--push-force` | apply force when pushing to Git |
+| `--llm-list` | display a list of available Large Language Models and exit |
+| `--llm-compare` | compare the generated messages from all models - but do not commit |
+| `--llm-router` | prefer to access the LLM via a router rather than direct |
+| `--llm-fallback` | use the fallback LLM model instead of the default |
+| `--llm-model MODEL` | choose the LLM model by name (the default is normally best) |
+| `--llm-excludes MODELS` | models to exclude from comparison (comma separated) |
+| `--silent` | suppress all normal output - errors and aborts still display |
+| `--debug-llm-inputs` | show inputs (including all prompts) sent to the LLM |
+| `--debug-llm-outputs` | show outputs received from the LLM |
+
+## Files containing secrets
+
+Files containing secrets should probably not be in Git. But if they are, you can add an entry to a `.gitattributes` file with value `-diff` to prevent them being viewable by a Git diff. This will prevent DiffDash from sending any contents to the LLM. For example:
+
+```text
+# This is file .gitattributes
+
+.env  -diff
+```
+
+## Development
+
+To install on your laptop:
+
+```bash
+# Clone the repository
+git clone https://github.com/johnowennixon/diffdash.git
+cd diffdash
+
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm run build
+
+# Make binaries executable
+npm link
+```
+
+To rebuild after editing:
+
+```bash
+# Lint the code
+pnpm run lint
+
+# Fix formatting issues (if required)
+pnpm run fix
+
+# Build the project
+pnpm run build
+```
+
+## License
+
+0BSD