id       = "stow"
name     = "GNU Stow"
homepage = "https://www.gnu.org/software/stow/"
description = "A symlink farm manager which takes distinct packages of software located in separate directories and makes them appear installed in one place."
executables   = ["stow"]

[dotfiles]

# https://www.gnu.org/software/stow/manual/stow.html — the "Resource Files"
# section: "Default command line options may be set in .stowrc (current
# directory) or ~/.stowrc (home directory). These are parsed in that order,
# and are appended together if they both exist." The "Ignore Lists" section:
# "In the absence of this package-specific ignore list, Stow will instead use
# the contents of ~/.stow-global-ignore, if it exists." The .stowrc and
# .stow-local-ignore in a package directory belong to that package, not to
# the user, so they are not here.
paths = [
  "~/.stowrc",
  "~/.stow-global-ignore",
]

exclude = []

# Stow has no credentials: it only ever creates and removes symlinks.
secret = []

# Both files are read once while stow parses its options, and stow exits; no
# resident process holds either of them.
side_effect = false

# No machine_lines. The obvious candidates in .stowrc are --dir and --target,
# but the same manual section documents that "the value of an option may
# contain a shell variable or ~" and that both are expanded, so the spelling
# users are told to write (--target=~/) is portable on purpose. The global
# ignore list is a set of regular expressions and is machine-independent by
# construction.

[commands]
format = 1
label = "Stow packages"
description = "Symlink, unstow or restow packages from a stow directory. Version and help flags are left out."
quality = "ai-draft"
base = "fig:stow"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.source]]
id = "fig"
kind = "completion"
url = "https://github.com/withfig/autocomplete/blob/master/src/stow.ts"
license = "MIT"

[[commands.field]]
id = "packages"
label = "Packages"
description = "Package directories inside the stow directory."
type = "string"
position = 0
multiple = true
sources = ["fig"]

[[commands.field]]
id = "dir"
label = "Stow directory"
description = "Defaults to the current directory."
type = "path"
option = ["--dir", "-d"]
path = { kind = "directory", role = "input", must_exist = true }
sources = ["fig"]

[[commands.field]]
id = "target"
label = "Target directory"
description = "Defaults to the parent of the stow directory."
type = "path"
option = ["--target", "-t"]
path = { kind = "directory", role = "output", must_exist = true }
sources = ["fig"]

[[commands.field]]
id = "simulate"
label = "Dry run"
description = "Show what would happen without changing the filesystem."
type = "boolean"
option = ["--no", "-n"]
sources = ["fig"]

[[commands.field]]
id = "delete"
label = "Unstow"
description = "Remove the packages from the target directory."
type = "boolean"
option = ["--delete", "-D"]
sources = ["fig"]

[[commands.field]]
id = "restow"
label = "Restow"
description = "Unstow then stow again, pruning obsolete links."
type = "boolean"
option = ["--restow", "-R"]
sources = ["fig"]

[[commands.field]]
id = "dotfiles"
label = "Dotfiles"
description = "Rename dot-prefixed entries in packages to hidden files."
type = "boolean"
option = ["--dotfiles"]
sources = ["fig"]

[[commands.field]]
id = "no_folding"
label = "No folding"
type = "boolean"
option = ["--no-folding"]
sources = ["fig"]

[[commands.field]]
id = "adopt"
label = "Adopt existing files"
description = "Moves existing target files into the stow directory."
type = "boolean"
option = ["--adopt"]
effect = "overwrite"
sources = ["fig"]

[[commands.field]]
id = "ignore"
label = "Ignore pattern"
description = "Perl regex of file name endings to ignore."
type = "string"
option = ["--ignore"]
multiple = true
sources = ["fig"]

[[commands.field]]
id = "verbose"
label = "Verbosity"
description = "0 to 5."
type = "integer"
option = ["--verbose"]
value_style = "equals"
sources = ["fig"]

[[commands.task]]
id = "stow"
label = "Stow packages"
fields = ["packages", "dir", "target", "simulate", "dotfiles"]
required = ["packages"]

[[commands.task]]
id = "unstow"
label = "Unstow packages"
set = { delete = [true] }
lock = ["delete"]
fields = ["packages", "dir", "target", "simulate", "delete"]
required = ["packages"]

[[commands.task]]
id = "restow"
label = "Restow packages"
set = { restow = [true] }
lock = ["restow"]
fields = ["packages", "dir", "target", "simulate", "restow", "dotfiles"]
required = ["packages"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["packages", "dir", "target", "simulate", "delete", "restow", "dotfiles"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["no_folding", "adopt", "ignore", "verbose"]