Configuration Guide

hideDot uses a YAML configuration file (default: hidedot.conf.yaml) to manage your dotfiles setup. The configuration file supports multiple sections that can be executed in sequence.

Full Configuration Example

- defaults:
    link:
      relink: true   # Replace incorrect symlinks
      force: true    # Remove existing files/directories
      backup: true   # Automatic backups (on unless set to false)
  
  profile: personal  # Optional: profile name for filtering
  
  create:
    - ~/.config
    - ~/.local/bin
  
  link:
    ~/.config/nvim: ~/.mydotfiles/nvim
    ~/.zshrc: ~/.mydotfiles/zsh/zshrc
  
  git:
    ~/.oh-my-zsh:
      url: https://github.com/ohmyzsh/ohmyzsh.git
      description: "Oh My Zsh"
  
  shell:
    - [touch ~/.hushlogin, "Create hushlogin"]
    - command: "cat > ~/.config/myapp/config.json"
      description: "Create config file"
      stdin: '{"key": "value"}'
  
  hooks:
    pre_link:
      - echo "Starting link process..."
    post_link:
      - echo "Links created successfully!"

Configuration Sections

Defaults Section

defaults:
  link:
    relink: true              # Replace incorrect symlinks
    force: true               # Remove existing files/directories
    backup: true              # Create backups before overwriting
    remove_duplicates: false  # Delete other symlinks pointing at the same source

Key	Default when omitted	Effect
relink	false	Replace a symlink that points somewhere else
force	false	Replace a target that is not a symlink at all
backup	true	Copy the target to ~/.hidedot-backups before replacing it
remove_duplicates	false	Delete other symlinks in the target's directory that point at the same source

Note that backup is the one key that defaults to on: leaving it out of a defaults block keeps backups enabled. Only backup: false or --no-backup turns them off, and if a backup cannot be written hideDot leaves the original file in place rather than overwriting something it cannot restore.

remove_duplicates deletes files, so it is off unless you ask for it. Targets declared anywhere in your config are never removed by it — pointing two entries at the same source (~/.bashrc and ~/.bash_profile, for instance) is a supported setup.

Profile Section

Use profiles to organize configs for different machines or environments:

profile: personal  # or "work", "server", etc.

Run with --profile personal to only apply configs with matching profile.

Create Section

Use the create section to ensure directories exist:

create:
  - ~/.config
  - ~/.local/bin

Link Section

The link section manages symlinks between your dotfiles and their target locations:

link:
  ~/.config/nvim: ~/.mydotfiles/nvim
  ~/.zshrc: ~/.mydotfiles/zsh/zshrc

Git Section

Clone git repositories with optional descriptions:

git:
  ~/.oh-my-zsh:
    url: https://github.com/ohmyzsh/ohmyzsh.git
    description: "Oh My Zsh"

Shell Section

Execute shell commands with descriptions. Two formats are supported:

Array format (simple):

shell:
  - [touch ~/.hushlogin, "Create hushlogin"]
  - [fc-cache -fv, "Rebuild font cache"]

Map format (with stdin support):

shell:
  - command: "cat > ~/.config/myapp/config.json"
    description: "Create config file"
    stdin: '{"key": "value"}'

Hooks Section

Run custom commands at specific points in the process:

hooks:
  pre_link:
    - echo "Starting link process..."
  post_link:
    - echo "Links created successfully!"
  pre_shell:
    - echo "About to run shell commands..."
  post_shell:
    - echo "Shell commands completed!"

Using Templates

Templates use Go's text/template syntax with these variables:

- link:
    ~/.config/git/config-{{ .Hostname }}: ./git/config
  
  shell:
    - ["echo 'Running on {{ .OS }}/{{ .Arch }}'", "Show system info"]

Available template variables:

Variable	Description	Example
{{ .Hostname }}	Machine hostname	macbook-pro
{{ .Username }}	Current user	john
{{ .HomeDir }}	Home directory path	/Users/john
{{ .OS }}	Operating system	darwin, linux, windows
{{ .Arch }}	Architecture	amd64, arm64
{{ .Date }}	Current date	2024-01-15

Multiple Profiles

You can have multiple profile configurations in the same file:

# Personal machine config
- profile: personal
  link:
    ~/.gitconfig: ~/.mydotfiles/git/gitconfig-personal
    ~/.zshrc: ~/.mydotfiles/zsh/zshrc

# Work machine config
- profile: work
  link:
    ~/.gitconfig: ~/.mydotfiles/git/gitconfig-work
    ~/.zshrc: ~/.mydotfiles/zsh/zshrc-work

# Common config (no profile = always applied)
- create:
    - ~/.config
    - ~/.local/bin

Run specific profile:

hidedot --profile work