Carlos A. Gomes dotfiles

Dotfiles are used to customize and automate you daily work on the terminal using scripts and aliases.

The "dotfiles" name is derived from the configuration files in Unix-like systems that start with a dot.

e.g.:

• .bash_aliases
• .gitconfig

Installation

Using Git and the bootstrap script

Clone the repository:

git clone https://github.com/carlos-algms/dotfiles.git
cd dotfiles

The bootstrapper script will create symbolic links in the home folder replacing existing files, so remember to backup.

Files to backup:

• ~/.bashrc
• ~/.bash_profile
• ~/.zshrc

Mac & Linux installation

./bootstrap.sh

Windows installation

bootstrap.bat

Installation System

Main Bootstrap

• Entry point: ./bootstrap.sh - Orchestrates all installation scripts
• Architecture: Iterates through subdirectories running individual install.sh scripts
• Script conventions: logging and OS detection, see AGENTS.md "File Operations Protocol"

Module Structure

Each major component has its own install.sh:

• shell/install.sh - Shell configuration (detects OS and delegates to platform-specific installers)
• neovim/install.sh - Neovim setup (installs via brew/apt, creates symlink from neovim/nvim to ~/.config/nvim)
• kitty/install.sh - Kitty terminal (macOS only, symlinks config files)

Installation Pattern

• Scripts create symlinks to this repository rather than copying files
• Existing files are backed up with timestamp suffix before linking
• Platform-specific installers in shell/[linux|macos|windows]/install-*.sh
• shell/zsh/install-zsh.sh installs oh-my-zsh only when ~/.oh-my-zsh is missing. The oh-my-zsh installer replaces an existing ~/.zshrc with its own template and saves the old file as ~/.zshrc.pre-oh-my-zsh, so a fresh machine gets a working file. Symlink your own ~/.zshrc afterwards if you want
• shell/zsh/installers/pnpm-shell-completion.sh installs the pnpm-shell-completion oh-my-zsh plugin. It is a native binary, so it is faster than pnpm completion zsh, which starts Node on shell start (~0.55s) and on every Tab (~0.3s). Rerun the script to update it: it compares the installed release tag with the latest GitHub release and reinstalls when they differ

Key Commands

# Install/update all configurations
./bootstrap.sh

# OR Install individual components
./shell/install.sh
./neovim/install.sh
./kitty/install.sh

# bootstrap.sh runs every component and lists the failed installers at the end.
# Installers are idempotent: rerun the failed ones.

# Linux only: install or update fzf, ripgrep, yazi, fnm, zoxide (+ Node LTS).
# Reinstalls a tool only when a newer release exists; rerun it to update them.
# Set GITHUB_TOKEN to avoid GitHub API rate limits.
./shell/linux/install-or-update-shell-tools.sh

# Sync neovim config via SSH
# Like a shared host like HostGator, GoDaddy, etc..
./neovim/sync-via-ssh.sh

# Herdr (not wired into bootstrap)
ln -s $(pwd)/herdr/config.toml ~/.config/herdr/config.toml

---

Author

Carlos A. Gomes