• Stars
    star
    7,030
  • Rank 5,559 (Top 0.2 %)
  • Language
    Python
  • License
    MIT License
  • Created over 10 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A tool that bootstraps your dotfiles ⚡️

Dotbot Build Status

Dotbot makes installing your dotfiles as easy as git clone $url && cd dotfiles && ./install, even on a freshly installed system!


Rationale

Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files [bo]o[t]strapper, get it?). It does less than you think, because version control systems do more than you think.

Dotbot is designed to be lightweight and self-contained, with no external dependencies and no installation required. Dotbot can also be a drop-in replacement for any other tool you were using to manage your dotfiles, and Dotbot is VCS-agnostic -- it doesn't make any attempt to manage your dotfiles.

See this blog post or more resources on the tutorials page for more detailed explanations of how to organize your dotfiles.

Getting Started

Starting Fresh?

Great! You can automate the creation of your dotfiles by using the user-contributed init-dotfiles script. If you'd rather use a template repository, check out dotfiles_template. Or, if you're just looking for some inspiration, we've got you covered.

Integrate with Existing Dotfiles

The following will help you get set up using Dotbot in just a few steps.

If you're using Git, you can add Dotbot as a submodule:

cd ~/.dotfiles # replace with the path to your dotfiles
git init # initialize repository if needed
git submodule add https://github.com/anishathalye/dotbot
git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
cp dotbot/tools/git-submodule/install .
touch install.conf.yaml

If you're using Mercurial, you can add Dotbot as a subrepo:

cd ~/.dotfiles # replace with the path to your dotfiles
hg init # initialize repository if needed
echo "dotbot = [git]https://github.com/anishathalye/dotbot" > .hgsub
hg add .hgsub
git clone https://github.com/anishathalye/dotbot
cp dotbot/tools/hg-subrepo/install .
touch install.conf.yaml

If you are using PowerShell instead of a POSIX shell, you can use the provided install.ps1 script instead of install. On Windows, Dotbot only supports Python 3.8+, and it requires that your account is allowed to create symbolic links.

To get started, you just need to fill in the install.conf.yaml and Dotbot will take care of the rest. To help you get started we have an example config file as well as configuration documentation for the accepted parameters.

Note: The install script is merely a shim that checks out the appropriate version of Dotbot and calls the full Dotbot installer. By default, the script assumes that the configuration is located in install.conf.yaml the Dotbot submodule is located in dotbot. You can change either of these parameters by editing the variables in the install script appropriately.

Setting up Dotbot as a submodule or subrepo locks it on the current version. You can upgrade Dotbot at any point. If using a submodule, run git submodule update --remote dotbot, substituting dotbot with the path to the Dotbot submodule; be sure to commit your changes before running ./install, otherwise the old version of Dotbot will be checked out by the install script. If using a subrepo, run git fetch && git checkout origin/master in the Dotbot directory.

If you prefer, you can install Dotbot from PyPI and call it as a command-line program:

pip install dotbot
touch install.conf.yaml

In this case, rather than running ./install, you can invoke Dotbot with dotbot -c <path to configuration file>.

Full Example

Here's an example of a complete configuration.

The conventional name for the configuration file is install.conf.yaml.

- defaults:
    link:
      relink: true

- clean: ['~']

- link:
    ~/.tmux.conf: tmux.conf
    ~/.vim: vim
    ~/.vimrc: vimrc

- create:
    - ~/downloads
    - ~/.vim/undo-history

- shell:
  - [git submodule update --init --recursive, Installing submodules]

The configuration file is typically written in YAML, but it can also be written in JSON (which is a subset of YAML). JSON configuration files are conventionally named install.conf.json.

Configuration

Dotbot uses YAML or JSON-formatted configuration files to let you specify how to set up your dotfiles. Currently, Dotbot knows how to link files and folders, create folders, execute shell commands, and clean directories of broken symbolic links. Dotbot also supports user plugins for custom commands.

Ideally, bootstrap configurations should be idempotent. That is, the installer should be able to be run multiple times without causing any problems. This makes a lot of things easier to do (in particular, syncing updates between machines becomes really easy).

Dotbot configuration files are arrays of tasks, where each task is a dictionary that contains a command name mapping to data for that command. Tasks are run in the order in which they are specified. Commands within a task do not have a defined ordering.

When writing nested constructs, keep in mind that YAML is whitespace-sensitive. Following the formatting used in the examples is a good idea. If a YAML configuration file is not behaving as you expect, try inspecting the equivalent JSON and check that it is correct.

Directives

Most Dotbot commands support both a simplified and extended syntax, and they can also be configured via setting defaults.

Link

Link commands specify how files and directories should be symbolically linked. If desired, items can be specified to be forcibly linked, overwriting existing files if necessary. Environment variables in paths are automatically expanded.

Format

Link commands are specified as a dictionary mapping targets to source locations. Source locations are specified relative to the base directory (that is specified when running the installer). If linking directories, do not include a trailing slash.

Link commands support an optional extended configuration. In this type of configuration, instead of specifying source locations directly, targets are mapped to extended configuration dictionaries.

Parameter Explanation
path The source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below))
create When true, create parent directories to the link as needed. (default: false)
relink Removes the old target if it's a symlink (default: false)
force Force removes the old target, file or folder, and forces a new link (default: false)
relative Use a relative path to the source when creating the symlink (default: false, absolute links)
canonicalize Resolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths)
if Execute this in your $SHELL and only link if it is successful.
ignore-missing Do not fail if the source is missing and create the link anyway (default: false)
glob Treat path as a glob pattern, expanding patterns referenced below, linking all files matched. (default: false)
exclude Array of glob patterns to remove from glob matches. Uses same syntax as path. Ignored if glob is false. (default: empty, keep all matches)
prefix Prepend prefix prefix to basename of each file when linked, when glob is true. (default: '')

When glob: True, Dotbot uses glob.glob to resolve glob paths, expanding Unix shell-style wildcards, which are not the same as regular expressions; Only the following are expanded:

Pattern Meaning
* matches anything
** matches any file, recursively (Python >= 3.5 only)
? matches any single character
[seq] matches any character in seq
[!seq] matches any character not in seq

However, due to the design of glob.glob, using a glob pattern such as config/*, will not match items that begin with .. To specifically capture items that being with ., you will need to include the . in the pattern, like this: config/.*.

When using glob with the exclude: option, the paths in the exclude paths should be relative to the base directory, same as the glob pattern itself. For example, if a glob pattern vim/* matches directories vim/autoload, vim/ftdetect, vim/ftplugin, and vim/spell, and you want to ignore the spell directory, then you should use exclude: ["vim/spell"] (not just "spell").

Example

- link:
    ~/.config/terminator:
      create: true
      path: config/terminator
    ~/.vim: vim
    ~/.vimrc:
      relink: true
      path: vimrc
    ~/.zshrc:
      force: true
      path: zshrc
    ~/.hammerspoon:
      if: '[ `uname` = Darwin ]'
      path: hammerspoon
    ~/.config/:
      path: dotconf/config/**
    ~/:
      glob: true
      path: dotconf/*
      prefix: '.'

If the source location is omitted or set to null, Dotbot will use the basename of the destination, with a leading . stripped if present. This makes the following two config files equivalent.

Explicit sources:

- link:
    ~/bin/ack: ack
    ~/.vim: vim
    ~/.vimrc:
      relink: true
      path: vimrc
    ~/.zshrc:
      force: true
      path: zshrc
    ~/.config/:
      glob: true
      path: config/*
      relink: true
      exclude: [ config/Code ]
    ~/.config/Code/User/:
      create: true
      glob: true
      path: config/Code/User/*
      relink: true

Implicit sources:

- link:
    ~/bin/ack:
    ~/.vim:
    ~/.vimrc:
      relink: true
    ~/.zshrc:
      force: true
    ~/.config/:
      glob: true
      path: config/*
      relink: true
      exclude: [ config/Code ]
    ~/.config/Code/User/:
      create: true
      glob: true
      path: config/Code/User/*
      relink: true

Create

Create commands specify empty directories to be created. This can be useful for scaffolding out folders or parent folder structure required for various apps, plugins, shell commands, etc.

Format

Create commands are specified as an array of directories to be created. If you want to use the optional extended configuration, create commands are specified as dictionaries. For convenience, it's permissible to leave the options blank (null) in the dictionary syntax.

Parameter Explanation
mode The file mode to use for creating the leaf directory (default: 0777)

The mode parameter is treated in the same way as in Python's os.mkdir. Its behavior is platform-dependent. On Unix systems, the current umask value is first masked out.

Example

- create:
    - ~/downloads
    - ~/.vim/undo-history
- create:
    ~/.ssh:
      mode: 0700
    ~/projects:

Shell

Shell commands specify shell commands to be run. Shell commands are run in the base directory (that is specified when running the installer).

Format

Shell commands can be specified in several different ways. The simplest way is just to specify a command as a string containing the command to be run.

Another way is to specify a two element array where the first element is the shell command and the second is an optional human-readable description.

Shell commands support an extended syntax as well, which provides more fine-grained control.

Parameter Explanation
command The command to be run
description A human-readable message describing the command (default: null)
quiet Show only the description but not the command in log output (default: false)
stdin Allow a command to read from standard input (default: false)
stdout Show a command's output from stdout (default: false)
stderr Show a command's error output from stderr (default: false)

Note that quiet controls whether the command (a string) is printed in log output, it does not control whether the output from running the command is printed (that is controlled by stdout / stderr). When a command's stdin / stdout / stderr is not enabled (which is the default), it's connected to /dev/null, disabling input and hiding output.

Example

- shell:
  - chsh -s $(which zsh)
  - [chsh -s $(which zsh), Making zsh the default shell]
  -
    command: read var && echo Your variable is $var
    stdin: true
    stdout: true
    description: Reading and printing variable
    quiet: true
  -
    command: read fail
    stderr: true

Clean

Clean commands specify directories that should be checked for dead symbolic links. These dead links are removed automatically. Only dead links that point to somewhere within the dotfiles directory are removed unless the force option is set to true.

Format

Clean commands are specified as an array of directories to be cleaned.

Clean commands also support an extended configuration syntax.

Parameter Explanation
force Remove dead links even if they don't point to a file inside the dotfiles directory (default: false)
recursive Traverse the directory recursively looking for dead links (default: false)

Note: using the recursive option for ~ is not recommended because it will be slow.

Example

- clean: ['~']

- clean:
    ~/:
      force: true
    ~/.config:
      recursive: true

Defaults

Default options for plugins can be specified so that options don't have to be repeated many times. This can be very useful to use with the link command, for example.

Defaults apply to all commands that come after setting the defaults. Defaults can be set multiple times; each change replaces the defaults with a new set of options.

Format

Defaults are specified as a dictionary mapping action names to settings, which are dictionaries from option names to values.

Example

- defaults:
    link:
      create: true
      relink: true

Plugins

Dotbot also supports custom directives implemented by plugins. Plugins are implemented as subclasses of dotbot.Plugin, so they must implement can_handle() and handle(). The can_handle() method should return True if the plugin can handle an action with the given name. The handle() method should do something and return whether or not it completed successfully.

All built-in Dotbot directives are written as plugins that are loaded by default, so those can be used as a reference when writing custom plugins.

Plugins are loaded using the --plugin and --plugin-dir options, using either absolute paths or paths relative to the base directory. It is recommended that these options are added directly to the install script.

See here for a current list of plugins.

Command-line Arguments

Dotbot takes a number of command-line arguments; you can run Dotbot with --help, e.g. by running ./install --help, to see the full list of options. Here, we highlight a couple that are particularly interesting.

--only

You can call ./install --only [list of directives], such as ./install --only link, and Dotbot will only run those sections of the config file.

--except

You can call ./install --except [list of directives], such as ./install --except shell, and Dotbot will run all the sections of the config file except the ones listed.

Wiki

Check out the Dotbot wiki for more information, tips and tricks, user-contributed plugins, and more.

Contributing

Do you have a feature request, bug report, or patch? Great! See CONTRIBUTING.md for information on what you can do about that.

License

Copyright (c) Anish Athalye. Released under the MIT License. See LICENSE.md for details.

More Repositories

1

neural-style

Neural style in TensorFlow! 🎨
Python
5,539
star
2

git-remote-dropbox

A transparent bridge between Git and Dropbox - use a Dropbox (shared) folder as a Git remote! 🎁
Python
3,055
star
3

lumen

Magic auto brightness based on screen contents 💡
Objective-C
2,286
star
4

gemini

Gemini is a modern LaTex beamerposter theme 🖼
TeX
982
star
5

porcupine

A fast linearizability checker written in Go 🔎
Go
883
star
6

obfuscated-gradients

Obfuscated Gradients Give a False Sense of Security: Circumventing Defenses to Adversarial Examples
Jupyter Notebook
881
star
7

seashells

The official client for seashells.io 🐚
Python
707
star
8

dotfiles

~anish • powered by https://github.com/anishathalye/dotbot 💾
Shell
704
star
9

neural-hash-collider

Preimage attack against NeuralHash 💣
Python
664
star
10

gavel

A project expo judging system 📊
Python
433
star
11

periscope

Periscope gives you "duplicate vision" to help you organize and de-duplicate your files without losing data 🔭
Go
379
star
12

auriga

Auriga is a minimalist LaTeX beamer presentation theme 📽
TeX
328
star
13

offix

"Who is in the office?" 👀
JavaScript
186
star
14

dotfiles_template

A template for structuring dotfiles (using Dotbot as an installer) 📜
PowerShell
184
star
15

ribosome

Synthesize photos from PhotoDNA using machine learning 🌱
Python
141
star
16

imagenet-simple-labels

Simpler human-readable labels for ImageNet 🏷
122
star
17

dotfiles-local

~anish [local config] • powered by https://github.com/anishathalye/dotbot 🏠
Shell
75
star
18

mathematics-of-deep-learning

The Mathematics of Deep Learning, SIPB IAP 2018
Jupyter Notebook
74
star
19

proof-html

A GitHub Action to validate HTML, check links, and more ✅
Ruby
57
star
20

seashells-server

The seashells.io server 🐚
Go
53
star
21

knox

A framework for formally verifying hardware security modules to be free of hardware, software, and timing side-channel vulnerabilities 🔏
Racket
29
star
22

notary

Notary: A Device for Secure Transaction Approval 📟
Verilog
28
star
23

hubot-group

A hubot script that expands mentions of groups 👫
CoffeeScript
26
star
24

synox

Rust library for program synthesis of string transformations from input-output examples 🔮
Rust
26
star
25

knox-hsm

Circuits and hardware security modules formally verified with Knox 🔐
Verilog
23
star
26

disposable

Create a Reddit throwaway account with the click of a button! 🚮
JavaScript
23
star
27

skipchat

SkipChat - MHacks V
C
20
star
28

rtlv

Tools for reasoning about circuits in Rosette/Racket 🔌
Racket
18
star
29

micro-wwvb

A tiny WWVB station 📡
C
17
star
30

linux-bootstrap

get a debian-based system set up the way I like it, with minimal effort on my part
17
star
31

hubot-shortcut

A macro system for hubot 💨
JavaScript
16
star
32

bin2coe

A tool to convert binary files to COE files 💫
Python
14
star
33

anishathalye

A self-updating GitHub profile 🐯
Python
12
star
34

hubot-conf

A simple configuration management system for hubot 🔧
JavaScript
11
star
35

gitlive

the source code that powered gitlive.net
Java
11
star
36

chroniton

A tool for formally verifying constant-time software against hardware 🕰️
Racket
10
star
37

unblock

A tiny utility to make shell pipes behave as if they have unlimited buffering ♾
Go
7
star
38

countdown

A simple countdown timer you can set as your homepage ⏰
HTML
5
star
39

coqioa

A formalization of IO automata in the Coq proof assistant
Coq
5
star
40

x

playground for testing stuff on github
4
star
41

assets

README assets for my GitHub projects 🎭
4
star
42

easy-security

Slides from the SIPB Cluedump on Low Effort High Impact Security
HTML
3
star
43

learn-pgp

Slides from the SIPB Cluedump on PGP
HTML
3
star
44

learn-git

An introduction to using Git - prepared for HackMIT / Hack Week 2015
HTML
2
star
45

deterministic-start-benchmark

Verilog
2
star
46

ipr

A formalization of information-preserving refinement (IPR) in the Coq Proof Assistant 🧩
Coq
2
star
47

xclips

Rust
1
star
48

scripts

Python
1
star
49

formal-methods-tutorial-2022-10-11

Racket
1
star