dot

A TypeScript CLI tool to install and backup your dotfiles from a Git repository.

Commands

| Command | Description | |---|---| | dot setup | Create an example dot.yaml in your dotfiles directory | | dot install <repo-url> | Clone a dotfiles repo and install its contents onto the system | | dot install --local <path> | Install from an existing local repository (no clone/pull) | | dot backup | Copy system dotfiles back into the local repo and commit |

Getting Started

1. Install the CLI

npm install -g dot

2. Initialise your dotfiles directory

dot setup
# or specify a custom path
dot setup --dir ~/projects/dotfiles

This creates ~/.dotfiles/dot.yaml with an example configuration and commented-out templates.
The generated file already includes an entry for dot.yaml itself so your configuration is always backed up alongside your other dotfiles.

3. Edit dot.yaml

Open ~/.dotfiles/dot.yaml and declare your dotfiles and packages:

dotfiles:
  # dot.yaml itself is tracked so it is always backed up
  - source: dot.yaml
    target: ~/.dotfiles/dot.yaml

  - source: .zshrc
    target: ~/.zshrc

  - source: .gitconfig
    target: ~/.gitconfig

  - source: .config/nvim
    target: ~/.config/nvim

packages:
  brew:
    - neovim
    - zsh
    - starship
  npm:
    - typescript

4. Push to a Git remote

cd ~/.dotfiles
git init && git remote add origin https://github.com/you/dotfiles.git
git add . && git commit -m "init"
git push -u origin main

5. Install on a new machine

dot install https://github.com/you/dotfiles.git

Command Reference

dot setup [options]

Creates an example dot.yaml in the dotfiles directory.

| Option | Default | Description | |---|---|---| | -d, --dir <path> | ~/.dotfiles | Directory where dot.yaml will be created | | -f, --force | false | Overwrite an existing dot.yaml |

dot setup
dot setup --dir ~/dotfiles
dot setup --force   # overwrite existing config

dot install [repo-url] [options]

Clones (or pulls) a dotfiles repository, installs declared packages, then symlinks (or copies) each dotfile to its target on the system.

Provide either a <repo-url> argument or the --local <path> option — at least one is required.

| Option | Default | Description | |---|---|---| | -d, --dir <path> | ~/.dotfiles | Local directory to clone the repo into | | -l, --local <path> | — | Use an existing local repository at this path (skips clone/pull) | | -c, --copy | false | Copy files instead of creating symlinks | | --skip-packages | false | Skip package manager installation |

# Remote repository
dot install https://github.com/you/dotfiles.git
dot install https://github.com/you/dotfiles.git --copy
dot install https://github.com/you/dotfiles.git --skip-packages
dot install https://github.com/you/dotfiles.git --dir ~/my-dots

# Existing local repository (no network required)
dot install --local ~/projects/dotfiles
dot install --local ~/projects/dotfiles --copy
dot install --local ~/projects/dotfiles --skip-packages

Conflict behaviour: if a file or symlink already exists at a target path it is removed and replaced. Directories are recreated automatically.

dot backup [options]

Copies each system dotfile back into the local repository at its declared source path, then commits and pushes the changes.

| Option | Default | Description | |---|---|---| | -d, --dir <path> | ~/.dotfiles | Path to the local dotfiles repository | | -m, --message <msg> | backup: YYYY-MM-DD | Git commit message | | --no-push | false | Commit locally without pushing |

dot backup
dot backup --message "add nvim config"
dot backup --no-push
dot backup --dir ~/my-dots

dot.yaml Reference

dotfiles:
  - source: <path-in-repo>   # relative to repo root
    target: <system-path>    # ~ is expanded to $HOME

packages:
  brew:   [neovim, zsh]      # macOS — Homebrew
  npm:    [typescript]       # npm global install
  pip:    [black]            # pip install
  apt:    [neovim, zsh]      # Debian/Ubuntu — apt-get

Development

npm install        # install dependencies
npm run build      # compile TypeScript → dist/
npm run dev        # run via ts-node (no build required)
npm test           # run Jest test suite
npm run clean      # remove dist/

Project Structure

src/
├── index.ts               # CLI entry point (Commander)
├── types/
│   └── index.ts           # Shared TypeScript interfaces
├── commands/
│   ├── setup.ts           # setup command
│   ├── install.ts         # install command
│   └── backup.ts          # backup command
└── utils/
    ├── config.ts          # Read/write dot.yaml (js-yaml)
    ├── files.ts           # Symlink/copy helpers, home expansion
    ├── git.ts             # Clone, pull, commit, push (simple-git)
    ├── packages.ts        # brew / npm / pip / apt installers (zx)
    └── logger.ts          # Terminal output (chalk + ora)