id       = "ranger"
name     = "ranger"
homepage = "https://ranger.fm"
description = "ranger is a console file manager with VI key bindings."
# The logo ranger.fm serves as its own icon.
icon     = "https://ranger.fm/ranger_logo.png"
executables   = ["ranger", "rifle"]
platforms = ["macos", "linux"]

[dotfiles]

# ranger(1), FILES: "ranger reads several configuration files which are located
# in $HOME/.config/ranger or $XDG_CONFIG_HOME/ranger if $XDG_CONFIG_HOME is
# defined" — rc.conf ("a list of commands which are executed on startup"),
# commands.py, rifle.conf ("the configuration file for the built-in file
# launcher"), scope.sh ("a script that handles file previews"), colorschemes/
# and plugins/.
#
# ranger/core/main.py backs that up: --confdir defaults to
# `xdg_path('XDG_CONFIG_HOME') or CONFDIR`, and ranger/__init__.py sets
# CONFDIR = os.path.expanduser('~/.config/ranger'). Reading $XDG_CONFIG_HOME
# with ~/.config as the fallback is what [configHome] means, on macOS too.
paths = ["[configHome]/ranger/"]

# The STORAGE files the man page lists — bookmarks, copy_buffer, history,
# tagged — are not in the directory above: core/fm.py builds them with
# datapath(), which is --datadir, `xdg_path('XDG_DATA_HOME') or
# ~/.local/share/ranger`. They are state and they live elsewhere, so nothing
# needs carving out for them.

secret = []

# No machine_lines: rc.conf and rifle.conf are keybindings, settings and the
# rules that pick a program per file type — exactly what a user wants on the
# next machine. Absolute paths do appear in the bookmarks file, which is in the
# data directory and not synced.

[commands]
format = 1
label = "Browse files with ranger"
description = "Open ranger on one or more paths, optionally as a file or directory chooser. Config and cache directory overrides are included; key-listing and copy-config options are not."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "man"
kind = "manual"
url = "https://manpages.debian.org/unstable/ranger/ranger.1.en.html"
revision = "2026-10-27"
evidence = '''
path ...
-d, --debug
-c, --clean
--cachedir=dir
-r dir, --confdir=dir
--datadir=dir
--choosefile=targetfile
--choosefiles=targetfile
--choosedir=targetfile
--selectfile=targetfile
--show-only-dirs
'''

[[commands.field]]
id = "paths"
label = "Paths"
description = "Each path opens in a tab. Empty means the current directory."
type = "path"
path = { kind = "any", role = "input" }
position = 0
multiple = true
sources = ["man"]

[[commands.field]]
id = "clean"
label = "Clean mode (no config files read or written)"
type = "boolean"
option = ["--clean", "-c"]
sources = ["man"]

[[commands.field]]
id = "debug"
label = "Debug mode"
type = "boolean"
option = ["--debug", "-d"]
sources = ["man"]

[[commands.field]]
id = "confdir"
label = "Config directory"
type = "path"
path = { kind = "directory", role = "input" }
option = ["--confdir", "-r"]
sources = ["man"]

[[commands.field]]
id = "cachedir"
label = "Cache directory"
type = "path"
path = { kind = "directory", role = "input" }
option = ["--cachedir"]
sources = ["man"]

[[commands.field]]
id = "datadir"
label = "Data directory"
type = "path"
path = { kind = "directory", role = "input" }
option = ["--datadir"]
sources = ["man"]

[[commands.field]]
id = "choosefile"
label = "Write picked file to"
description = "Exit on opening a file and write its absolute path to this file."
type = "path"
path = { kind = "file", role = "output" }
option = ["--choosefile"]
effect = "overwrite"
sources = ["man"]

[[commands.field]]
id = "choosefiles"
label = "Write picked files to"
type = "path"
path = { kind = "file", role = "output" }
option = ["--choosefiles"]
effect = "overwrite"
sources = ["man"]

[[commands.field]]
id = "choosedir"
label = "Write last directory to"
type = "path"
path = { kind = "file", role = "output" }
option = ["--choosedir"]
effect = "overwrite"
sources = ["man"]

[[commands.field]]
id = "show_only_dirs"
label = "Show only directories"
type = "boolean"
option = ["--show-only-dirs"]
sources = ["man"]

[[commands.task]]
id = "clean"
label = "Start without config"
fields = ["paths", "clean"]
required = []
set = { clean = [true] }

[[commands.task]]
id = "choose_dir"
label = "Pick a directory"
fields = ["paths", "choosedir", "show_only_dirs"]
required = ["choosedir"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["paths", "clean", "show_only_dirs", "choosedir", "choosefile", "choosefiles"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["debug", "confdir", "cachedir", "datadir"]