Application settings
Application preferences live in tracked files under
symlinks/.
Edit those sources, not installed copies or generated files. A home-directory
link may make this checkout live configuration, so some changes take effect
immediately.
Installing an application and configuring it are separate changes. Package management chooses applications; symlink declarations choose which settings files reach your home. The files themselves control application behavior. This guide helps you find the right source, then covers preferences shared by the shells.
Find a common change
Section titled “Find a common change”| I want to change… | Start here |
|---|---|
| Git identity, defaults, or aliases | config/git/config, config/git/aliases, and Git settings |
| Bash/Zsh environment or shared commands | Shared shell sources below |
| Bash or Zsh prompt | config/bash/prompt.bash or config/zsh/prompt.zsh |
| PowerShell behavior | PowerShell configuration |
| Terminal colors, fonts, or keys | Alacritty settings or Windows Terminal settings |
| tmux behavior | config/tmux/tmux.conf |
| Desktop shortcuts, monitors, bar, or appearance | Arch desktop |
| Editor settings, keybindings, or plugins | Visual Studio Code or Vim and Neovim |
| Agent preferences, skills, or integrations | Agent configuration |
| SSH client defaults | ssh/config |
Source paths in this table are beneath symlinks/. Linked source files open
the public repository on GitHub; edit the corresponding file in your own
checkout. Paths such as ~/.config/git/config describe installed locations,
not a second source to maintain.
Make the change
Section titled “Make the change”For a preference in an already-linked file, edit the source and use the
application’s normal reload or restart behavior. You do not need to recreate
the link. Some settings UIs, including VS Code’s, can write back through the
link; review git diff afterward.
For a new file or destination, update
conf/symlinks.toml,
then preview the link task before applying. Back up existing targets: installing a managed
link can replace a file without making a backup. The
first-run example shows the
declaration-to-source-to-home relationship.
Use a private overlay for machine-specific alternatives. An overlay can replace a linked source, but does not merge arbitrary application file contents. Keep credentials and private identity details out of public sources.
Shell application configuration
Section titled “Shell application configuration”| Setting | Source |
|---|---|
| Bash and Zsh interactive startup | bashrc, zshrc |
| Bash and Zsh login profiles | bash_profile, zprofile |
| Shared shell environment and pager defaults | config/shell/profile.sh |
| Shared commands and aliases | config/shell/aliases.sh |
| Zsh completion | config/zsh/completion.zsh |
| Zsh command helpers | config/zsh/functions/ |
| Git aliases | config/git/aliases |
| Download naming and timestamping | config/wgetrc |
Environment and paging
Section titled “Environment and paging”The login profiles source shared environment settings; interactive startup
files source shared aliases when present. Put
behavior common to Bash and Zsh in config/shell/; keep shell-specific
behavior in its own startup file. The Windows guide
covers PowerShell’s separate profile.
The shared profile supplies defaults for XDG directories, terminal information,
and the less pager. Customize these in config/shell/profile.sh or supply
environment overrides before startup. The source records each setting’s defaults.
Completion
Section titled “Completion”Zsh uses normal completion on the first Tab. Repeat Tab to try approximate matches.
Dotfiles command completion comes from the CLI’s Shell completions task, not a separate hand-edited selector list.
Git shortcuts
Section titled “Git shortcuts”Common shortcuts include:
| Command | Purpose |
|---|---|
git st | Show concise status and branch information |
git dis | Review staged changes |
git lo | Show a compact commit graph |
git gr <pattern> | Search tracked content |
Run git alias to list all configured aliases.
Alias definitions belong in the linked Git files. Desired global key/value overrides belong in Git settings.
Downloads and archives
Section titled “Downloads and archives”Wget preserves URL filenames and uses timestamping to reuse unchanged
downloads. Change its shared defaults in config/wgetrc.
In Zsh, extract <file>
chooses the extraction tool for the archive format. That tool must be installed;
RPM extraction uses bsdtar, supplied by libarchive on Arch.
Keep the extractor’s normal path protections when customizing the helper.
Extract untrusted archives into a fresh directory and review the contents
before running anything; see Security and trust.