command module
Version: v0.2.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2016 License: MIT Imports: 12 Imported by: 0


dotbro - simple yet effective dotfiles manager.

Build Status Go Report Card

Dotbro is a tool which helps you install and keep your dotfiles up to date.

If you don't have your dotfiles repository yet, it's time to create it.


Dotfiles are generally stored is VCS and symlinked from repo directory to your $HOME - this is one of the best patterns because you can track changes easily and commit them to your dotfiles repo. However, this pattern does not offer you any way to install your dotfiles, so often people end up writing their own script e.g. in bash, which is not good for long-term purposes (I know that because I had one).

This tool was made to deal with dotfiles installation, so you don't waste your time writing your install scripts and focus only on your dotfiles themselves.

Dotbro takes on the routine. The main task - installing your dotfiles in one command on any of your machines.


Simple configuration file

All you need is simple configuration file in JSON or TOML format.

Clear mapping

You may want to (or you do already) store your dotfiles in a neat way using named directories like bash/bashrc. Obviously, you want to symlink it to proper place $HOME/.bashrc. This is easily done by writing such string in [mapping] section:

"bash/bashrc" = ".bashrc"
Specify the configuration file only once

First time you run dotbro, specify the config file. Dotbro remembers path to this file and use it in further runs.

Dotbro cleans broken symlinks in your $HOME (or your another destination path).

Add command

Dotbro can automate routine of adding files to your dotfiles repo with one single command. It does a backup copy, moves the file and creates a symlink to your file. After that you only need to add this file to your dotbro config (I'm working on automation of this) and commit that file to your repo.


Configuration can be either TOML or JSON file. TOML is peferred, because it's a bit clearer and allows comments. However, JSON is good option for configs without mapping, it's short and simple.

Example of a simple configuration file in TOML format:

# Dotbro configuration file.
# Some points:
# - Almost all options have default value.
# - You can use $ENV_VARIABLE in paths.


# Directory of your dotfiles repository.
# Default: directory of this config.
dotfiles = "$HOME/dotfiles"

# Destination directory - your dotfiles will be linked there.
# Default: $HOME
destination = "$HOME"

# Backup directory - your original files will be backuped there.
# Default: $HOME/.dotfiles~
backup = "$HOME/.dotfiles~"


# Binaries
"bin" = "bin"

"zsh/zprofile" = ".zprofile"
"zsh/zshrc" = ".zshrc"
"zsh/zshrc.d" = ".zshrc.d"
"zsh/zlogin" = ".zlogin"

# Vim
"vim/vimrc" = ".vimrc"

"git/commit_template" = ".gitcommit"
"git/config" = ".gitconfig"
"git/excludes" = ".gitexcludes"

"i3" = ".i3"
".keynavrc" = ".keynavrc"
".screenrc" = ".screenrc"

See more examples in config_examples directory of this repo.


Config has 3 sections:

  • directories
  • mapping
  • files
Option Description Example Default
dotfiles Directory of your dotfiles repository. $HOME/dotfiles Directory of your config file.
sources Directory relative to dotfiles where dotfiles are stored. You want to set this option if you keep your dotfiles in a subdirectory of your repo. By default this is empty, assuming your dotfiles are on the first level of dotfiles directory. src none
destination Your dotfiles will be linked there. $HOME $HOME
backup Your original files will be backuped there. $HOME/backups/dotfiles $HOME/.dotfiles~

Each option here represents source file and destination file.
Example: your dotfiles directory is $HOME/dotfiles. In that directory, you have folder vim and file vimrc in that folder, so path is $HOME/dotfiles/vim/vimrc. In directories section you have already specified dotfiles = "$HOME/dotfiles". So to install your vimrc properly you need to specify such line in mapping section:

"vim/vimrc" = ".vimrc"

Also, mapping is optional. If you do not specify any mapping, dotbro will symlink all files from your dotfiles directory to your destination directory respectively. If you do want this approach, but want some files to be excluded, see Files section.


As said above, this section is for symlinking all dotfiles without mapping specification.

Option Description Example Default
excludes Files to exclude from being installed excludes = ["", "dotbro.toml"] none

Summing up, your config without mapping will look like this:

# Dotbro configuration file.


dotfiles = "$HOME/dotfiles"


excludes = [

Install dotbro

Using Go tools:
go get

This downloads the source code, builds and installs the latest version of dotbro. Then you can use dotbro command right away.

Precompiled binary

Coming soon ...


Take a look at usage info running:

dotbro --help

If you haven't prepared your config file yet, it's time to do it. When your config is ready, run:

dotbro -c <config-path>

This installs your dotfiles.

Further runs you can omit config path parameter - dotbro have remembered it for you. So just run:


To move a file to your dotfiles, perform an add command:

dotbro add ./path-to-file


If you experience any problems, please submit an issue and attach dotbro log file, which can be found at $HOME/.dotbro/dotbro.log.




The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL