How to Customize thefuck Behavior: 4 Configuration Methods Explained

You can customize thefuck behavior by editing the user settings file at ~/.config/thefuck/settings.py, exporting environment variables such as THEFUCK_RULES, passing command-line flags like --debug, or creating custom Python rule modules in ~/.config/thefuck/rules/.

The thefuck command correction tool matches failed console commands against a library of rules to suggest fixes. According to the nvbn/thefuck source code, all customization happens through configuration files, environment variables, command-line arguments, and custom rule modules—allowing you to tailor behavior without modifying the core codebase.

Editing the User Settings File

When thefuck launches, it initializes a Python settings file at ~/.config/thefuck/settings.py (falling back to ~/.thefuck/settings.py for legacy installations). The creation logic resides in Settings._init_settings_file within thefuck/conf.py (lines 46‑53).

Available Configuration Options

The settings file shadows defaults defined in DEFAULT_SETTINGS from thefuck/const.py. Key options that control thefuck behavior include:

• rules – List of enabled rule names or ['ALL_ENABLED'] to load all bundled rules.
• exclude_rules – Rules to ignore even when using ALL_ENABLED.
• priority – Dictionary mapping rule names to integers; higher values run later during matching.
• require_confirmation – Boolean to show a prompt before executing fixes.
• instant_mode – Boolean to skip the interactive prompt and output the fix directly.
• repeat – Boolean to wrap fixes so thefuck runs again if the first correction fails.
• wait_command – Seconds to wait for slow commands before offering a fix.
• debug – Boolean to enable verbose output via settings.debug.
• alter_history – Boolean to write corrected commands into shell history.

Example settings.py Configuration

# ~/.config/thefuck/settings.py

rules = ['git_push', 'sudo', 'cd_parent']
exclude_rules = ['sudo']
priority = {'git_push': 10}
instant_mode = True
debug = False

After saving, thefuck reads these values automatically on the next invocation.

Using Environment Variables

For temporary overrides, export variables mapped in ENV_TO_ATTR from thefuck/const.py (lines 49‑63). The Settings._settings_from_env method in thefuck/conf.py (lines 19‑23) parses these at runtime.

Common environment variables include:

• THEFUCK_RULES – Colon-separated list of rules to load (e.g., cd_parent:git_push).
• THEFUCK_EXCLUDE_RULES – Rules to ignore.
• THEFUCK_PRIORITY – Priority overrides in rule=priority format.
• THEFUCK_DEBUG – Set to true to enable debugging.
• THEFUCK_INSTANT_MODE – Set to 1 to skip confirmation prompts.
• THEFUCK_REPEAT – Set to 1 to enable repeat mode.
• THEFUCK_NO_COLORS – Set to 1 to disable colored output.
• THEFUCK_ALTER_HISTORY – Set to 0 to prevent history modification.

These variables take precedence over the settings file but yield to command-line flags.

Command-Line Flags

Per-invocation tweaks are handled by the parser in thefuck/argument_parser.py. Flags override both file and environment settings:

• --debug – Sets settings.debug = True.
• --repeat – Enables repeat mode (alias generation handled in thefuck/utils.py by get_alias).
• --yes – Skips confirmation by setting settings.require_confirmation = False.
• --quiet – Disables colors via settings.no_colors = True.
• --no-alter-history – Prevents history modification.

Because argument parsing occurs last in the initialization chain, these options provide the highest priority configuration.

Creating Custom Rules

Rules are Python modules exposing specific callables. The corrector.get_rules_import_paths function in thefuck/corrector.py (lines 22‑38) discovers rules from three locations:

1. Bundled rules – thefuck/rules/ directory in the package.
2. User rules – ~/.config/thefuck/rules/ (created by Settings._setup_user_dir).
3. Third-party packages – Any installed package named thefuck_contrib_* containing a rules/ subdirectory.

Rule Structure

Each rule module must define:

• match(command) – Returns True if the rule applies to the given command object.
• get_new_command(command) – Returns a string or list of strings representing the corrected command.

Optional attributes include:

• priority – Integer value (default rules use lower numbers; higher numbers run later).
• enabled_by_default – Boolean; set to False to require explicit inclusion in settings.rules.
• requires_output – Boolean; if True, the rule only runs when the original command produced output.
• side_effect(command, new_script) – Callable for cleanup actions.

Example Custom Rule

Create ~/.config/thefuck/rules/git_add_all.py:

def match(command):
    return command.script == 'git add .' and 'nothing added' in command.output

def get_new_command(command):
    return 'git add -A'

The Rule.from_path method in thefuck/types.py (lines 30‑54) converts this file into a Rule object automatically. The rule will be available immediately without registration.

Advanced Customization Techniques

Controlling Rule Priority

The priority setting accepts a dictionary mapping rule names to integers. Internally, corrector.get_rules in thefuck/corrector.py (lines 46‑49) sorts rules using key=lambda rule: rule.priority. Lower numbers execute first; the default priority is defined in thefuck/types.py.

Enabling and Disabling Rules Dynamically

The Rule.is_enabled method in thefuck/types.py (lines 56‑66) determines participation based on:

return (self.name in settings.rules
        or self.enabled_by_default
        and 'ALL_ENABLED' in settings.rules)

To enable a rule explicitly, add its name to settings.rules. To disable a rule while using ALL_ENABLED, add it to settings.exclude_rules.

Instant Mode vs. Confirmation

Instant mode (settings.instant_mode) bypasses the interactive prompt and outputs the fix directly, while require_confirmation (settings.require_confirmation) controls whether thefuck asks for permission before executing. You can toggle these via the settings file, environment variables (THEFUCK_INSTANT_MODE), or command-line flags.

Summary

• Configuration File: Edit ~/.config/thefuck/settings.py to permanently adjust rules, priorities, and behavior flags like instant_mode and require_confirmation.
• Environment Variables: Use THEFUCK_RULES, THEFUCK_DEBUG, and others for shell-session-specific overrides parsed by Settings._settings_from_env.
• Command-Line Flags: Pass --debug, --repeat, or --yes for one-time adjustments that override all other settings.
• Custom Rules: Place Python modules defining match() and get_new_command() in ~/.config/thefuck/rules/ to extend the built-in correction logic without modifying the core package.

Frequently Asked Questions

Where is the thefuck configuration file located?

The primary location is ~/.config/thefuck/settings.py, falling back to ~/.thefuck/settings.py for legacy installations. thefuck/conf.py creates this file automatically via Settings._init_settings_file if it does not exist.

How do I disable a specific rule in thefuck?

Add the rule name to the exclude_rules list in your settings.py (e.g., exclude_rules = ['sudo']), or export THEFUCK_EXCLUDE_RULES=sudo for temporary disabling. You can also remove the rule from the rules list if you are not using ALL_ENABLED.

Can I create custom rules for thefuck?

Yes. Create a Python file in ~/.config/thefuck/rules/ containing a match(command) function returning a boolean and a get_new_command(command) function returning the corrected command string. The corrector.get_rules_import_paths function discovers these automatically on the next run.

What is the difference between instant mode and require_confirmation?

Instant mode (instant_mode = True) skips the interactive menu and immediately outputs the first suggested fix, while require_confirmation determines whether thefuck asks for permission before executing the corrected command. You can use instant mode to see the fix without running it, or combine both settings to execute immediately without prompting.

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