 |
VOOZH | about |
|
VOOZH | about |
This document describes the configuration file system used by ai-commit, including file locations, formats, precedence rules, and the merge strategy employed by the ConfigManager. Understanding this system is essential for customizing ai-commit's behavior at different scopes (system-wide vs. project-specific).
For information about managing configuration using the CLI, see Configuration Management. For details on specific configuration options, see Generator-Specific Configuration, Commit Types Configuration, and Prompt Templates Configuration.
The ai-commit configuration system employs a three-layer file hierarchy (plus runtime CLI overrides) with the following file locations:
Class and Constant Reference for Configuration Paths
| Priority | Type | Location | Format | Scope | Modifiable |
|---|---|---|---|---|---|
| 1 (Lowest) | Default | config/ai-commit.php | PHP array | Application defaults | No (shipped with app) |
| 2 | Global | ~/.ai-commit/.ai-commit.json | JSON | User-wide settings | Yes |
| 3 | Local | ./.ai-commit.json | JSON | Project-specific | Yes |
| 4 (Highest) | CLI Arguments | Runtime flags | N/A | Single execution | N/A |
The default configuration is a PHP file shipped with the application at config/ai-commit.php. This file contains all factory defaults and is never modified by user operations. It serves as the baseline for reset operations.
The global configuration file is stored in the user's home directory. The path varies by operating system:
Unix/Linux/macOS:
~/.ai-commit/.ai-commit.json
Windows:
C:\Users\<username>\.ai-commit\.ai-commit.json
The path resolution logic is implemented in ConfigManager::globalPath() at app/ConfigManager.php90-95 On Unix, it shells out via exec('cd ~; pwd') to resolve ~. On Windows, it uses get_current_user() to build the path under C:\Users\.
The local configuration file is located in the current working directory:
./.ai-commit.json
This allows project-specific overrides that can be committed to version control for team-wide conventions. Path resolution is implemented in app/ConfigManager.php97-106
File Selection and Merge Flow
Sources: app/ConfigManager.php47-48 app/ConfigManager.php70-106 app/Commands/ConfigCommand.php177-188
The default configuration file at config/ai-commit.php returns a plain PHP array. It is read-only from the user's perspective—loaded via require during the merge process and used as the baseline for reset operations. It is never written back by any command.
Both global and local configuration files use JSON format. The encoding options are defined in ConfigManager::JSON_OPTIONS at app/ConfigManager.php49:
| Flag | Effect |
|---|---|
JSON_PRETTY_PRINT | Human-readable indentation |
JSON_UNESCAPED_UNICODE | Preserves Unicode characters (e.g., 中文) |
JSON_UNESCAPED_SLASHES | Prevents escaping of / |
JSON_THROW_ON_ERROR | Throws JsonException on malformed JSON |
Example JSON Configuration:
The configuration system supports only two file extensions, validated in app/ConfigManager.php258-262:
| Extension | Handler | Usage |
|---|---|---|
.php | require $file | Default configuration only |
.json | File::json($file) | Global and local configurations |
Any other file extension will throw an UnsupportedConfigFileTypeException.
Sources: app/ConfigManager.php47-49 app/ConfigManager.php252-269 tests/Unit/ConfigManagerTest.php70-72
Configuration values are resolved using a cascading precedence system, where higher-priority sources override lower-priority ones:
The configuration merge strategy employs PHP's array_replace_recursive() function, which provides deep merging of nested arrays. The merge process is implemented in app/ConfigManager.php252-269:
Merge Behavior:
Example Merge:
Given these configurations:
Default (Priority 1):
Global (Priority 2):
Local (Priority 3):
Result:
Sources: app/ConfigManager.php176-181 app/ConfigManager.php252-269
The ConfigManager provides static factory methods for creating configuration instances:
| Method | Parameters | Description | Reference |
|---|---|---|---|
ConfigManager::make() | ?array $items | Creates manager from all available files or provided array | app/ConfigManager.php70-80 |
ConfigManager::makeFrom() | string ...$files | Creates manager from specific files | app/ConfigManager.php85-88 |
ConfigManager::load() | None | Creates manager and registers it globally via Config::set() | app/ConfigManager.php62-65 |
ConfigManager::load() Bootstrap Sequence
The private ConfigManager::readFrom(string ...$files) method at app/ConfigManager.php252-269 handles both PHP and JSON formats. It iterates over each file, dispatches via a match on File::extension($file), and accumulates results with array_replace_recursive(). Unsupported extensions cause UnsupportedConfigFileTypeException to be thrown immediately.
After initial loading, configurations can be replaced or updated using ConfigManager::replaceFrom(string $file) at app/ConfigManager.php168-171 It reads a file and calls ConfigManager::replace() which uses array_replace_recursive() on the internal $items array. The ConfigCommand calls this after each mutating action (set, unset, reset) to ensure the in-memory state reflects the target file before writing.
Sources: app/ConfigManager.php62-88 app/ConfigManager.php168-181 app/ConfigManager.php252-269
The ConfigManager provides methods to persist configuration changes back to files:
| Method | Target | Reference |
|---|---|---|
putGlobal() | Global configuration file | app/ConfigManager.php111-114 |
putLocal() | Local configuration file | app/ConfigManager.php119-122 |
putFile(string $file) | Arbitrary file path | app/ConfigManager.php127-163 |
Before writing configuration to JSON files, the ConfigManager filters out non-serializable values in app/ConfigManager.php129-158 The following patterns are preserved:
generators.*.parameters.messagesgenerators.*.parameters.promptgenerators.*.parameters.userAll other object instances that are not JsonSerializable, Arrayable, or Jsonable are removed to prevent serialization errors.
The putFile() method automatically creates the parent directory if it doesn't exist using File::ensureDirectoryExists() at app/ConfigManager.php160
Sources: app/ConfigManager.php111-163 tests/Feature/ConfigCommandTest.php30-58
The ConfigCommand determines which configuration file to operate on based on command options:
The resolution is handled by the private configFile() method at app/Commands/ConfigCommand.php177-188:
| Option | Result |
|---|---|
| `--file | -f ` |
| `--global | -g` |
| (neither) | ConfigManager::localPath() (current working directory) |
Sources: app/Commands/ConfigCommand.php152-162 app/Commands/ConfigCommand.php177-188 tests/Feature/ConfigCommandTest.php41-53
The ConfigCommand::initialize() method at app/Commands/ConfigCommand.php170-175 runs before handle(). If ConfigManager::globalPath() does not exist on disk, it calls $this->configManager->putGlobal(), which writes the current (default-merged) configuration to ~/.ai-commit/.ai-commit.json and creates the directory as needed.
Local configuration files are created on-demand during the first config set operation without the --global flag. The file is created automatically by app/ConfigManager.php160:
Sources: app/Commands/ConfigCommand.php170-175 app/ConfigManager.php127-163
If a JSON configuration file contains syntax errors, the system throws a JsonException with error details. This is enforced by the JSON_THROW_ON_ERROR flag in app/ConfigManager.php49
Test Case: tests/Unit/ConfigManagerTest.php66-68
Attempting to load a configuration file with an unsupported extension (anything other than .php or .json) throws an UnsupportedConfigFileTypeException.
Test Case: tests/Unit/ConfigManagerTest.php70-72
When accessing a non-existent configuration key via get(), the ConfigManager (extending Laravel's Repository) returns null by default or an optional default value if provided.
Sources: app/ConfigManager.php252-269 app/Exceptions/UnsupportedConfigFileTypeException.php tests/Unit/ConfigManagerTest.php66-72
Refresh this wiki