Jump to content

# Shell package guidelines

From ArchWiki

Related articles

- Command-line shell

## Install

For users to change shells, the shell must appear in `/etc/shells`. Most shell packages have install scripts like below:

    shellname.install

    post_install() {
        grep -Fqx /bin/shellname /etc/shells || echo /bin/shellname >>/etc/shells
        grep -Fqx /usr/bin/shellname /etc/shells || echo /usr/bin/shellname >>/etc/shells
    }

    post_upgrade() {
        post_install
    }

    post_remove() {
        sed -i -r '/^(\/usr)?\/bin\/shellname$/d' etc/shells
    }

## Shell completions

Most shells provide a built in set of completions for a few common commands while also scanning at least one system directory for functions that may be supplied by other packages. The following table is a summary of where packages may place completion files and what the files should be named.

Shell | Directory | File
--- | --- | ---
Bash | `/usr/share/bash-completion/completions/` | `binary_name`
Elvish | `/usr/share/elvish/lib/` | `binary_name.elv`
Fish | `/usr/share/fish/vendor_completions.d/` | `binary_name.fish`
Zsh | `/usr/share/zsh/site-functions/` | `_binary_name`

Other shells:

- Nushell provides some default completions, but does not have a system-wide directory where completions can be provided yet[1]. For packages that generate Nushell completion functions, one solution would be to package them `/usr/share/nushell/autoload/binary_name.nu` and use a `post_install()` function to print a tip for users to add a `use /path/to/file` statement to their configs.

Tip As a general rule, packages should have neither depends nor optdepends on shells. Just because they happen to supply completions for them does not imply a package dependency relationship any way. The exception is packages that do not supply their own completions; the completions do not exist in the default shell package, but they are provided by the supplemental collection packages bash-completion or zsh-completions. When completion files exist in these packages, add them to `optdepends`.

## Shell functions or modules

Shell | Directory | File
--- | --- | ---
Elvish | `/usr/share/elvish/lib/` | `module_name.elv`
Fish | `/usr/share/fish/vendor_functions.d/` | `function_name.fish`
Zsh | `/usr/share/zsh/site-functions/` | `function_name`

Category:

- Arch package guidelines

Shell package guidelines
Add topic