aicommit2 2.2.15 → 2.2.17

package/README.md

@@ -14,10 +14,11 @@
 [![license](https://img.shields.io/badge/license-MIT-211A4C.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHN0cm9rZT0iI0ZGRiIgdmlld0JveD0iMCAwIDI0IDI0Ij48cGF0aCBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS13aWR0aD0iMiIgZD0ibTMgNiAzIDFtMCAwLTMgOWE1IDUgMCAwIDAgNi4wMDEgME02IDdsMyA5TTYgN2w2LTJtNiAyIDMtMW0tMyAxLTMgOWE1IDUgMCAwIDAgNi4wMDEgME0xOCA3bDMgOW0tMy05LTYtMm0wLTJ2Mm0wIDE2VjVtMCAxNkg5bTMgMGgzIi8+PC9zdmc+)](https://github.com/tak-bro/aicommit2/blob/main/LICENSE)
 [![version](https://img.shields.io/npm/v/aicommit2?logo=semanticrelease&label=release&color=A51C2D)](https://www.npmjs.com/package/aicommit2)
 [![downloads](https://img.shields.io/npm/dt/aicommit2?color=F33535&logo=npm)](https://www.npmjs.com/package/aicommit2)
+[![Nix](https://img.shields.io/badge/Nix-5277C3?logo=nixos&logoColor=fff)](#nix-installation)
 
 </div>
 
----
+______________________________________________________________________
 
 ## 🚀 Quick Start
 
@@ -59,7 +60,7 @@ _aicommit2_ is a reactive CLI tool that automatically generates Git commit messa
 
 ### Local AI Services
 
-- [Ollama](docs/providers/ollama.md) 
+- [Ollama](docs/providers/ollama.md)
 
 ## Setup
 
@@ -80,6 +81,7 @@ aicommit2 config set ANTHROPIC.key=<your key>
 ```
 
 3. Run _aicommit2_ with your staged files in git repository:
+
 ```shell
 git add <files...>
 aicommit2
@@ -89,6 +91,54 @@ aicommit2
 
 ### Alternative Installation Methods
 
+#### Nix Installation
+
+If you use the Nix package manager, aicommit2 can be installed directly using the provided flake:
+
+```sh
+# Install temporarily in your current shell
+nix run github:tak-bro/aicommit2
+
+# Install permanently to your profile
+nix profile install github:tak-bro/aicommit2
+
+# Use the shorter alias
+nix run github:tak-bro/aic2 -- --help
+```
+
+##### Using in a Flake-based Project
+
+Add aicommit2 to your flake inputs:
+
+```nix
+{
+  # flake.nix configuration file
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    aicommit2.url = "github:tak-bro/aicommit2";
+  };
+  # Rest of your flake.nix file
+}
+
+  # Somewhere where you define your packages
+  {pkgs, inputs, ...}:{
+
+  environment.systemPackages = [inputs.aicommit2.packages.x86_64-linux.default];
+  # Or home packages
+  home.packages = [inputs.aicommit2.packages.x86_64-linux.default];
+  }
+```
+
+##### Development Environment
+
+To enter a development shell with all dependencies:
+
+```sh
+nix develop github:tak-bro/aicommit2
+```
+
+After setting up with Nix, you'll still need to configure API keys as described in the [Setup](#setup) section.
+
 #### From Source
 
 ```sh
@@ -151,8 +201,9 @@ aicommit2 --all # or -a
 - `--pre-commit`: Run in [pre-commit](https://pre-commit.com/) framework mode (default: **false**)
   - This option is specifically for use with the pre-commit framework
   - See [Integration with pre-commit framework](#integration-with-pre-commit-framework) section for setup instructions
-   
+
 Example:
+
 ```sh
 aicommit2 --locale "jp" --all --type "conventional" --generate 3 --clipboard --exclude "*.json" --exclude "*.ts"
 ```
@@ -177,7 +228,7 @@ if you prefer to set up the hook manually, create or edit the `.git/hooks/prepar
 #!/bin/sh
 # your-other-hook "$@"
 aicommit2 --hook-mode "$@"
- ```
+```
 
 Make the hook executable:
 
@@ -191,14 +242,14 @@ If you're using the [pre-commit](https://pre-commit.com/) framework, you can add
 
 ```yaml
 repos:
-  - repo: local
-    hooks:
-      - id: aicommit2
-        name: AI Commit Message Generator
-        entry: aicommit2 --pre-commit
-        language: node
-        stages: [prepare-commit-msg]
-        always_run: true
+    - repo: local
+      hooks:
+          - id: aicommit2
+            name: AI Commit Message Generator
+            entry: aicommit2 --pre-commit
+            language: node
+            stages: [prepare-commit-msg]
+            always_run: true
 ```
 
 Make sure you have:
@@ -209,7 +260,6 @@ Make sure you have:
 
 > **Note** : The `--pre-commit` flag is specifically designed for use with the pre-commit framework and ensures proper integration with other pre-commit hooks.
 
-
 #### Uninstall
 
 In the Git repository you want to uninstall the hook from:
@@ -222,16 +272,52 @@ Or manually delete the `.git/hooks/prepare-commit-msg` file.
 
 ### Configuration
 
+aicommit2 supports configuration via command-line arguments, environment variables, and a configuration file. Settings are resolved in the following order of precedence:
+
+1. Command-line arguments
+2. Environment variables
+3. Configuration file
+4. Default values
+
+#### Configuration File Location
+
+aicommit2 follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/index.html) for its configuration file. The configuration file is named `config.ini` and is in INI format. It is resolved in the following order of precedence:
+
+1. **`AICOMMIT_CONFIG_PATH` environment variable**: If this environment variable is set, its value is used as the direct path to the configuration file.
+2. **`$XDG_CONFIG_HOME/aicommit2/config.ini`**: This is the primary XDG-compliant location. If `$XDG_CONFIG_HOME` is not set, it defaults to `~/.config/aicommit2/config.ini`.
+3. **`~/.aicommit2`**: This is a legacy location maintained for backward compatibility.
+
+The first existing file found in this order will be used. If no configuration file is found, aicommit2 will default to creating a new `config.ini` file in the `$XDG_CONFIG_HOME/aicommit2/` directory.
+
+You can find the path of the currently loaded configuration file using the `config path` command:
+
+```sh
+aicommit2 config path
+```
+
 #### Reading and Setting Configuration
 
-- READ: `aicommit2 config get <key>`
+- READ: `aicommit2 config get [<key> [<key> ...]]`
 - SET: `aicommit2 config set <key>=<value>`
+- DELETE: `aicommit2 config del <config-name>`
 
 Example:
+
 ```sh
+# Get all configurations
+aicommit2 config get
+
+# Get specific configuration
 aicommit2 config get OPENAI
 aicommit2 config get GEMINI.key
+
+# Set configurations
 aicommit2 config set OPENAI.generate=3 GEMINI.temperature=0.5
+
+# Delete a configuration setting or section
+aicommit2 config del OPENAI.key
+aicommit2 config del GEMINI
+aicommit2 config del timeout
 ```
 
 #### Environment Variables
@@ -255,46 +341,55 @@ PERPLEXITY_API_KEY="your-perplexity-key"
 DEEPSEEK_API_KEY="your-deepseek-key"
 ```
 
+> **Note**: You can customize the environment variable name used for the API key with the `envKey` configuration property for each service.
+
 Usage Example:
 
 ```sh
 OPENAI_API_KEY="your-openai-key" ANTHROPIC_API_KEY="your-anthropic-key" aicommit2
 ```
 
-> **Note**: Environment variables take precedence over configuration file settings. 
+> **Note**: Environment variables take precedence over configuration file settings.
 
 #### How to Configure in detail
 
-1. Command-line arguments: **use the format** `--[Model].[Key]=value`
-```sh
-aicommit2 --OPENAI.locale="jp" --GEMINI.temperatue="0.5"
-```
+_aicommit2_ offers flexible configuration options for all AI services, including support for specifying multiple models. You can configure settings via command-line arguments, environment variables, or a configuration file.
 
-2. Configuration file: **use INI format in the `~/.aicommit2` file or use `set` command**.
-   Example `~/.aicommit2`:
-```ini
-# General Settings
-logging=true
-generate=2
-temperature=1.0
+1. **Command-line arguments**: Use the format `--[Model].[Key]=value`.
+   To specify multiple models, use the `--[Model].model=model1,model2` format.
 
-# Model-Specific Settings
-[OPENAI]
-key="<your-api-key>"
-temperature=0.8
-generate=1
-systemPromptPath="<your-prompt-path>"
+   ```sh
+   aicommit2 --OPENAI.locale="jp" --GEMINI.temperature="0.5" --OPENAI.model="gpt-4o,gpt-3.5-turbo"
+   ```
 
-[GEMINI]
-key="<your-api-key>"
-generate=5
-includeBody=true
+2. **Configuration file**: Refer to [Configuration File Location](#configuration-file-location) or use the `set` command.
+   For array-like values like `model`, you can use either the `model=model1,model2` comma-separated syntax or the `model[]=` syntax for multiple entries. This applies to all AI services.
 
-[OLLAMA]
-temperature=0.7
-model[]=llama3.2
-model[]=codestral
-```
+   ```ini
+   # General Settings
+   logging=true
+   generate=2
+   temperature=1.0
+
+   # Model-Specific Settings
+   [OPENAI]
+   key="<your-api-key>"
+   temperature=0.8
+   generate=1
+   model="gpt-4o,gpt-3.5-turbo"
+   systemPromptPath="<your-prompt-path>"
+
+   [GEMINI]
+   key="<your-api-key>"
+   generate=5
+   includeBody=true
+   model="gemini-pro,gemini-flash"
+
+   [OLLAMA]
+   temperature=0.7
+   model[]=llama3.2
+   model[]=codestral
+   ```
 
 > The priority of settings is: **Command-line Arguments > Environment Variables > Model-Specific Settings > General Settings > Default Values**.
 
@@ -304,7 +399,8 @@ The following settings can be applied to most models, but support may vary.
 Please check the documentation for each specific model to confirm which settings are supported.
 
 | Setting                | Description                                                         | Default      |
-|------------------------|---------------------------------------------------------------------|--------------|
+| ---------------------- | ------------------------------------------------------------------- | ------------ |
+| `envKey`               | Custom environment variable name for the API key                    | -            |
 | `systemPrompt`         | System Prompt text                                                  | -            |
 | `systemPromptPath`     | Path to system prompt file                                          | -            |
 | `exclude`              | Files to exclude from AI analysis                                   | -            |
@@ -322,14 +418,28 @@ Please check the documentation for each specific model to confirm which settings
 | `codeReviewPromptPath` | Path to code review prompt file                                     | -            |
 | `disabled`             | Whether a specific model is enabled or disabled                     | false        |
 
-> 👉 **Tip:** To set the General Settings for each model, use the following command.
+> 👉 **Tip:** To set the General Settings for each model, use the following command.
+>
 > ```shell
 > aicommit2 config set OPENAI.locale="jp"
 > aicommit2 config set CODESTRAL.type="gitmoji"
 > aicommit2 config set GEMINI.includeBody=true
 > ```
 
+##### envKey
+
+- Allows users to specify a custom environment variable name for their API key.
+- If `envKey` is not explicitly set, the system defaults to using an environment variable named after the service, followed by `_API_KEY` (e.g., `OPENAI_API_KEY` for OpenAI, `GEMINI_API_KEY` for Gemini).
+- This setting provides flexibility for managing API keys, especially when multiple services are used or when specific naming conventions are required.
+
+```sh
+aicommit2 config set OPENAI.envKey="MY_CUSTOM_OPENAI_KEY"
+```
+
+> `envKey` is used to retrieve the API key from your system's environment variables. Ensure the specified environment variable is set with your API key.
+
 ##### systemPrompt
+
 - Allow users to specify a custom system prompt
 
 ```sh
@@ -339,8 +449,10 @@ aicommit2 config set systemPrompt="Generate git commit message."
 > `systemPrompt` takes precedence over `systemPromptPath` and does not apply at the same time.
 
 ##### systemPromptPath
+
 - Allow users to specify a custom file path for their own system prompt template
 - Please see [Custom Prompt Template](#custom-prompt-template)
+- **Note**: Paths can be absolute or relative to the configuration file location.
 
 ```sh
 aicommit2 config set systemPromptPath="/path/to/user/prompt.txt"
@@ -396,16 +508,10 @@ aicommit2 config set generate=2
 
 Default: `true`
 
-Option that allows users to decide whether to generate a log file capturing the responses.
-The log files will be stored in the `~/.aicommit2_log` directory(user's home).
-
-![log-path](https://github.com/tak-bro/aicommit2/blob/main/img/log_path.png?raw=true)
-
-- You can remove all logs below comamnd.
+This boolean option controls whether the application generates log files. When enabled, both the general application logs and the AI request/response logs are written to their respective paths. For a detailed explanation of all logging settings, including how to enable/disable logging and manage log files, please refer to the main [Logging](#main-logging-section) section.
 
-```sh
-aicommit2 log removeAll
-```
+- **Log File Example**:
+  ![log-path](https://github.com/tak-bro/aicommit2/blob/main/img/log_path.png?raw=true)
 
 ##### includeBody
 
@@ -419,7 +525,6 @@ aicommit2 config set includeBody="true"
 
 ![ignore_body_false](https://github.com/tak-bro/aicommit2/blob/main/img/demo_body_min.gif?raw=true)
 
-
 ```sh
 aicommit2 config set includeBody="false"
 ```
@@ -514,31 +619,34 @@ aicommit2 config set codeReview=true
 - **The code review process consumes a large number of tokens.**
 
 ##### codeReviewPromptPath
+
 - Allow users to specify a custom file path for code review
+- **Note**: Paths can be absolute or relative to the configuration file location.
 
 ```sh
 aicommit2 config set codeReviewPromptPath="/path/to/user/prompt.txt"
 ```
 
 ## Available General Settings by Model
-|                             | timeout | temperature | maxTokens |  topP  |
-|:---------------------------:|:-------:|:-----------:|:---------:|:------:|
-|         **OpenAI**          |    ✓    |      ✓      |     ✓     |   ✓    |
-|    **Anthropic Claude**     |    ✓    |      ✓      |     ✓     |   ✓    |
-|         **Gemini**          |         |      ✓      |     ✓     |   ✓    |
-|       **Mistral AI**        |    ✓    |      ✓      |     ✓     |   ✓    |
-|        **Codestral**        |    ✓    |      ✓      |     ✓     |   ✓    |
-|         **Cohere**          |    ✓    |      ✓      |     ✓     |   ✓    |
-|          **Groq**           |    ✓    |      ✓      |     ✓     |   ✓    |
-|       **Perplexity**        |    ✓    |      ✓      |     ✓     |   ✓    |
-|        **DeepSeek**         |    ✓    |      ✓      |     ✓     |   ✓    |
-|         **Ollama**          |    ✓    |      ✓      |           |   ✓    |
-| **OpenAI API-Compatible**   |    ✓    |      ✓      |     ✓     |   ✓    |
+
+|                           | timeout | temperature | maxTokens | topP |
+| :-----------------------: | :-----: | :---------: | :-------: | :--: |
+|        **OpenAI**         |    ✓    |      ✓      |     ✓     |  ✓   |
+|   **Anthropic Claude**    |    ✓    |      ✓      |     ✓     |  ✓   |
+|        **Gemini**         |         |      ✓      |     ✓     |  ✓   |
+|      **Mistral AI**       |    ✓    |      ✓      |     ✓     |  ✓   |
+|       **Codestral**       |    ✓    |      ✓      |     ✓     |  ✓   |
+|        **Cohere**         |    ✓    |      ✓      |     ✓     |  ✓   |
+|         **Groq**          |    ✓    |      ✓      |     ✓     |  ✓   |
+|      **Perplexity**       |    ✓    |      ✓      |     ✓     |  ✓   |
+|       **DeepSeek**        |    ✓    |      ✓      |     ✓     |  ✓   |
+|        **Ollama**         |    ✓    |      ✓      |           |  ✓   |
+| **OpenAI API-Compatible** |    ✓    |      ✓      |     ✓     |  ✓   |
 
 > All AI support the following options in General Settings.
+>
 > - systemPrompt, systemPromptPath, codeReview, codeReviewPromptPath, exclude, type, locale, generate, logging, includeBody, maxLength
 
-
 ## Configuration Examples
 
 ```
@@ -554,6 +662,7 @@ aicommit2 config set \
 ```
 
 > 🔍 **Detailed Support Info**: Check each provider's documentation for specific limits and behaviors:
+>
 > - [OpenAI](docs/providers/openai.md)
 > - [Anthropic Claude](docs/providers/anthropic.md)
 > - [Gemini](docs/providers/gemini.md)
@@ -563,13 +672,60 @@ aicommit2 config set \
 > - [Perplexity](docs/providers/perplexity.md)
 > - [DeepSeek](docs/providers/deepseek.md)
 > - [OpenAI API Compatibility](docs/providers/compatible.md)
-> - [Ollama](docs/providers/ollama.md) 
- 
+> - [Ollama](docs/providers/ollama.md)
+
+## <a id="main-logging-section"></a>Logging
+
+The application utilizes two distinct logging systems to provide comprehensive insights into its operations:
+
+### 1. Application Logging (Winston)
+
+This system handles general application logs and exceptions. Its behavior can be configured through the following settings in your `config.ini` file:
+
+- **`logLevel`**:
+
+  - **Description**: Specifies the minimum level for logs to be recorded. Messages with a level equal to or higher than the configured `logLevel` will be captured.
+  - **Default**: `info`
+  - **Supported Levels**: `error`, `warn`, `info`, `http`, `verbose`, `debug`, `silly`
+
+- **`logFilePath`**:
+
+  - **Description**: Defines the path to the main application log file. This setting supports date patterns (e.g., `%DATE%`) to automatically rotate log files daily.
+  - **Default**: `logs/aicommit2-%DATE%.log` (relative to the application's state directory, typically `~/.local/state/aicommit2/logs` on Linux or `~/Library/Application Support/aicommit2/logs` on macOS).
+
+- **`exceptionLogFilePath`**:
+
+  - **Description**: Specifies the path to a dedicated log file for recording exceptions. Similar to `logFilePath`, it supports date patterns for daily rotation.
+  - **Default**: `logs/exceptions-%DATE%.log` (relative to the application's state directory, typically `~/.local/state/aicommit2/logs` on Linux or `~/Library/Application Support/aicommit2/logs` on macOS).
+
+### 2. AI Request/Response Logging
+
+This system is specifically designed to log the prompts and responses exchanged with AI models for review and commit generation. These logs are stored in the application's dedicated logs directory.
+
+- **Log Location**: These logs are stored in the same base directory as the application logs, which is determined by the system's state directory (e.g., `~/.local/state/aicommit2/logs` on Linux or `~/Library/Application Support/aicommit2/logs` on macOS).
+- **File Naming**: Each AI log file is uniquely named using a combination of the date (`YYYY-MM-DD_HH-MM-SS`) and a hash of the git diff content, ensuring easy identification and chronological order.
+
+### Enable/Disable Logging
+
+The `logging` setting controls whether log files are generated. It can be configured both globally and for individual AI services:
+
+- **Global `logging` setting**: When set in the general configuration, it controls the overall application logging (handled by Winston) and acts as a default for AI request/response logging.
+- **Service-specific `logging` setting**: You can override the global `logging` setting for a particular AI service. If `logging` is set to `false` for a specific service, AI request/response logs will not be generated for that service, regardless of the global setting.
+
+### Removing All Logs
+
+You can remove all generated log files (both application and AI logs) using the following command:
+
+```sh
+aicommit2 log removeAll
+```
+
 ## Custom Prompt Template
 
 _aicommit2_ supports custom prompt templates through the `systemPromptPath` option. This feature allows you to define your own prompt structure, giving you more control over the commit message generation process.
 
 ### Using the systemPromptPath Option
+
 To use a custom prompt template, specify the path to your template file when running the tool:
 
 ```
@@ -630,7 +786,6 @@ The response should be valid JSON that can be parsed without errors.
 
 This ensures that the output is consistently formatted as a JSON array, regardless of the custom template used.
 
-
 ## Watch Commit Mode
 
 ![watch-commit-gif](https://github.com/tak-bro/aicommit2/blob/main/img/watch-commit-min.gif?raw=true)
@@ -642,6 +797,7 @@ aicommit2 --watch-commit
 ```
 
 This feature only works within Git repository directories and automatically triggers whenever a commit event occurs. When a new commit is detected, it automatically:
+
 1. Analyzes commit changes
 2. Performs AI code review
 3. Displays results in real-time
@@ -655,9 +811,10 @@ This feature only works within Git repository directories and automatically trig
 - API costs can increase substantially if there are many commits
 - It is recommended to **carefully monitor your token usage** when using this feature
 - To use this feature, you must enable watch mode for at least one AI model:
-  ```sh
-  aicommit2 config set [MODEL].watchMode="true"
-  ```
+
+```sh
+aicommit2 config set [MODEL].watchMode="true"
+```
 
 ## Upgrading
 
@@ -686,8 +843,11 @@ For bug fixes or feature implementations, please check the [Contribution Guide](
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+
 <!-- prettier-ignore-start -->
+
 <!-- markdownlint-disable -->
+
 <table>
   <tr>
     <td align="center"><a href="https://github.com/eltociear"><img src="https://avatars.githubusercontent.com/eltociear" width="100px;" alt=""/><br /><sub><b>@eltociear</b></sub></a><br /><a href="https://github.com/tak-bro/aicommit2/commits?author=eltociear" title="Documentation">📖</a></td>
@@ -708,7 +868,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- prettier-ignore-end -->
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
----
+______________________________________________________________________
 
 If this project has been helpful, please consider giving it a Star ⭐️!