0
# Configuration Management
1

2
Settings management from configuration files and environment variables, supporting user customization of correction behavior, rule selection, and application preferences. The configuration system provides flexible control over thefuck's behavior through multiple sources.
3

4
## Capabilities
5

6
### Settings Loading and Management
7

8
Core functions for loading and managing application settings from multiple sources.
9

10
```python { .api }
11
def get_settings(user_dir):
12
    """
13
    Returns settings filled with values from settings.py and environment variables.
14
    
15
    Parameters:
16
    - user_dir (pathlib.Path): User configuration directory path
17
    
18
    Returns:
19
    Settings: Complete settings object with values from defaults, file, and environment
20
    
21
    Loads settings in priority order:
22
    1. Default settings
23
    2. User settings file (~/.thefuck/settings.py)
24
    3. Environment variables (highest priority)
25
    """
26

27
def initialize_settings_file(user_dir):
28
    """
29
    Creates initial settings file if it doesn't exist.
30
    
31
    Parameters:
32
    - user_dir (pathlib.Path): User configuration directory path
33
    
34
    Returns:
35
    None
36
    
37
    Creates ~/.thefuck/settings.py with default settings template and comments.
38
    """
39
```
40

41
### Default Configuration
42

43
Built-in default settings and constants that define the base behavior.
44

45
```python { .api }
46
DEFAULT_RULES = _DefaultRulesNames([])
47
    """
48
    Default list of enabled rules.
49
    Special list type that includes all rules with enabled_by_default=True.
50
    """
51

52
DEFAULT_PRIORITY = 1000
53
    """
54
    Default priority value for rules when not specified.
55
    """
56

57
DEFAULT_SETTINGS = {
58
    'rules': DEFAULT_RULES,
59
    'wait_command': 3,
60
    'require_confirmation': True,
61
    'no_colors': False,
62
    'debug': False,
63
    'priority': {},
64
    'env': {'LC_ALL': 'C', 'LANG': 'C', 'GIT_TRACE': '1'}
65
}
66
    """
67
    Default configuration dictionary containing all default values.
68
    
69
    Settings:
70
    - rules: List of enabled correction rules
71
    - wait_command: Timeout in seconds for command execution
72
    - require_confirmation: Whether to require user confirmation before executing
73
    - no_colors: Disable colored output
74
    - debug: Enable debug logging
75
    - priority: Dictionary of rule name to priority overrides
76
    - env: Environment variables to set when executing commands
77
    """
78
```
79

80
### Environment Variable Support
81

82
Environment variable to setting attribute mapping and processing.
83

84
```python { .api }
85
ENV_TO_ATTR = {
86
    'THEFUCK_RULES': 'rules',
87
    'THEFUCK_WAIT_COMMAND': 'wait_command',
88
    'THEFUCK_REQUIRE_CONFIRMATION': 'require_confirmation',
89
    'THEFUCK_NO_COLORS': 'no_colors',
90
    'THEFUCK_PRIORITY': 'priority',
91
    'THEFUCK_DEBUG': 'debug'
92
}
93
    """
94
    Mapping of environment variable names to settings attributes.
95
    """
96
```
97

98
### Special Rule List Types
99

100
Specialized list types for rule management with enhanced behavior.
101

102
```python { .api }
103
class _DefaultRulesNames(RulesNamesList):
104
    """
105
    Special rules list that automatically includes rules with enabled_by_default=True.
106
    
107
    Extends RulesNamesList with default rule inclusion behavior.
108
    """
109
    
110
    def __contains__(self, item):
111
        """
112
        Check if rule is enabled.
113
        
114
        Parameters:
115
        - item (Rule): Rule object to check
116
        
117
        Returns:
118
        bool: True if rule is in list or has enabled_by_default=True
119
        """
120
    
121
    def __add__(self, items):
122
        """
123
        Add items to rules list.
124
        
125
        Parameters:
126
        - items (list): Items to add
127
        
128
        Returns:
129
        _DefaultRulesNames: New list with added items
130
        """
131
```
132

133
## Configuration File Format
134

135
The settings file (`~/.thefuck/settings.py`) is a Python file that can set any of the configuration options:
136

137
```python
138
# ~/.thefuck/settings.py example
139

140
# Rules to enable (list of rule names)
141
rules = ['git_push', 'sudo', 'cd_mkdir', 'apt_get']
142

143
# Timeout for command execution (seconds)
144
wait_command = 5
145

146
# Require user confirmation before executing corrections
147
require_confirmation = True
148

149
# Disable colored output
150
no_colors = False
151

152
# Enable debug logging
153
debug = False
154

155
# Override rule priorities (rule_name: priority)
156
priority = {
157
    'sudo': 2000,
158
    'git_push': 1500
159
}
160

161
# Environment variables for command execution
162
env = {
163
    'LC_ALL': 'C',
164
    'LANG': 'C',
165
    'GIT_TRACE': '1'
166
}
167
```
168

169
## Environment Variables
170

171
All settings can be overridden with environment variables:
172

173
```python { .api }
174
# Environment variable formats:
175

176
THEFUCK_RULES = "sudo:git_push:cd_mkdir"
177
    """
178
    Colon-separated list of rule names.
179
    Use 'DEFAULT_RULES' to include all default rules plus additional ones.
180
    """
181

182
THEFUCK_WAIT_COMMAND = "5"
183
    """
184
    Command timeout in seconds (integer).
185
    """
186

187
THEFUCK_REQUIRE_CONFIRMATION = "false"
188
    """
189
    Boolean setting: 'true' or 'false' (case-insensitive).
190
    """
191

192
THEFUCK_NO_COLORS = "true"
193
    """
194
    Boolean setting: 'true' or 'false' (case-insensitive).
195
    """
196

197
THEFUCK_DEBUG = "true"
198
    """
199
    Boolean setting: 'true' or 'false' (case-insensitive).
200
    """
201

202
THEFUCK_PRIORITY = "sudo=2000:git_push=1500"
203
    """
204
    Colon-separated rule=priority pairs.
205
    """
206
```
207

208
## Usage Examples
209

210
### Basic Settings Setup
211

212
```python
213
from thefuck.conf import get_settings, initialize_settings_file
214
from thefuck.main import setup_user_dir
215

216
# Setup user directory and get settings
217
user_dir = setup_user_dir()
218
settings = get_settings(user_dir)
219

220
print(f"Wait timeout: {settings.wait_command}")
221
print(f"Confirmation required: {settings.require_confirmation}")
222
print(f"Enabled rules: {len(settings.rules)}")
223
print(f"Debug mode: {settings.debug}")
224
```
225

226
### Environment Override Example
227

228
```python
229
import os
230
from thefuck.conf import get_settings
231
from thefuck.main import setup_user_dir
232

233
# Set environment variables
234
os.environ['THEFUCK_DEBUG'] = 'true'
235
os.environ['THEFUCK_WAIT_COMMAND'] = '10'
236
os.environ['THEFUCK_RULES'] = 'sudo:git_push:DEFAULT_RULES'
237

238
# Get settings (environment overrides file settings)
239
user_dir = setup_user_dir()
240
settings = get_settings(user_dir)
241

242
print(f"Debug enabled: {settings.debug}")  # True
243
print(f"Wait timeout: {settings.wait_command}")  # 10
244
```
245

246
### Custom Rules Configuration
247

248
```python
249
from thefuck.conf import get_settings
250
from thefuck.types import RulesNamesList
251

252
# Example of programmatic rules configuration
253
user_dir = setup_user_dir()
254
settings = get_settings(user_dir)
255

256
# Modify rules list
257
custom_rules = RulesNamesList(['sudo', 'git_push', 'cd_mkdir', 'apt_get'])
258
new_settings = settings.update(rules=custom_rules)
259

260
print(f"Original rules count: {len(settings.rules)}")
261
print(f"Custom rules count: {len(new_settings.rules)}")
262
```
263

264
### Priority Customization
265

266
```python
267
from thefuck.conf import get_settings
268

269
user_dir = setup_user_dir()
270
settings = get_settings(user_dir)
271

272
# Update rule priorities
273
priority_overrides = {
274
    'sudo': 2000,        # Higher priority
275
    'git_push': 500,     # Lower priority
276
    'cd_mkdir': 1500     # Medium priority
277
}
278

279
custom_settings = settings.update(priority=priority_overrides)
280
print(f"Custom priorities: {custom_settings.priority}")
281
```
282

283
## Settings Precedence
284

285
Settings are loaded in the following order (later sources override earlier ones):
286

287
1. **Default settings** - Built-in defaults from `DEFAULT_SETTINGS`
288
2. **Settings file** - User's `~/.thefuck/settings.py`
289
3. **Environment variables** - `THEFUCK_*` environment variables
290

291
This allows for flexible configuration with global defaults, user customization, and per-session overrides.
292

293
## Error Handling
294

295
The configuration system handles errors gracefully:
296

297
- **File loading errors**: Invalid settings files are logged but don't crash the application
298
- **Environment parsing errors**: Invalid environment values are logged and ignored
299
- **Missing files**: Settings file is created automatically if missing
300
- **Type conversion errors**: Invalid values fall back to defaults with warnings