Dotfiles Manager

A personal dotfiles manager that supports two installation modes and follows a modular, directory-per-tool architecture.

Project Structure

This dotfiles repository supports:

Architecture Pattern

Each tool follows a **directory-per-tool** structure under the repository root:

```

<tool>/

├── install.sh # Optional: Custom installation (skips OS package manager)

├── configure.sh # Optional: Symlinks configs and sets up plugins

└── <config-files> # Tool-specific configuration files

```

**Orchestration flow:**

1. Root `install.sh` is invoked

2. Calls `bin/dotfiles <tool>` for each tool

3. Runs `<tool>/install.sh` (if exists)

4. Runs `<tool>/configure.sh` (if exists)

Instructions

When Adding a New Tool

1. **Create the tool directory structure**:

- Create `<tool>/` directory

- Add `install.sh` for custom installation logic (if needed)

- Add `configure.sh` for symlinking configs and plugin setup (if needed)

- Add tool-specific configuration files

2. **Update the orchestration**:

- Add `./bin/dotfiles <tool>` call in root `install.sh`

- Place call conditionally under `full` mode check if tool is full-mode only

- Handle package name → command name mapping in `bin/dotfiles` if they differ (e.g., `neovim`→`nvim`, `ripgrep`→`rg`)

3. **Follow script conventions**:

- Use `#!/usr/bin/env bash` shebang

- Include `set -e` for fail-fast behavior

- Reference `$DOTFILES_LOCATION` for paths back to repo root

- Check `$INSTALL_MODE` to conditionally handle `'full'` vs minimal

- Use `$elevate` variable for sudo operations (empty when running as root)

- Symlink configs using `ln -sf` to appropriate home directories (`~/.config/`, `~/`, etc.)

Zsh/Oh-My-Zsh Customizations

Custom zsh files live in `omz/` and are symlinked to `$ZSH_CUSTOM`:

When modifying zsh behavior, add files to `omz/` following this structure.

Neovim Configuration

The neovim setup uses lazy.nvim plugin manager with configuration in `neovim/lazy-nvim/`:

When adding neovim plugins or LSP configs, follow this structure.

Git Hooks

Pre-commit framework hooks are templated in `git/git-template/hooks/` and symlinked to `~/.git-template/hooks`. Add new hooks following this pattern.

Testing Changes

```bash

Run full installation

./install.sh full

Test individual tool

./bin/dotfiles <tool-name>

```

Changelog & Versioning

Important Conventions

Examples

Adding a New Tool (Example: `bat`)

1. Create `bat/configure.sh`:

```bash

#!/usr/bin/env bash

set -e

Symlink bat config

mkdir -p ~/.config/bat

ln -sf "$DOTFILES_LOCATION/bat/config" ~/.config/bat/config

```

2. Add to root `install.sh`:

```bash

if [[ "$INSTALL_MODE" == 'full' ]]; then

./bin/dotfiles bat

fi

```

Adding a Zsh Function

1. Create `omz/functions/my_function`:

```bash

Function description

my_function() {

echo "Hello from custom function"

}

```

2. Reference in `omz/functions.zsh`:

```bash

autoload -Uz my_function

```