Where Are thefuck Settings Managed? A Deep Dive into the Configuration System

Thefuck settings are managed through a hierarchical system centered in thefuck/conf.py, which loads configuration from user config files, environment variables, and command-line arguments into a global Settings instance.

Thefuck, the popular Python command-line correction tool, uses a flexible, multi-layered configuration system that allows users to customize behavior through files, environment variables, or runtime flags. Understanding where these thefuck settings are stored and how they are prioritized is essential for advanced customization and debugging. According to the nvbn/thefuck source code, all configuration flows through the Settings class in thefuck/conf.py.

The Core Settings Architecture

The Settings Class in conf.py

The configuration system revolves around the Settings class defined in thefuck/conf.py. This class extends Python's built-in dict to provide attribute-style access (e.g., settings.rules, settings.debug).

At line 40 of conf.py, the module initializes a global instance named settings that the entire application imports and uses:

from thefuck.conf import settings

# Access any configuration value as an attribute

if settings.debug:
    print("Debug mode enabled")

The Settings.init() method populates this dictionary through three successive loading steps, with each layer overriding the previous one.

The Three-Layer Configuration Hierarchy

Thefuck applies settings in a specific priority order: command-line arguments override environment variables, which override user config files, which override default values.

Layer 1: User Configuration File

The primary location for persistent thefuck settings is the user config file at ~/.config/thefuck/settings.py (with fallback support for the legacy path ~/.thefuck/settings.py).

When the program starts, the _init_settings_file() function (lines 46-53) checks for this file and generates a default template with comments if it does not exist. The _settings_from_file() function (lines 77-84) then loads the file using importlib or imp to execute the Python code and extract variables.

Example user configuration file:

# ~/.config/thefuck/settings.py

rules = ['git_push', 'sudo', 'python_command']
require_confirmation = False
wait_command = 2
debug = True

Layer 2: Environment Variables (THEFUCK_*)

Environment variables prefixed with THEFUCK_ provide a method for per-session configuration overrides. The _settings_from_env() method (lines 19-24) iterates over the const.ENV_TO_ATTR mapping to identify relevant variables.

The conversion logic in _val_from_env() (lines 101-118) automatically casts values to appropriate Python types: colon-separated strings become lists, "true"/"false" become booleans, and numeric strings become integers.

# Override rules list (colon-separated)

export THEFUCK_RULES='git_push:cd_parent:no_sudo'

# Enable debug mode (boolean conversion)

export THEFUCK_DEBUG=true

# Change wait time (integer conversion)

export THEFUCK_WAIT_COMMAND=5

Layer 3: Command-Line Arguments

Runtime flags passed to thefuck take highest priority. The argument_parser.py module defines CLI flags that map directly to settings attributes. The _settings_from_args() method (lines 25-37) inspects the parsed argparse.Namespace and applies these values to the global settings object.

# Disable confirmation prompt and enable debug output for this invocation only

thefuck --no-confirmation --debug

Default Settings and Constants

All default values for thefuck settings reside in thefuck/const.py. The DEFAULT_SETTINGS dictionary (beginning at line 31) defines factory defaults for every configurable option, including rules, priority, debug, wait_command, and require_confirmation.

The same file defines ENV_TO_ATTR (lines 49-63), which maps environment variable names to their corresponding settings attributes and specifies type conversion rules. This mapping ensures that THEFUCK_RULES correctly populates settings.rules as a list, while THEFUCK_WAIT_COMMAND populates settings.wait_command as an integer.

Practical Configuration Examples

Editing the User Config File

Create or modify ~/.config/thefuck/settings.py to apply permanent customizations:

# Require explicit confirmation before running corrections

require_confirmation = True

# Only use specific rules

rules = ['git_push', 'apt_get', ' fix_file']

# Wait 3 seconds before executing the corrected command

wait_command = 3

Using Environment Variables

Set variables before invoking the command for temporary overrides:

export THEFUCK_REQUIRE_CONFIRMATION=false
export THEFUCK_DEBUG=true
thefuck  # Runs with confirmation disabled and debug output enabled

Accessing Settings Programmatically

Any module within thefuck or third-party extensions can import and read the global settings instance:

from thefuck.conf import settings

def my_custom_rule(command):
    if settings.debug:
        print(f"Processing: {command}")
    
    # Access any configured value

    timeout = settings.wait_command
    return True

Summary

• Primary location: The Settings class in thefuck/conf.py manages all configuration through a global settings instance created at module load time.
• Configuration files: Persistent settings live in ~/.config/thefuck/settings.py (XDG compliant) or the legacy ~/.thefuck/settings.py path.
• Environment overrides: Variables prefixed with THEFUCK_ override file settings using the mapping defined in thefuck/const.py.
• Runtime flags: Command-line arguments parsed in thefuck/argument_parser.py take highest priority via _settings_from_args().
• Defaults: All default values and type mappings reside in thefuck/const.py within the DEFAULT_SETTINGS dictionary.

Frequently Asked Questions

Where is the thefuck settings file located?

Thefuck stores user configuration at ~/.config/thefuck/settings.py by default, following the XDG Base Directory specification. If this directory does not exist, it falls back to the legacy path ~/.thefuck/settings.py. The file is automatically generated with default values and comments on first run if it does not exist.

How do I override thefuck settings temporarily?

Use environment variables prefixed with THEFUCK_ to override settings for a single shell session. For example, export THEFUCK_DEBUG=true enables debug mode, while export THEFUCK_RULES='git_push' restricts which rules are active. These variables override config file values but are themselves overridden by command-line arguments.

What is the priority order for thefuck configuration sources?

Thefuck applies configuration in the following priority order (lowest to highest): default values from thefuck/const.py, user configuration file (settings.py), environment variables (THEFUCK_*), and command-line arguments. This means CLI flags always take precedence, followed by environment variables, then file settings.

How does thefuck convert environment variables to Python types?

The conversion logic in _val_from_env() (lines 101-118 of thefuck/conf.py) automatically detects types: strings containing colons are split into lists (e.g., "a:b" becomes ['a', 'b']), "true"/"false" strings become booleans, and numeric strings become integers. This mapping is controlled by the ENV_TO_ATTR dictionary in thefuck/const.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}