dotfiler

dotfiler

A tool for managing dotfiles through symlinks.

Installation

Install the tool globally:

go install github.com/jakewan/dotfiler@latest

Quick Start

1. Create a private Git repository for your dotfiles
2. Organize your files however you prefer
3. Create a dotfiler.yml manifest file that references your files
4. Run dotfiler files update -m dotfiler.yml to apply the configuration

Repository Structure

You can organize your dotfiles repository however makes sense to you. Here's one example structure:

my-dotfiles/
├─ shell/
│  ├─ .bashrc
│  ├─ .zshrc-intel
│  ├─ .zshrc-apple
├─ git/
│  ├─ .gitconfig
│  ├─ .gitignore_global
├─ editors/
│  ├─ nvim/
│  │  ├─ init.vim
│  ├─ vscode/
│  │  ├─ settings.json
├─ dotfiler.yml

Other common approaches:

• Flat structure: all dotfiles in the root directory
• By application: separate folders for each tool
• By OS: platform-specific subdirectories
• Mixed: whatever organization works for your workflow

Manifest Configuration

The dotfiler.yml file references your existing files and defines where to symlink them:

---
# Basic relative path symlink
- op: symlink
  srcFilePath: shell/.bashrc
  dstFilePath: .bashrc
  targetOS:
    - linux
    - darwin
  targetArch:
    - amd64
    - arm64

# Cross-platform configuration
- op: symlink
  srcFilePath: git/.gitconfig
  dstFilePath: .gitconfig
  targetOS:
    - linux
    - darwin
    - windows
  targetArch:
    - amd64
    - arm64

# Nested destination path
- op: symlink
  srcFilePath: editors/nvim/init.vim
  dstFilePath: .config/nvim/init.vim
  targetOS:
    - linux
    - darwin
  targetArch:
    - amd64
    - arm64

# Platform-specific configuration
- op: symlink
  srcFilePath: editors/vscode/settings.json
  dstFilePath: .config/Code/User/settings.json
  targetOS:
    - linux
  targetArch:
    - amd64
    - arm64

# macOS-specific path
- op: symlink
  srcFilePath: editors/vscode/settings.json
  dstFilePath: Library/Application Support/Code/User/settings.json
  targetOS:
    - darwin
  targetArch:
    - amd64
    - arm64

# Architecture-specific configuration
- op: symlink
  srcFilePath: shell/.zshrc-intel
  dstFilePath: .zshrc
  targetOS:
    - darwin
  targetArch:
    - amd64

- op: symlink
  srcFilePath: shell/.zshrc-apple
  dstFilePath: .zshrc
  targetOS:
    - darwin
  targetArch:
    - arm64

# Absolute source path (system files)
- op: symlink
  srcFilePath: /usr/share/applications/example.desktop
  dstFilePath: .config/autostart/example.desktop
  targetOS:
    - linux
  targetArch:
    - amd64
    - arm64

Configuration Options

• op: Operation type (currently only symlink is supported)
• srcFilePath: Source file path (relative to manifest, or absolute—on Unix-like systems, absolute paths start with /; on Windows, they start with a drive letter like C:\. The tool uses Go's filepath.IsAbs() to detect absolute paths on all platforms.)
• dstFilePath: Destination path (relative to home directory, or custom with -d flag)
• targetOS: Target operating systems (see Go runtime constants)
• targetArch: Target architectures (see Go runtime constants)

Feature Examples

Each example above demonstrates a key feature:

1. Basic symlink: Simple relative path within your dotfiles repo
2. Cross-platform: Same configuration works across multiple operating systems
3. Nested paths: Create symlinks in subdirectories like .config/
4. Platform-specific: Different configurations for different operating systems
5. Architecture-specific: Different files for Intel vs Apple Silicon Macs
6. System file symlinks: Link to existing system files using absolute paths

Platform Support

Use values from Go's GOOS and GOARCH runtime constants.

View available combinations:

go tool dist list | egrep 'darwin|linux|windows'

Common examples:

• darwin/amd64 (Intel Mac)
• darwin/arm64 (Apple Silicon Mac)
• linux/amd64 (64-bit Linux)
• windows/amd64 (64-bit Windows)

Usage

Apply your dotfile configuration:

dotfiler files update -m path/to/dotfiler.yml

Options

• -m, --manifest: Path to manifest file (default: ./dotfiler.yml)
• -d, --destination: Destination root directory (default: user home directory)

Safety Features

• User confirmation: Always prompts before making changes
• Validation: Checks all operations before executing any
• Warnings: Alerts about external dependencies (absolute paths)
• Directory creation: Automatically creates missing parent directories