1. Getting Started

1. Organize Your Dotfiles

If you don't have a dotfiles repository yet

• Figure out all the applications that use dotfiles that you want to keep track of, and write down where all those files are located.
• Create a new git repo (I suggest placing it in ~/.dotfiles)
• Move those dotfiles to the repo. You can also change the file names to make sense to you - for example a file that was at ~/.i3/config can be renamed to simply i3.
• Commit and push, you now have a dotfiles repo!

Setting up in the repo

• Add .dotter/local.toml to your .gitignore - that file contains the machine-specific configuration, so there's no point uploading it.
• Add .dotter/cache.toml and .dotter/cache to your .gitignore as well
• When installing, I recommend downloading the binaries (windows and linux) into the root of your repository.
  That way, wherever your dotfiles are, Dotter also is.
• On Linux, make sure dotter has execute permissions with chmod +x dotter, then you can run it with ./dotter

2. Initialize Dotter

Begin by navigating to the directory where you want to manage your dotfiles, and initialize Dotter:

dotter init

This will create a .dotter directory containing the following files:

• global.toml: Shared configuration for all systems. The file will look something like this

[helpers]

[default]
depends = []

[default.files]
"README.md" = ""
dotter = ""
zshrc = ""
vimrc = ""

Go ahead and remove files that are not configurations like README or dotter, as well as empty sections. Fill out the target locations for the configuration files, like so:

[default.files]
zshrc = "~/.zshrc"
vimrc = "~/.vimrc"

This defines a package named default with the corresponding files, and tells Dotter where they should go once deployed.

• local.toml: Machine-specific settings. Leave it as is for now.

3. Deploy

Simulate what will happen when Dotter deploys your files using

dotter deploy --dry-run

Deploy the files to their respective locations using

dotter deploy -v

The -v or --verbose flag provides a log of the changes that dotter has performed.

Note that on your first run, you might also need to pass a -f or --force flag to allow dotter to delete and overwrite whatever files are already at the target location, and replace it with a symbolic link pointing at the file in the repository.

Congratulations! Your dotfiles are now managed by Dotter. You can keep adding files to your dotfiles repository, and manage them by simply adding them to global.toml. However, there's many more features to explore.