Configuration Management

This page guides users through managing ai-commit configuration using the config command. It covers setting API keys, adjusting generator parameters, understanding configuration file locations, and the precedence hierarchy that determines which settings take effect.

For details about specific configuration options like commit types, prompt templates, and generator-specific settings, see section 7. For information about the internal implementation of the configuration system, see Configuration System Implementation. For command-line flags that override configuration, see Command Options and Flags.

Configuration File Locations

ai-commit uses a three-tier configuration system with files at different locations:

Location	Path	Scope	Format
PHP Defaults	config/ai-commit.php	Application-wide defaults	PHP array
Global Config	~/.ai-commit/.ai-commit.json (Unix) C:\Users\<username>\.ai-commit\.ai-commit.json (Windows)	User-wide settings across all projects	JSON
Local Config	./.ai-commit.json (current directory)	Project-specific settings	JSON

The global configuration directory is determined by app/ConfigManager.php90-94 which uses the user's home directory. The local configuration is always in the current working directory at app/ConfigManager.php97-106

Sources: app/ConfigManager.php47-48 app/ConfigManager.php90-106 README.md60-68

Configuration Hierarchy

Settings are merged using a precedence hierarchy where later sources override earlier ones:

The merging process uses PHP's array_replace_recursive function at app/ConfigManager.php178 to perform deep array merging, allowing nested configuration keys to be overridden individually.

Sources: app/ConfigManager.php176-181 app/ConfigManager.php252-268

Using the Config Command

The config command provides six actions for managing configuration:

Sources: app/Commands/ConfigCommand.php32 app/Commands/ConfigCommand.php72-109

Basic Command Syntax

Available options:

• --global or -g: Apply changes to the global config file
• --file=<path> or -f <path>: Apply changes to a specific config file
• --editor=<editor> or -e <editor>: Specify editor for the edit action

The file selection logic at app/Commands/ConfigCommand.php177-188 determines which configuration file to operate on based on these flags.

Sources: app/Commands/ConfigCommand.php152-162 app/Commands/ConfigCommand.php177-188 README.md172-180

Configuration Actions

set: Setting Configuration Values

Set a configuration key to a value:

The set action stores the value at app/Commands/ConfigCommand.php73-76 and supports both string and JSON values (automatically detected at app/Commands/ConfigCommand.php210-213).

Sources: app/Commands/ConfigCommand.php73-76 app/Commands/ConfigCommand.php210-213 README.md61-68

get: Retrieving Configuration Values

Retrieve configuration values:

The get action at app/Commands/ConfigCommand.php78-81 returns either a specific key's value or the entire configuration as JSON when no key is specified.

Sources: app/Commands/ConfigCommand.php78-81 README.md175

unset: Removing Configuration Keys

Remove a configuration key:

The unset action at app/Commands/ConfigCommand.php83-86 uses ConfigManager::forget() which calls Arr::forget() at app/ConfigManager.php188-193 to remove the key.

Sources: app/Commands/ConfigCommand.php83-86 app/ConfigManager.php188-193 README.md176

reset: Restoring Default Values

Reset configuration to default values from the PHP config file:

The reset action at app/Commands/ConfigCommand.php88-92 loads the default PHP configuration from config/ai-commit.php and restores the specified key or all configuration.

Sources: app/Commands/ConfigCommand.php88-92 README.md177

list: Displaying All Configuration

List all configuration in dot notation:

Output example:

[generator] openai_chat
[generators.openai_chat.api_key] sk-...
[generators.openai_chat.parameters.model] gpt-4
[generators.openai_chat.parameters.temperature] 0.7
[http_options.timeout] 60

The list action at app/Commands/ConfigCommand.php94-99 converts the configuration to dot notation using toDotArray() at app/ConfigManager.php224-227

Sources: app/Commands/ConfigCommand.php94-99 app/ConfigManager.php224-227 README.md178

edit: Opening Configuration in Editor

Open the configuration file in a text editor:

The edit action at app/Commands/ConfigCommand.php100-106 launches an editor process using Symfony's Process component. The editor is determined at app/Commands/ConfigCommand.php190-205 by checking for available editors in order: custom (via --editor), then system editors (vim, vi, nano, pico, ed on Unix; notepad on Windows).

Sources: app/Commands/ConfigCommand.php100-106 app/Commands/ConfigCommand.php190-205 README.md179

Configuration Workflow

Sources: app/Commands/ConfigCommand.php55-114 app/ConfigManager.php127-163

Configuration Precedence Example

This diagram shows how configuration values are resolved for a specific key:

Sources: app/ConfigManager.php70-80 app/ConfigManager.php85-88

Common Configuration Tasks

Configuring API Keys

Set API keys for different generators:

API keys are stored in the generators.<generator_name>.api_key configuration path as defined in the generator configurations.

Sources: README.md61-68 README-zh_CN.md61-68

Setting Default Generator

Configure which AI generator to use by default:

This sets the default value for the --generator flag used by the commit command.

Sources: README.md70

Configuring Binary Paths

For CLI-based generators, set the path to the executable:

These paths are used at runtime to execute the CLI tools.

Sources: README.md61-65

Adjusting Generator Parameters

Customize AI model parameters:

Generator parameters are nested under generators.<generator_name>.parameters and vary by generator type.

Sources: app/Commands/ConfigCommand.php210-213

Configuration File Format

Configuration files use JSON format with the following structure:

The JSON is formatted with pretty-printing options defined at app/ConfigManager.php49 including JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE, and JSON_UNESCAPED_SLASHES.

For a complete reference of all available configuration options, see section 7.

Sources: app/ConfigManager.php49 app/ConfigManager.php127-163

Configuration Initialization

When the config command runs, it automatically ensures the global configuration file exists:

This initialization happens at app/Commands/ConfigCommand.php170-175 before any config action is executed, ensuring users always have a valid global configuration file.

Sources: app/Commands/ConfigCommand.php170-175 app/ConfigManager.php111-114

Troubleshooting Configuration Issues

Finding Active Configuration

To see which configuration file is being used:

Viewing Merged Configuration

Display the final merged configuration:

Resetting to Defaults

If configuration becomes corrupted:

Sources: app/Commands/ConfigCommand.php88-92 app/Commands/ConfigCommand.php94-99