Project Status ⚠️

This project is in maintainance mode. If there are any bugs I will do my best to fix them but no new features will be added.

Im currently working on a successor to Dotted called Rotz which is written in rust. Rotz is compatible with Dotteds dotfile repos but aims to have better error handling and better ux as well as more features.

See the roadmap to get the status of Rotzs development.

Introduction

Dotted has three main functionalities.

Linking dotfiles from a common repository to your system
Installing the applications you need to start working on an new/empty machine
Full Cross platform functionality

Story

My main OS is Windows and I was getting tired of manually installing and setting up my dev tools over and over again on a clean windows install.

I started using scoop as a package manager stand-in for the installing part and started looking into dotfile managers. There are some solutions but none of them fulfilled my need for easy and full cross platform support which is why I created my own dotfile manager. (related xkcd)

Installation

Install the PowerShell module:

Install-Module Dotted

Requirements

PowerShell >= 5.x (PowerShell Core is supported)
powershell-yaml

Run

Run Get-Command -Module Dotted to see all commands Dotted has.

You can then use Get-Help -Full <command> to view the fill command help.

Note: You may need to run Import-Module Dotted (consider adding this to your Profile.ps1). Note: You may install the powershell-yaml module Install-Module powershell-yaml.

Getting Started

If you already have a dotfiles repo you can clone it with the Clone-Dots command.

To bootstrap your dev environment use Install-Dots.

To link your dotfiles use Link-Dots.

Configuration

Dotted uses a git repo containing thedotfiles and yaml files for configuration.

This git repo should be located at ~/.dotfiles. Different paths can be specified using the -DotfilesPath cli flag or in the Dotted config file ~/.config/dotted/config.yaml like this:

path: ~./dotfiles

Each managed application has a subfolder containing its dotfiles and a dot.yaml file.

Example:

└── vscode
    ├── dot.yaml
    ├── keybindings.json
    └── settings.json

The file dot.yaml contains information about how to install and update the application and where to link the dotfiles.

`dot.yaml`

The dot.yaml file consists of four optional keys:

key	requirement	function
`links`	`optional`	Defines where to link which `dotfile`
`installs`	`optional`	Defines the install command and install dependencies.
`updates`	`optional`	Defines the update command and update dependencies.
`depends`	`optional`	Defines dependencies this application needs to work.

`links`

The links section specifies where the dotfiles should be linked. Command Link-Dots

It consists of multiple key: value pairs where the key is the filename of the dotfile and the value is the link path.

Example:

vscode/dot.yaml

...
links:
  keybindings.json: ~\AppData\Roaming\Code\User\keybindings.json
  settings.json: ~\AppData\Roaming\Code\User\settings.json

`installs`

The installs section contains the install command and optional install dependencies. Command Install-Dots

It can either be a string containing the install command or have two sub keys.

key	requirement	function
`cmd`	`required`	Contains the install command.
`depends`	`optional`	Contains an array of dependencies.

Examples:

nodejs/dot.yaml

...
installs:
  cmd: scoop install nodejs
  depends: [scoop]

scoop/dot.yaml

...
installs: iex (new-object net.webclient).downloadstring('https://get.scoop.sh')

`updates`

The updates section contains the update command and optional update dependencies. Command Update-Dots

It works exactly like the installs key described above.

Example:

nodejs/dot.yaml

...
updates:
  cmd: scoop update nodejs
  depends: [scoop]

depends

The depends section contains an array of dependencies needed for the application to work correctly.

These dependencies will also be installed/updated when the application is installed/updated.

Example:

zsh/dot.yaml
...
depends: [starship]

Defaults

The repo can also contain a default file dots.yaml in the root folder of the repo.

This file contains defaults which are automatically used for empty keys in the dot.yaml files.

You can use template strings (``) to substitute the name of the application (the name of the folder the dot.yaml file is located in).

Example:

dots.yaml

installs:
  cmd: scoop install 
  depends:
    - scoop
    - extras
updates:
  cmd: scoop update 
  depends:
    - scoop

OS Specifics

You can specify different behaviors per OS in all configuration files.

Dotted can differentiate between Windows, Linux and MacOS.

To specify OS Specific behavior you need to add top level keys named linux, windows, darwin (for MacOS) and general (applied to all OSs).

Examples:

dots.yaml

windows:
  installs:
    cmd: scoop install 
    depends:
      - scoop
      - extras
  updates:
    cmd: scoop update 
    depends:
      - scoop
darwin:
  installs:
    cmd: brew install 
    depends:
      - brew
  updates:
    cmd: brew upgrade 
    depends:
      - brew

neovim/dot.yaml

windows:
  links:
    ginit.vim: ~\AppData\Local\nvim\ginit.vim
    init.vim: ~\AppData\Local\nvim\init.vim
    
global:
  links:
    ginit.vim: ~/.config/nvim/init.vim
    init.vim: ~/.config/nvim/ginit.vim

You can also combine multiple OSs per key separating them with a |.

Example:

dots.yaml

windows:
  installs:
    cmd: scoop install 
    depends:
      - scoop
      - extras
darwin|linux:
  installs:
    cmd: brew install 
    depends:
      - brew

Example Repository

You can see all of this functionality used in my own dotfiles repository.

Contribute

Feel free to create pull requests and issues for bugs, features or questions.