# noto noto (/nōto/, meaning "notebook" in Japanese) is a command-line tool that generates commit messages for your Git projects. It analyzes your staged changes and uses Gemini to create clean, context-aware commit messages instantly. ## Why noto? Writing good commit messages is hard. We've all been there: - Staring at a blank commit message box, unsure what to write - Defaulting to vague messages like "fix bug" or "update stuff" - Struggling to maintain consistency across team commits - Spending more time writing commit messages than actually coding noto solves this by doing the thinking for you. It analyzes your actual code changes and generates meaningful, professional commit messages in seconds—so you can focus on what matters: writing great code. ## Features - **Lightning Fast** - Generate messages in seconds, not minutes - **Context-Aware** - Analyzes actual code changes, not just file names - **Customizable Guidelines** - Define your own commit message style with `noto init` - **Git Integration** - Apply, edit, or copy messages directly - **Smart Defaults** - Works great out of the box, customizable when you need it - **Message Caching** - Reuses cached messages for the same changes to save time and API costs - **Branch Management** - Switch, create, and manage branches with ease - **Auto Upgrades** - Keep noto up to date with the latest features ## Installation ### Prerequisites - Node.js (v18 or higher) - Git installed and configured - A Gemini API key from Google AI Studio (https://aistudio.google.com/app/apikey) ### Quick Install Install noto globally using your package manager of choice: ```bash npm install -g @snelusha/noto ``` Or using Homebrew: ```bash brew install snelusha/noto/noto ``` Verify installation: ```bash noto --version ``` ### API Key Setup noto needs a Gemini API key to generate commit messages. You have two options: #### Option 1: Environment Variable (Recommended) Add your API key to your shell configuration: ```bash export NOTO_API_KEY="your-gemini-api-key-here" ``` For macOS/Linux, add to `.bashrc`, `.zshrc`, or `.profile`: ```bash export NOTO_API_KEY="your-gemini-api-key-here" ``` Then reload your terminal: ```bash source ~/.zshrc # or ~/.bashrc or ~/.profile ``` For Windows (PowerShell): ```bash setx NOTO_API_KEY "your-gemini-api-key-here" ``` #### Option 2: Local Configuration Set your API key using noto's config command: ```bash noto config key "your-gemini-api-key-here" ``` This stores the key in `~/.config/noto/.notorc` following XDG standards. > noto first checks for the NOTO_API_KEY environment variable. If not found, it falls back to the local configuration. ## Configuration ### Model Selection noto uses `gemini-2.5-flash-lite` by default. To change the model: ```bash noto config model ``` ### Reset Configuration Reset all noto configurations to defaults: ```bash noto config reset ``` ### Custom Commit Prompts Every project has its own commit style. The `noto init` command analyzes your existing commit history and generates a custom prompt that matches your project's style: ```bash noto init ``` Available flags: - `--root` - Create the prompt file in the git root - `--generate` - Generate prompt from existing commits (requires 5+ commits) Examples: ```bash noto init --root # Create in git root noto init --generate # Generate from commits noto init --root --generate # Both options ``` noto will create a `.noto/commit-prompt.md` file that defines your commit message style. Commit this file to version control so your entire team uses consistent commit messages. #### Multiple Commit Prompts Working on a monorepo? noto supports multiple commit prompt files based on your current working directory: ``` monorepo/ ├── .noto/commit-prompt.md # Root-level prompt ├── packages/ │ ├── frontend/ │ │ └── .noto/commit-prompt.md # Frontend-specific prompt │ └── backend/ │ └── .noto/commit-prompt.md # Backend-specific prompt ``` noto picks the closest `.noto/commit-prompt.md` file relative to your current directory. ## Usage ### Basic Commit Generation Stage your changes and run noto: ```bash git add . noto ``` noto analyzes your staged changes, generates a commit message in an interactive editor, and commits the changes automatically. ### Preview Mode Preview the generated message without committing: ```bash git add . noto -p # or --preview ``` ### Copy to Clipboard Copy the message to clipboard: ```bash git add . noto -c # or --copy ``` ### Commit and Push Commit and push the changes: ```bash noto --push ``` ### Provide Context Provide additional context for the commit message: ```bash noto -m "fixing authentication bug" # or --message ``` ### Force Regeneration Bypass cache and force regeneration: ```bash noto -f # or --force ``` ### Manual Commit Message Write a custom commit message manually: ```bash noto --manual ``` ### Working with Previous Messages Retrieve the last generated commit message: ```bash noto prev ``` Use with flags: ```bash noto prev -a # Apply previous message noto prev -c # Copy previous message ``` ### Amend Previous Commit Modify your last commit message: ```bash noto prev --amend -e # or --edit ``` > When using `--amend`, the `--edit` flag is required. ### Branch Management Switch between branches: ```bash noto checkout ``` Create a new branch: ```bash noto checkout -b feat/new-feature ``` ### Upgrading noto Keep noto up to date with the latest features: ```bash noto upgrade ``` Upgrade to specific version types: ```bash noto upgrade --stable # Latest stable version noto upgrade --beta # Latest beta version ``` ## All Available Flags ### Commit Generation - `-p, --preview` - Preview the generated message without committing - `-c, --copy` - Copy the message to clipboard - `-m, --message` - Provide context for the commit message - `-f, --force` - Bypass cache and force regeneration - `--push` - Commit and push the changes - `--manual` - Write a custom commit message manually ### Previous Message - `-e, --edit` - Required with `--amend` (for `noto prev`) - `--amend` - Amend the previous commit (with `noto prev`) ### Initialization - `--root` - Create prompt file in git root - `--generate` - Generate prompt from existing commits ### Upgrade - `--stable` - Upgrade to the latest stable version - `--beta` - Upgrade to the latest beta version ## Quick Examples ```bash # Quick commit (default behavior) git add . noto # Preview message without committing noto -p # Commit and push noto --push # Provide context noto -m "fixing authentication bug" # Force regenerate noto -f # Copy for manual use noto -c # Reuse previous noto prev -a # Amend last commit noto prev --amend -e # Set up custom prompts noto init --root --generate ``` ## Common Issues ### "noto api key is missing" Configure your API key: ```bash noto config key ``` Or set it as an environment variable (recommended): ```bash export NOTO_API_KEY="your-api-key-here" ``` ### "no staged changes found" Stage your changes first: ```bash git add . noto ``` ### "not enough commits to generate a prompt file" `noto init --generate` needs at least 5 commits. Either: - Wait until you have 5+ commits, then try again - Use `noto init` without `--generate` for an empty template ### "the --amend option requires the --edit option" Use both flags together: ```bash noto prev --amend -e ``` ### Why does noto show the same message repeatedly? noto caches messages to save API costs. Force regeneration with: ```bash noto -f ``` ## Privacy & Costs - **Privacy**: Only your git diff (staged changes) is sent to generate the commit message, not your entire codebase. - **Costs**: noto uses Gemini API's free tier, which is generous for most usage. Check Google AI Studio pricing for limits. ## Contributing We welcome contributions and suggestions! If you have ideas or improvements, feel free to open an issue or pull request on GitHub. ## License This project is licensed under the MIT License. © 2024-2026 Sithija Nelusha Silva (https://github.com/snelusha)