A blazingly fast reimplementation of thefuck in Go.
Project status: go-fuck is stable as of 1.0.0. The settings file and the --json output
are covered by compatibility guarantees (see UPGRADING.md); the instant mode
remains opt-in.
go-fuck fixes the command you just typed and got wrong. Run the fuck alias after a failure and
go-fuck replays the command to capture its error output, matches a rule against it and executes the
corrected command once you confirm the suggestion.
$ git push
fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin main
$ fuck
› git push --set-upstream origin main [enter · ↑↓ · ctrl+c]- Why Go
- Features
- Requirements
- Installation
- Shell setup
- First steps
- How it works
- Instant mode
- Machine readable output
- Settings
- Confirmation keys
- Rules
- Creating custom rules
- Differences from thefuck
- Contributing
- License
- Acknowledgements
- One static binary. A single
go-fuckexecutable (orgo-fuck.exeon Windows) contains everything. No interpreter, no packages and no runtime dependencies. - Fast startup. A native Go binary starts in milliseconds, without importing an interpreter and its modules.
- Cross-platform by default. The same source builds for Linux, macOS and Windows on amd64 and arm64, and CI builds and tests all three systems.
- Small, dependency-free codebase. Standard library only, formatted with
gofmtand organized so a new rule is one file plus one test file.
The correction hot path and the shell history parser have Go benchmarks
(make bench); they do not depend on the installed tools. Measured on an AMD Ryzen 7 7730U (16 logical CPUs) with Go 1.27:
| Benchmark | Result |
|---|---|
| Full correction path (select rules, match them, order suggestions) | ~0.2 ms/op |
| Matching every rule against a captured output | ~0.18 ms/op |
| Matching rules when the command output could not be captured | ~1.4 µs/op |
| Parsing a 20,000 line shell history file | ~1.3 ms/op |
| Restoring a multi-line command from the bash alias history | ~0.65 µs/op |
| Restoring a command from the zsh history array | ~42 ns/op |
The rule engine adds roughly 0.2 ms; the wall clock time of a correction is dominated by deliberately re-running the failed command. An interpreter based implementation pays for interpreter and module import startup before the first rule runs, which a native binary does not need.
- Shell integration for bash, zsh, fish, tcsh and PowerShell.
- Machine readable JSON output for editor plugins, scripts and AI agents with
--json. - Interactive confirmation prompt with keyboard navigation, or skip it with
-y/--yes. - Re-runs go-fuck when the corrected command fails with
-r/--repeat;--force-commandfixes an arbitrary command instead of the previous one. - A single ember theme for the version banner, confirmation prompt, help text, setup messages and
diagnostics: shared
›/×/·symbols, an fzf prompt in the same palette, 24 bit, 256 color and 16 color fallbacks, andNO_COLORsupport. - A JSON settings file with defaults for every option, environment variable overrides using the
GOFUCK_*prefix and the legacyTHEFUCK_*prefix, rule priorities, disabled rules and per-rule settings. - Custom rules as compiled Go rules or declarative JSON files in the configuration directory.
- Go 1.27 or newer to build from source. The JSON documents (settings, custom rules,
--json,--doctor --json) are handled byencoding/json/v2, which was stabilized in Go 1.27.GOTOOLCHAIN=auto, the default of current toolchains, downloads Go 1.27 automatically when needed; prebuilt release archives and package manager installs do not need Go at all. - No runtime dependencies. The compiled binary is self-contained.
- A supported shell for the alias: bash, zsh, fish, tcsh or PowerShell. On Windows, PowerShell is
recommended; a
cmd.exeshim is provided as well.
The repository doubles as a Homebrew tap:
brew tap leafevans/go-fuck https://github.com/leafevans/go-fuck
brew trust leafevans/go-fuck
brew install go-fuckThe formula installs the prebuilt binary for your platform, so no Go toolchain is
needed. Upgrade with brew upgrade go-fuck.
scoop bucket add go-fuck https://github.com/leafevans/go-fuck
scoop install go-fuckUpgrade with scoop update go-fuck.
The package is in the Arch User Repository and builds from source:
yay -S go-fuck # or: paru -S go-fuckOr install it manually with makepkg:
git clone https://aur.archlinux.org/go-fuck.git
cd go-fuck
makepkg -siUpgrade it with your AUR helper (yay -Syu or paru -Syu). The AUR package
targets x86_64; on other architectures use go install or the prebuilt binaries.
go install github.com/leafevans/go-fuck/v2/cmd/go-fuck@latestThe module path ends in /v2 because the major version is part of the Go module path; use the
command above, the module without the suffix only carries the old 1.x releases. The binary is
installed into $(go env GOPATH)/bin (%USERPROFILE%\go\bin on Windows). Make sure that
directory is on your PATH.
Download the archive for your operating system and architecture from the
releases page, unpack it and place the go-fuck
binary somewhere on your PATH. Linux and macOS archives contain the raw binary, Windows archives
contain go-fuck.exe. Every release ships a checksums.txt file that you can use to verify the
download.
git clone https://github.com/leafevans/go-fuck.git
cd go-fuck
make build # or: go build -o go-fuck ./cmd/go-fuckmake install runs go install ./cmd/go-fuck instead. On Windows the build produces
go-fuck.exe.
go-fuck is a normal executable; the alias function connects it to the previous command and evaluates
the corrected command that go-fuck prints. go-fuck --alias generates the function for the detected
shell, so the setup is the same everywhere and always matches the installed binary.
go-fuck --setup writes the alias line to the detected shell's configuration file and prints the
command that reloads it. Running it again is safe: when the line is already present go-fuck reports
that the shell is already configured and leaves the file untouched.
Pass --enable-experimental-instant-mode to configure instant mode
instead of the regular alias; shells without instant mode support warn and fall back to the regular
alias.
bash, zsh, fish and tcsh are configured when their configuration file already exists. PowerShell is
configured for every installed flavor: go-fuck asks powershell.exe and pwsh for their
$PROFILE (the Documents folder can be redirected, for example to OneDrive) and creates the profile
file when it is missing.
Add the line for your shell to its configuration file, then start a new shell or reload the file:
# bash: ~/.bashrc (or ~/.bash_profile on macOS)
# zsh: ~/.zshrc
eval "$(go-fuck --alias)"
# fish: ~/.config/fish/config.fish
go-fuck --alias | source
# tcsh: ~/.tcshrc
eval `go-fuck --alias`
# PowerShell: $PROFILE
iex "$(go-fuck --alias)"go-fuck detects the shell from TF_SHELL and otherwise from the process tree. If detection is
unreliable, for example when generating the alias from a setup script, set it explicitly:
TF_SHELL=fish go-fuck --alias.
Pass the name after --alias:
eval "$(go-fuck --alias FUCK)"The name has to be a valid shell function name. Without an argument, the alias is named after the
TF_ALIAS environment variable when it is set, and fuck otherwise.
The generated function exports a few variables, calls go-fuck and evaluates the corrected command that go-fuck prints on standard output:
| Variable | Set by | Purpose |
|---|---|---|
TF_SHELL |
the alias | shell name (bash, zsh, fish, tcsh, powershell); go-fuck uses it instead of guessing from the process tree |
TF_ALIAS |
the alias | name of the alias function; used in messages and by the repeat mechanism |
TF_ALIAS_VERSION |
the shell alias | alias format version (currently 3); go-fuck warns when an older alias is used |
TF_HISTORY |
the bash and zsh alias | the previous history entry, marked so a command typed over several lines stays one value |
TF_SHELL_ALIASES |
the bash and zsh alias | the shell aliases, expanded before the command is matched |
GOFUCK_ARGUMENT_PLACEHOLDER |
the alias | separates go-fuck's own arguments from the arguments of the corrected command; the legacy THEFUCK_ARGUMENT_PLACEHOLDER is accepted too |
The bash alias reads the previous entry with fc and the zsh alias reads it from the zsh
history array; both prefix the value with an internal marker so a command typed over several lines is
restored as one command. Older aliases that export a window of history lines are still supported. The
fish alias passes the previous command explicitly via its $history[1] variable. Because
TF_SHELL is always set by the alias, go-fuck uses the right shell-specific behavior even when the
process tree is unreliable (containers, sudo, wrappers).
The scripts/ directory contains two small Windows shims that mirror the scripts shipped with
thefuck:
scripts/fuck.bat— forcmd.exe. It passes the previous command from the doskey history to go-fuck and runs the corrected command in the current console.scripts/fuck.ps1— for PowerShell. The first call writes the go-fuck initialization to your profile and definesfuck()for the current session; later calls delegate to the function.
Put the script somewhere on your PATH and call fuck. The release archives of every platform
ship both shims in their scripts/ directory.
The introduction shows a git correction. Two more examples:
$ cd project/src
cd: no such file or directory: project/src
$ fuck
› mkdir -p project/src && cd project/src [enter · ↑↓ · ctrl+c]$ echo "hello'
zsh: unmatched "
$ fuck
› echo "hello" [enter · ↑↓ · ctrl+c]Common options:
| Option | Meaning |
|---|---|
-y, --yes, --yeah, --hard |
execute the first suggestion without asking |
-r, --repeat |
re-run go-fuck if the corrected command fails |
--force-command CMD |
fix CMD instead of the previous command |
--output-from FILE |
read the output of --force-command from FILE (or standard input with -) instead of re-running it |
--doctor |
print a diagnostic report: detected shell, alias, settings file, history and optional integrations; --doctor --json prints it as JSON |
--list-rules |
print the names of the built-in rules and exit (useful for the rules, exclude_rules and priority settings); with --json one object per rule with its priority and flags |
--json |
print the suggestions as JSON and exit (useful for scripts and editors; the shell alias passes it through unchanged) |
-d, --debug |
print debug information to stderr |
-v, --version |
print version/build information: a themed banner in a terminal, one line when piped; --debug --version adds the config path, instant mode, fzf and alias state |
-h, --help |
print the full option list |
--setup |
write the alias to the detected shell's configuration file (bash, zsh, fish, tcsh, PowerShell) |
--enable-experimental-instant-mode |
alias initialization flag: with --alias or --setup, configure the instant mode (bash/zsh on Linux and macOS, PowerShell on Windows) |
If fuck does nothing, or go-fuck cannot find the command that failed, run the diagnostic report:
$ go-fuck --doctorIt checks the detected shell, the alias in the shell configuration file (for PowerShell every
installed flavor's profile), the settings file (including ignored unknown keys), the command history
and the optional integrations (fzf and instant mode). For instant mode it validates
the logged shell's terminal log and warns when the instant mode line is no longer the last prompt
definition in the PowerShell profile. Warnings include the command that fixes them, and
--doctor --json prints the same report as JSON.
To list the rule names accepted by the rules, exclude_rules and priority settings, run:
$ go-fuck --list-rulesgo-fuck --list-rules --json prints one JSON object per rule with its name, priority,
enabled_by_default, requires_output and side_effect fields, which is convenient for
editor plugins and scripts that generate settings files.
The fuck shell function passes the information commands (--list-rules, --doctor,
--json, --alias, --help, --version) through to go-fuck unchanged, so
fuck --list-rules prints the rule list just like go-fuck --list-rules. Shell aliases generated by
older releases evaluate go-fuck's standard output as the corrected command instead, which is why
fuck --list-rules used to report that adb_unknown_command is not a command: the rule list was
executed line by line. After upgrading, the alias is refreshed by the next shell start when the
configuration file evaluates go-fuck --alias; to refresh it in a running shell run go-fuck --setup or
evaluate the alias again (go-fuck warns when it detects an outdated alias).
- You run a command and it fails. You type
fuck. - The shell function exports the shell name and history and calls
go-fuck. - go-fuck determines the command that failed, expands shell aliases and re-runs the command
with a short timeout (
wait_command, three seconds by default; commands listed inslow_commandsgetwait_slow_command, fifteen seconds by default) to capture its output. Instant mode skips this step and reads the output from the terminal log instead. - Every enabled rule is tried in priority order. A matching rule returns one or more corrected commands, which are sorted by priority and offered in the confirmation prompt.
- When you accept a suggestion, go-fuck applies the rule's side effect (if any), optionally writes the corrected command to the shell history and prints it on standard output.
- The shell function evaluates that output, so the corrected command runs in your shell exactly as if you had typed it.
The re-run is why the default mode works with any shell and any command without a terminal logger; the cost is running the failed command a second time, which is what instant mode avoids.
On Windows the command is re-run with the PowerShell flavor that started go-fuck, so PowerShell
native commands and syntax produce their real error messages instead of an unrelated cmd.exe
"not recognized" error. Processes that were not started from PowerShell, and processes whose alias
does not report the shell through GOFUCK_SHELL, keep the cmd.exe behavior.
Instant mode reads the output of the previous command from a terminal log instead of re-running the command. This is useful for slow, interactive or side effecting commands. It is implemented for bash and zsh on Linux and macOS and for PowerShell on Windows; other shells and platforms warn and fall back to the regular alias.
Enable it by passing the instant mode flag to the alias initialization in your shell configuration.
On bash, zsh and Windows PowerShell go-fuck --setup --enable-experimental-instant-mode writes that
line to your configuration file for you.
Linux and macOS:
# ~/.bashrc (or ~/.zshrc for zsh)
eval "$(go-fuck --alias --enable-experimental-instant-mode)"Windows (Windows PowerShell 5.1 and PowerShell 7):
# $PROFILE
iex "$(go-fuck --alias --enable-experimental-instant-mode)"The flag name contains experimental for historical reasons.
Restart the shell. The initialization replaces the terminal shell with a logged subshell: commands
keep working as usual, but go-fuck reads their output from the terminal log, so fuck does not
execute the failed command a second time. The log is a temporary file that is removed when the
logged shell exits.
On Windows the logged shell runs on a pseudo console (ConPTY), which requires Windows 10 version 1809 or newer. When ConPTY is not available, the regular alias is installed instead of closing the terminal.
The mode is covered by end-to-end tests: an interactive bash runs on a pseudo terminal on Linux and
macOS, and Windows PowerShell runs on a pseudo console on Windows; the tests feed a command, check
the terminal log and read the output back. Commands typed over several lines (a PowerShell block or
backtick continuation, PSReadLine's Shift+Enter input or a pasted command) are treated as one history
entry, and output rows that the terminal wrapped are joined again before the rules see them. When
instant mode is enabled, go-fuck --doctor also validates the active terminal log (readable, not
empty, prompt marker present).
Limitations:
- The shell profile runs twice per terminal start: once in the terminal shell and once in the logged subshell. Slow profiles delay the first prompt twice.
- Prompt frameworks that rebuild
PS1before every prompt (starship, powerlevel10k, ...) keep working, because the marker is re-added after the prompt functions run. A prompt definition added after the instant mode line can still hide the marker; on Windows the instant mode line has to be the last prompt definition in the profile. - Full screen programs such as
vimortmuxuse the alternate screen, whose content is not part of the log; the previous screen is restored when they exit. If the terminal is closed while such a program is still running, the end of the log may be missing. - On Windows the terminal size is polled, so a resized window reaches the logged shell with a short delay.
- The log keeps the newest 1 MiB of terminal output. The renderer is simpler than the reference implementation's pyte emulation: ANSI stripping and carriage return overwrites on Linux and macOS, a small screen model for the ConPTY stream on Windows, so full screen programs can still differ.
- Long output rows are joined again because the console wrapped them. On Windows a row that is one column short of the terminal width is treated as wrapped, so a line that happens to be exactly that wide and is followed by a newline can be merged with the next line.
The logged shell exports GOFUCK_INSTANT_MODE=true, which enables the instant_mode setting
automatically; there is no need to set it manually.
--json prints the correction result as JSON instead of opening the interactive prompt. It is
intended for editor plugins, scripts and AI agents; call go-fuck directly rather than through the
shell alias, because the alias evaluates whatever go-fuck prints.
When the caller already captured the output of the failed command (an editor, a terminal
integration or an AI agent usually did), pass it with --output-from FILE instead of letting go-fuck
re-run the command. Use - to read the output from standard input:
$ go-fuck --json --force-command "git push" --output-from failed-output.log
$ cat failed-output.log | go-fuck --json --force-command "git push" --output-from -This avoids re-running a command with side effects and works when the command cannot be run again. The output is treated exactly like captured output, so the same rules and suggestions apply.
$ go-fuck --json --force-command "git brnch"
{
"schema_version": 1,
"command": "git brnch",
"suggestions": [
{
"command": "git branch",
"priority": 1000,
"side_effect": false,
"rule": "git_unknown_command"
},
{
"command": "git brnch",
"priority": 5000,
"side_effect": false,
"rule": "history"
}
]
}The suggestions are ordered as they would be offered interactively. priority is the rule
priority (lower values are tried first). rule is the name of the rule that produced the
suggestion. side_effect reports whether the interactive mode would run a side effect, for
example git add, before the corrected command. The history rule can repeat
the original command as a fallback suggestion; consumers that only want real corrections can skip
suggestions equal to command.
output is the captured standard output and standard error of the failed command; it is omitted
when the output could not be captured. Output larger than 32 KiB is cut at a UTF-8 boundary and
output_truncated is set to true. The example above omits the output field for brevity.
In JSON mode go-fuck does not execute the corrected command, does not apply side effects and does
not update the shell history; the caller decides what to do with the suggestions. The exit code is
0 once the JSON was written, even when no rule matched and suggestions is empty.
The JSON document is a stable machine readable contract. schema_version is 1 for the whole
1.x series; it is only incremented for a breaking layout change, while new optional fields may be
added in minor releases. Consumers must ignore unknown fields and must not rely on the key order.
The document is always written to stdout; diagnostics stay on stderr.
Settings are stored in settings.json inside the go-fuck directory of the user configuration
directory returned by Go's os.UserConfigDir():
| Operating system | Path |
|---|---|
| Linux / BSD | ~/.config/go-fuck/settings.json (or $XDG_CONFIG_HOME/go-fuck/settings.json) |
| macOS | ~/Library/Application Support/go-fuck/settings.json |
| Windows | %AppData%\go-fuck\settings.json |
The file is created with the default settings on first use. JSON does not support comments, so the
generated file contains an explanatory _comment field; it is ignored when the file is loaded.
Unknown keys are ignored by default, so a settings file written by a newer go-fuck keeps working
with an older one. They are reported by go-fuck --doctor and by a correction run, so a typo such
as rule instead of rules does not go unnoticed. Rule names in rules, exclude_rules and
priority are validated the same way: an unknown name is reported with its setting, because a typo
would otherwise silently ignore the rule or its priority override. Contradictory rule settings are
reported too: a rule that appears in both rules and exclude_rules, or a priority override for an
excluded or disabled rule, would be silently ignored (exclude_rules wins). Values out of range are
reported the same way and replaced with the defaults: wait_command and wait_slow_command must be between 1 and
3600 seconds (a zero or negative value used to kill the re-run command immediately), and
history_limit and num_close_matches must not be negative. Set strict_settings (or
GOFUCK_STRICT_SETTINGS=true) to reject unknown keys instead: the file is reported as invalid and
not applied. Invalid JSON or a value of the wrong type is always reported and the file is not
applied, so go-fuck falls back to the built-in defaults instead of running with a half applied
configuration. From 1.0.0
the keys above and their meaning are frozen; new optional keys may be added in minor releases.
A minimal file that customizes a few values:
{
"rules": ["All rules enabled"],
"exclude_rules": ["git_push"],
"wait_command": 10,
"require_confirmation": true,
"priority": {
"cd_mkdir": 100
},
"settings": {}
}All fields:
| Key | Type | Default | Meaning |
|---|---|---|---|
rules |
array of strings | ["All rules enabled"] |
Rules that are enabled. The sentinel value "All rules enabled" enables every rule that is enabled by default; list explicit rule names to enable exactly those rules. |
exclude_rules |
array of strings | [] |
Rules that are never loaded, even when enabled. |
wait_command |
integer | 3 |
Seconds to wait for the output of the re-run command. |
require_confirmation |
boolean | true |
Ask before executing a corrected command. |
fzf |
boolean | false |
Use fzf as the selection prompt when it is installed. Falls back to the built-in prompt automatically. |
strict_settings |
boolean | false |
Reject unknown top-level keys as an error instead of ignoring and warning about them. |
no_colors |
boolean | false |
Disable colored output. |
debug |
boolean | false |
Print debug information to stderr. |
priority |
object of integer | {} |
Per-rule priority overrides. Lower values are tried first; the built-in default is 1000. |
history_limit |
integer | 0 |
Maximum number of shell history lines that are read. 0 means no limit. |
alter_history |
boolean | true |
Write the corrected command back to the shell history. |
wait_slow_command |
integer | 15 |
Seconds to wait for the output of commands listed in slow_commands. |
slow_commands |
array of strings | ["lein", "react-native", "gradle", "./gradlew", "vagrant"] |
Commands that are expected to be slow to re-run. |
repeat |
boolean | false |
If the corrected command fails, run go-fuck again. |
instant_mode |
boolean | false |
Inside the logged shell, read the previous output from the terminal log instead of re-running the command; the instant mode alias sets this automatically. See Instant mode. |
num_close_matches |
integer | 3 |
Maximum number of close matches suggested for misspelled commands. |
env |
object of string | {"LC_ALL": "C", "LANG": "C", "GIT_TRACE": "1"} |
Environment variables added when the failed command is re-run. |
excluded_search_path_prefixes |
array of strings | [] |
PATH prefixes that are skipped when searching for executables. |
settings |
object | {} in the default file |
Rule-specific string settings, read by rules with conf.Current().String(key, default). |
Every setting can be set with an environment variable. The modern prefix is GOFUCK_; the legacy
THEFUCK_ prefix from the original implementation is still recognized, so an existing thefuck
configuration keeps working. For example, GOFUCK_WAIT_COMMAND=10 and
THEFUCK_WAIT_COMMAND=10 do the same thing. If both prefixes are set for the same setting, the
legacy THEFUCK_* variable is applied last and wins.
| Suffix | Type | Example | Corresponding setting |
|---|---|---|---|
RULES |
colon separated list | GOFUCK_RULES='sudo:no_command' |
rules; the token DEFAULT_RULES stands for "All rules enabled" |
EXCLUDE_RULES |
colon separated list | GOFUCK_EXCLUDE_RULES='git_push' |
exclude_rules |
WAIT_COMMAND |
integer seconds | GOFUCK_WAIT_COMMAND=10 |
wait_command |
REQUIRE_CONFIRMATION |
boolean | GOFUCK_REQUIRE_CONFIRMATION=false |
require_confirmation |
FZF |
boolean | GOFUCK_FZF=true |
fzf |
STRICT_SETTINGS |
boolean | GOFUCK_STRICT_SETTINGS=true |
strict_settings |
NO_COLORS |
boolean | GOFUCK_NO_COLORS=true |
no_colors |
DEBUG |
boolean | GOFUCK_DEBUG=true |
debug |
PRIORITY |
rule=priority list separated by colons |
GOFUCK_PRIORITY='cd_mkdir=100:git_push=900' |
priority |
HISTORY_LIMIT |
integer | GOFUCK_HISTORY_LIMIT=2000 |
history_limit |
ALTER_HISTORY |
boolean | GOFUCK_ALTER_HISTORY=false |
alter_history |
WAIT_SLOW_COMMAND |
integer seconds | GOFUCK_WAIT_SLOW_COMMAND=30 |
wait_slow_command |
SLOW_COMMANDS |
colon separated list | GOFUCK_SLOW_COMMANDS='lein:gradle' |
slow_commands |
REPEAT |
boolean | GOFUCK_REPEAT=true |
repeat |
INSTANT_MODE |
boolean | GOFUCK_INSTANT_MODE=false |
instant_mode |
NUM_CLOSE_MATCHES |
integer | GOFUCK_NUM_CLOSE_MATCHES=5 |
num_close_matches |
EXCLUDED_SEARCH_PATH_PREFIXES |
list separated by the OS path list separator (: on Linux/macOS, ; on Windows) |
GOFUCK_EXCLUDED_SEARCH_PATH_PREFIXES='/snap:/mnt' (Linux/macOS), 'C:\\Tools;C:\\Other' (Windows) |
excluded_search_path_prefixes |
The env map can only be set in settings.json. Booleans accept true and false
(case-insensitive).
Settings are applied in increasing order of precedence:
- built-in defaults,
settings.json,- environment variables,
- command line options such as
-y,-dand-r.
By default go-fuck asks before running the corrected command. The prompt shows the suggestion and the available actions:
| Key | Action |
|---|---|
Enter |
execute the selected command |
↑, Ctrl+N, k, e |
select the previous suggestion |
↓, Ctrl+P, j, n |
select the next suggestion |
Ctrl+C, q |
abort without running anything |
Disable the prompt with require_confirmation: false in settings.json or by passing -y.
If fzf is installed, go-fuck can use it as the selection prompt.
Enable it once in settings.json:
{
"fzf": true
}or per shell with export GOFUCK_FZF=true. When fzf runs, the suggestions are listed with a
fuck> prompt (Enter selects, Esc aborts); go-fuck falls back to its built-in prompt
automatically when fzf is not installed or fails. -y/require_confirmation: false still skips
the selection entirely.
The built-in rules are compiled into the binary, and declarative JSON rules can be loaded from the configuration directory (see Creating custom rules). Each rule decides whether it applies to a failed command and returns one or more corrected commands. There are 251 built-in rules: 169 ported from the reference implementation plus 82 go-fuck specific rules for failures that thefuck does not handle, including the GitHub and GitLab CLIs, kubectl/kind/kustomize, uv, cargo, Helm, pnpm, the npm, pnpm, yarn and uv lock file checks, the Go toolchain and go.sum, Node.js, bun, Deno, Docker Compose, just, Poetry, make, the go-task runner, minikube, Bundler, Chocolatey, the .NET CLI, rustup toolchains, the Dart and Flutter command-line tools, the uv and Cargo project setup corrections, the PowerShell file operation and cmd.exe corrections, git switch and safe.directory corrections and divergent, clobbered or blocked git operations. The list below is generated from the compiled rules:
adb_unknown_commandag_literalapt_getapt_get_searchapt_invalid_operationapt_list_upgradableapt_upgradeaws_cliaz_clibrew_cask_dependencybrew_installbrew_linkbrew_reinstallbrew_uninstallbrew_unknown_commandbrew_update_formulabun_script_not_foundbundle_unknown_commandcargocargo_missing_bench_targetcargo_missing_bincargo_missing_example_targetcargo_missing_manifestcargo_missing_test_targetcargo_no_commandcargo_unknown_argumentcargo_unknown_commandcat_dircd_correctioncd_cscd_mkdircd_parentchmod_xchoco_installchoco_unknown_commandcmd_cd_mkdircmd_missing_directorycmd_missing_filecmd_mkdir_existingcmd_pushd_mkdircmd_rmdir_nonemptycomposer_not_commandconda_mistypecp_create_destinationcp_omitting_directorycpp11dart_unknown_commanddeno_task_not_founddirty_untardirty_unzipdjango_south_ghostdjango_south_mergednf_no_such_commanddocker_compose_unknown_servicedocker_image_being_used_by_containerdocker_logindocker_not_commanddotnet_unknown_argumentdotnet_unknown_commanddryfab_command_not_foundfix_alt_spacefix_fileflutter_unknown_commandgem_unknown_commandgh_unknown_commandgh_unknown_flaggit_addgit_add_forcegit_amend_initial_commitgit_bisect_usagegit_branch_0flaggit_branch_deletegit_branch_delete_checked_outgit_branch_existsgit_branch_listgit_branch_missinggit_checkoutgit_checkout_unstagedgit_clone_git_clonegit_clone_missinggit_commit_addgit_commit_amendgit_commit_resetgit_diff_no_indexgit_diff_stagedgit_dubious_ownershipgit_fetch_clobber_taggit_fix_stashgit_flag_after_filenamegit_help_aliasedgit_hook_bypassgit_lfs_mistypegit_main_mastergit_mergegit_merge_unrelatedgit_merge_unstagedgit_not_commandgit_pullgit_pull_clonegit_pull_divergentgit_pull_uncommitted_changesgit_pushgit_push_different_branch_namesgit_push_forcegit_push_pullgit_push_without_commitsgit_rebase_merge_dirgit_rebase_no_changesgit_rebase_unstagedgit_remote_already_existsgit_remote_deletegit_remote_seturl_addgit_rm_local_modificationsgit_rm_recursivegit_rm_stagedgit_stashgit_stash_popgit_submodule_missinggit_switch_existing_branchgit_switch_unknown_branchgit_tag_forcegit_tag_missinggit_two_dashesgit_unknown_optiongit_unknown_remotegit_worktree_branch_usedgit_worktree_remove_missingglab_unknown_commandgo_install_versiongo_missing_filego_missing_modulego_missing_packagego_missing_sumgo_mod_initgo_rungo_unknown_commandgo_unknown_flaggradle_no_taskgradle_wrappergrep_arguments_ordergrep_recursivegrunt_task_not_foundgulp_not_taskhas_exists_scripthelm_unknown_commandheroku_multiple_appsheroku_not_commandhistoryhostscliifconfig_device_not_foundjavajavacjust_unknown_recipekind_unknown_commandkubectl_unknown_commandkustomize_unknown_commandlein_not_taskln_no_hard_linkln_s_orderlong_form_helpls_allls_lahmake_unknown_targetmanman_no_spacemercurialminikube_unknown_commandmissing_space_before_subcommandmkdir_pmvn_no_commandmvn_unknown_lifecycle_phasenixos_cmd_not_foundno_commandno_such_filenode_missing_modulenode_script_not_foundnpm_ci_lock_mismatchnpm_ci_missing_lockfilenpm_missing_scriptnpm_peer_dependency_conflictnpm_run_scriptnpm_wrong_commandomnienv_no_such_commandopenpacmanpacman_invalid_optionpacman_not_foundpath_from_historyphp_spip_installpip_unknown_commandpnpm_command_not_foundpnpm_frozen_lockfilepoetry_unknown_commandport_already_in_usepowershell_cat_directorypowershell_cd_unquoted_pathpowershell_missing_directorypowershell_missing_filepowershell_mkdir_existingpowershell_remove_recursepowershell_set_locationpowershell_unix_flagsprove_recursivelypython_commandpython_executepython_module_errorquotation_marksrails_migrations_pendingreact_native_command_unrecognizedremove_shell_prompt_literalremove_trailing_cedillarm_dirrm_rootrustup_toolchain_missingrustup_unknown_subcommandscm_correctionsed_unterminated_ssl_lsssh_known_hostssudosudo_command_from_user_pathswitch_langsystemctltask_unknown_taskterraform_initterraform_no_commandtest.pytmuxtouchtsuru_logintsuru_not_commandunknown_commandunsudouv_locked_lockfileuv_missing_projectuv_pip_no_venvuv_script_not_founduv_unknown_argumentuv_unknown_subcommandvagrant_upwhoisworkon_doesnt_existswrong_hyphen_before_subcommandyarn_aliasyarn_command_not_foundyarn_command_replacedyarn_frozen_lockfileyarn_helpyum_invalid_operation
Regenerate it after adding or renaming a rule:
go run ./tools/gen-rule-list # or: make rules-list
make rules-list-check # fail when README.md is out of dateThe same names can be used in the rules, exclude_rules and priority settings.
There are two ways to add a rule.
go-fuck loads extra rules from JSON files in the rules directory inside its configuration
directory:
| Operating system | Directory |
|---|---|
| Linux / BSD | ~/.config/go-fuck/rules (or $XDG_CONFIG_HOME/go-fuck/rules) |
| macOS | ~/Library/Application Support/go-fuck/rules |
| Windows | %AppData%\go-fuck\rules |
Each file contains one rule:
{
"name": "git_remote_typo",
"enabled": true,
"priority": 900,
"match": {
"script": "^git remote add (\\w+)$",
"output": "No such remote '([^']+)'"
},
"commands": ["git remote remove {1}"]
}nameis required, must match^[a-z0-9][a-z0-9_.]*$and must not collide with a built-in rule.match.scriptandmatch.outputare regular expressions; at least one is required. Whenmatch.outputis present the command output must be available, otherwise the rule is skipped.commandscontains the suggested corrections.{0},{1}, ... are replaced with the capture groups ofmatch.output;{script}is replaced with the original command line.enabled(defaulttrue) andpriority(default1000) behave like the flags of built-in rules and can be overridden with therules,exclude_rulesandprioritysettings.
The directory is read on every invocation, so a new rule is active the next time you run fuck;
no restart or rebuild is needed. Rules are purely declarative: they cannot run commands as side
effects or access the network. Invalid files are reported on stderr and skipped without affecting
the built-in rules.
Adding a rule to the binary still follows the porting workflow:
- Read PORTING.md. It describes the rule interface, the helpers and the conventions.
- Create
internal/rules/<rule_name>.goandinternal/rules/<rule_name>_test.go, port the test cases from thefuck and register the rule from aninitfunction. - Run the checks described in CONTRIBUTING.md.
- Regenerate the rule list in this file with
make rules-list.
JSON rules are the lightweight option for local and machine specific corrections; compiled-in rules are the right place for generally useful rules and for rules that need to inspect files or run external commands.
go-fuck is a reimplementation, not a drop-in replacement for every thefuck feature:
- Complete rule port plus extras. All 169 rules of the reference implementation are ported, plus 82 go-fuck specific rules; the list in Rules is authoritative. Porting conventions are documented in PORTING.md.
- Instant mode covers Linux, macOS and Windows. It reads the previous command output from a terminal log instead of re-running the command: bash and zsh on Linux and macOS, PowerShell on Windows (ConPTY); other shells and platforms fall back to the regular alias.
- In-memory memoization instead of an on-disk cache. Rule results are cached only for one
invocation, while thefuck's
@cachepersisted values between runs. - Compiled rules with declarative JSON extensions. There is no Python rule API or third-party rule package format; custom rules are JSON files that cannot run code or side effects.
- No Python-apt database. The apt rules are ported without the database installed by
python-commandnotfound. - JSON settings and environment compatibility. Settings live in
settings.jsoninstead ofsettings.py; the legacyTHEFUCK_*environment variables are still accepted next toGOFUCK_*. - Explicit alias setup. Instead of thefuck's first-run detection, go-fuck uses
--setup, which reports what it changed, is safe to run again and configures every installed PowerShell flavor.
Contributions are welcome. Read CONTRIBUTING.md for the development setup, the
make targets and the conventions. In short:
go build ./...
go test ./... -count=1
go vet ./...
make fmt-checkCommits follow Conventional Commits (feat:, fix:,
docs:, test:, chore:, refactor:).
MIT. See LICENSE.
- thefuck by nvbn and its contributors, which this project reimplements. The rules, their behavior and many messages are ported from it.
- The original idea comes from a tweet by @liamosaur.
go-fuck is an independent project and is not affiliated with thefuck.

