| Name | dotbot JSON |
| Version |
1.23.1
JSON |
| download |
| home_page | None |
| Summary | A tool that bootstraps your dotfiles |
| upload_time | 2025-08-03 00:30:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
dotfiles
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Dotbot [](https://github.com/anishathalye/dotbot/actions/workflows/ci.yml) [](https://app.codecov.io/gh/anishathalye/dotbot) [](https://pypi.org/pypi/dotbot/) [](https://pypi.org/pypi/dotbot/)
Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles && ./install`, even on a freshly installed system!
- [Rationale](#rationale)
- [Getting Started](#getting-started)
- [Installing Your Dotfiles](#installing-your-dotfiles)
- [Configuration](#configuration)
- [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults))
- [Plugins](#plugins)
- [Command-line Arguments](#command-line-arguments)
- [Wiki][wiki]
---
## 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](https://www.anishathalye.com/2014/08/03/managing-your-dotfiles/) or more resources on the [tutorials page](https://github.com/anishathalye/dotbot/wiki/Tutorials) 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][init-dotfiles] script. If you'd rather use a template repository, check out [dotfiles_template][dotfiles-template]. Or, if you're just looking for [some inspiration][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.
You can create an empty configuration file with:
```bash
touch install.conf.yaml
```
If you're using **Git**, you can add Dotbot as a submodule:
```bash
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 .
```
If you're using **Mercurial**, you can add Dotbot as a subrepo:
```bash
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 .
```
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][windows-symlinks].
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](#full-example) config file as well as [configuration documentation](#configuration) 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.
#### Installation as a command-line program
If you prefer, instead of bundling Dotbot as a submodule with your dotfiles, you can install Dotbot from [PyPI] as a standalone command-line program. Use the tool of your choice, such as `pip` or [`uv`][uv]:
```bash
uv tool install dotbot
```
Some systems include Dotbot in their native package manager, such as [Homebrew][homebrew-dotbot] and [Arch Linux][arch-dotbot], so for example, you can also install it with `brew install dotbot`.
With Dotbot installed as a command-line program on your system, 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`.
```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][json2yaml]). JSON configuration files are conventionally named `install.conf.json`.
## Installing Your Dotfiles
To install your dotfiles on a new machine or after updates:
```bash
git clone <your-dotfiles-repo-url> ~/.dotfiles
cd ~/.dotfiles
./install
```
To update an existing installation:
```bash
cd ~/.dotfiles
git pull
./install
```
## 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](#link) files and folders, [create](#create) folders, execute [shell](#shell) commands, and [clean](#clean) directories of broken symbolic links. Dotbot also supports user [plugins](#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][json2yaml] 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](#defaults).
### Link
Link commands create symbolic links at specified locations that point to files in your dotfiles repository. This allows you to keep your configuration files in version control while having them appear where applications expect to find them. Symlinks are created by default, but hardlinks are also supported. 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 link names to targets. The link name (key) is where the symbolic link will be created, and the target (value) is the file in your dotfiles directory that the link will point to. Targets 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 targets directly, link names are mapped to extended configuration dictionaries.
| Parameter | Explanation |
| --- | --- |
| `path` | The target for the link (file in dotfiles directory), the same as in the shortcut syntax (default: null, automatic (see below)) |
| `type` | The type of link to create. If specified, must be either `symlink` or `hardlink`. (default: `symlink`) |
| `create` | When true, create parent directories to the link as needed. (default: false) |
| `relink` | Removes the old link if it's a symlink (default: false) |
| `force` | Force removes the old link, file or folder, and forces a new link (default: false) |
| `relative` | When creating a symlink, use a relative path to the target. (default: false, absolute links) |
| `canonicalize` | Resolve any symbolic links encountered in the target 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 target 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](https://docs.python.org/3/library/glob.html#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 |
| `?` | 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
```yaml
- 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/:
glob: true
path: dotconf/config/**
~/:
glob: true
path: dotconf/*
prefix: '.'
```
If the target location is omitted or set to `null`, Dotbot will use the basename of the link name, with a leading `.` stripped if present. This makes the following two config files equivalent.
Explicit targets:
```yaml
- 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 targets:
```yaml
- 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](https://docs.python.org/3/library/os.html#mkdir-modebits). Its behavior is platform-dependent. On Unix systems, the current umask value is first masked out.
#### Example
```yaml
- 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
```yaml
- 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
```yaml
- 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
```yaml
- 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.
Plugins should declare support for dry-run with `supports_dry_run = True`, and implement this support by logging what the plugin _would_ do (without doing it) when `Context.dry_run()` is set. Plugins that don't explicitly declare support for dry-run will be skipped when Dotbot is run with `--dry-run`.
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.
See [here][plugins] for a current list of third-party plugins.
#### Loading plugins via configuration
You can specify plugins in your configuration file as an array of files or directories (containing plugins) to load:
```yaml
- plugins:
- dotbot-plugins/dotbot-brew/
- dotbot-plugins/custom_plugin.py
```
Paths specified in the config file are interpreted relative to the _base directory_.
#### Loading plugins via command line
Plugins can also be loaded using the `--plugin` option. You can use this argument multiple times:
```bash
dotbot --plugin dotbot-plugins/dotbot-brew/ --plugin dotbot-plugins/custom_plugin.py ...
```
Paths specified this way are interpreted relative to the _working directory_ where `dotbot` is invoked.
It is recommended that these options are added directly to your `install` script for consistency across installations.
## Command-line arguments
Dotbot takes a number of command-line arguments; you can run Dotbot with `--help`, for example, by running `./install --help`, to see the full list of options. Here, we highlight a couple that are particularly interesting.
### `--dry-run`
You can call `./install --dry-run`, and Dotbot will explain what it _would_ do, without actually making any changes. This can be helpful for safely testing your configuration. Plugins that don't support dry-run will be skipped.
### `--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][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][contributing] for information on what you can do about that.
## License
Copyright (c) Anish Athalye. Released under the MIT License. See [LICENSE.md][license] for details.
[PyPI]: https://pypi.org/project/dotbot/
[uv]: https://github.com/astral-sh/uv
[homebrew-dotbot]: https://formulae.brew.sh/formula/dotbot
[arch-dotbot]: https://aur.archlinux.org/packages/dotbot
[init-dotfiles]: https://github.com/Vaelatern/init-dotfiles
[dotfiles-template]: https://github.com/anishathalye/dotfiles_template
[inspiration]: https://github.com/anishathalye/dotbot/wiki/Users
[windows-symlinks]: https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links
[json2yaml]: https://www.json2yaml.com/
[plugins]: https://github.com/anishathalye/dotbot/wiki/Plugins
[wiki]: https://github.com/anishathalye/dotbot/wiki
[contributing]: CONTRIBUTING.md
[license]: LICENSE.md
Raw data
{
"_id": null,
"home_page": null,
"name": "dotbot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "dotfiles",
"author": null,
"author_email": "Anish Athalye <me@anishathalye.com>",
"download_url": "https://files.pythonhosted.org/packages/05/4b/8308f726306d3d983323dd9bfa55e3610a07168f56ef612ecae05998ed55/dotbot-1.23.1.tar.gz",
"platform": null,
"description": "# Dotbot [](https://github.com/anishathalye/dotbot/actions/workflows/ci.yml) [](https://app.codecov.io/gh/anishathalye/dotbot) [](https://pypi.org/pypi/dotbot/) [](https://pypi.org/pypi/dotbot/)\n\nDotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles && ./install`, even on a freshly installed system!\n\n- [Rationale](#rationale)\n- [Getting Started](#getting-started)\n- [Installing Your Dotfiles](#installing-your-dotfiles)\n- [Configuration](#configuration)\n- [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults))\n- [Plugins](#plugins)\n- [Command-line Arguments](#command-line-arguments)\n- [Wiki][wiki]\n\n---\n\n## Rationale\n\nDotbot 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.\n\nDotbot 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.\n\nSee [this blog post](https://www.anishathalye.com/2014/08/03/managing-your-dotfiles/) or more resources on the [tutorials page](https://github.com/anishathalye/dotbot/wiki/Tutorials) for more detailed explanations of how to organize your dotfiles.\n\n## Getting started\n\n### Starting fresh?\n\nGreat! You can automate the creation of your dotfiles by using the user-contributed [init-dotfiles][init-dotfiles] script. If you'd rather use a template repository, check out [dotfiles_template][dotfiles-template]. Or, if you're just looking for [some inspiration][inspiration], we've got you covered.\n\n### Integrate with existing dotfiles\n\nThe following will help you get set up using Dotbot in just a few steps.\n\nYou can create an empty configuration file with:\n\n```bash\ntouch install.conf.yaml\n```\n\nIf you're using **Git**, you can add Dotbot as a submodule:\n\n```bash\ncd ~/.dotfiles # replace with the path to your dotfiles\ngit init # initialize repository if needed\ngit submodule add https://github.com/anishathalye/dotbot\ngit config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule\ncp dotbot/tools/git-submodule/install .\n```\n\nIf you're using **Mercurial**, you can add Dotbot as a subrepo:\n\n```bash\ncd ~/.dotfiles # replace with the path to your dotfiles\nhg init # initialize repository if needed\necho \"dotbot = [git]https://github.com/anishathalye/dotbot\" > .hgsub\nhg add .hgsub\ngit clone https://github.com/anishathalye/dotbot\ncp dotbot/tools/hg-subrepo/install .\n```\n\nIf 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][windows-symlinks].\n\nTo 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](#full-example) config file as well as [configuration documentation](#configuration) for the accepted parameters.\n\nNote: 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.\n\nSetting 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.\n\n#### Installation as a command-line program\n\nIf you prefer, instead of bundling Dotbot as a submodule with your dotfiles, you can install Dotbot from [PyPI] as a standalone command-line program. Use the tool of your choice, such as `pip` or [`uv`][uv]:\n\n```bash\nuv tool install dotbot\n```\n\nSome systems include Dotbot in their native package manager, such as [Homebrew][homebrew-dotbot] and [Arch Linux][arch-dotbot], so for example, you can also install it with `brew install dotbot`.\n\nWith Dotbot installed as a command-line program on your system, you can invoke Dotbot with `dotbot -c <path to configuration file>`.\n\n### Full example\n\nHere's an example of a complete configuration.\n\nThe conventional name for the configuration file is `install.conf.yaml`.\n\n```yaml\n- defaults:\n link:\n relink: true\n\n- clean: ['~']\n\n- link:\n ~/.tmux.conf: tmux.conf\n ~/.vim: vim\n ~/.vimrc: vimrc\n\n- create:\n - ~/downloads\n - ~/.vim/undo-history\n\n- shell:\n - [git submodule update --init --recursive, Installing submodules]\n```\n\nThe configuration file is typically written in YAML, but it can also be written in JSON (which is a [subset of YAML][json2yaml]). JSON configuration files are conventionally named `install.conf.json`.\n\n## Installing Your Dotfiles\n\nTo install your dotfiles on a new machine or after updates:\n\n```bash\ngit clone <your-dotfiles-repo-url> ~/.dotfiles\ncd ~/.dotfiles\n./install\n```\n\nTo update an existing installation:\n\n```bash\ncd ~/.dotfiles\ngit pull\n./install\n```\n\n## Configuration\n\nDotbot uses YAML or JSON-formatted configuration files to let you specify how to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and folders, [create](#create) folders, execute [shell](#shell) commands, and [clean](#clean) directories of broken symbolic links. Dotbot also supports user [plugins](#plugins) for custom commands.\n\n**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).\n\nDotbot 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.\n\nWhen 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][json2yaml] and check that it is correct.\n\n## Directives\n\nMost Dotbot commands support both a simplified and extended syntax, and they can also be configured via setting [defaults](#defaults).\n\n### Link\n\nLink commands create symbolic links at specified locations that point to files in your dotfiles repository. This allows you to keep your configuration files in version control while having them appear where applications expect to find them. Symlinks are created by default, but hardlinks are also supported. If desired, items can be specified to be forcibly linked, overwriting existing files if necessary. Environment variables in paths are automatically expanded.\n\n#### Format\n\nLink commands are specified as a dictionary mapping link names to targets. The link name (key) is where the symbolic link will be created, and the target (value) is the file in your dotfiles directory that the link will point to. Targets are specified relative to the base directory (that is specified when running the installer). If linking directories, *do not* include a trailing slash.\n\nLink commands support an optional extended configuration. In this type of configuration, instead of specifying targets directly, link names are mapped to extended configuration dictionaries.\n\n| Parameter | Explanation |\n| --- | --- |\n| `path` | The target for the link (file in dotfiles directory), the same as in the shortcut syntax (default: null, automatic (see below)) |\n| `type` | The type of link to create. If specified, must be either `symlink` or `hardlink`. (default: `symlink`) |\n| `create` | When true, create parent directories to the link as needed. (default: false) |\n| `relink` | Removes the old link if it's a symlink (default: false) |\n| `force` | Force removes the old link, file or folder, and forces a new link (default: false) |\n| `relative` | When creating a symlink, use a relative path to the target. (default: false, absolute links) |\n| `canonicalize` | Resolve any symbolic links encountered in the target to symlink to the canonical path (default: true, real paths) |\n| `if` | Execute this in your `$SHELL` and only link if it is successful. |\n| `ignore-missing` | Do not fail if the target is missing and create the link anyway (default: false) |\n| `glob` | Treat `path` as a glob pattern, expanding patterns referenced below, linking all *files* matched. (default: false) |\n| `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) |\n| `prefix` | Prepend prefix prefix to basename of each file when linked, when `glob` is `true`. (default: '') |\n\nWhen `glob: true`, Dotbot uses [glob.glob](https://docs.python.org/3/library/glob.html#glob.glob) to resolve glob paths, expanding Unix shell-style wildcards, which are **not** the same as regular expressions; Only the following are expanded:\n\n| Pattern | Meaning |\n|:---------|:-----------------------------------|\n| `*` | matches anything |\n| `**` | matches any **file**, recursively |\n| `?` | matches any single character |\n| `[seq]` | matches any character in `seq` |\n| `[!seq]` | matches any character not in `seq` |\n\nHowever, 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/.*`.\n\nWhen 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\"`).\n\n#### Example\n\n```yaml\n- link:\n ~/.config/terminator:\n create: true\n path: config/terminator\n ~/.vim: vim\n ~/.vimrc:\n relink: true\n path: vimrc\n ~/.zshrc:\n force: true\n path: zshrc\n ~/.hammerspoon:\n if: '[ `uname` = Darwin ]'\n path: hammerspoon\n ~/.config/:\n glob: true\n path: dotconf/config/**\n ~/:\n glob: true\n path: dotconf/*\n prefix: '.'\n```\n\nIf the target location is omitted or set to `null`, Dotbot will use the basename of the link name, with a leading `.` stripped if present. This makes the following two config files equivalent.\n\nExplicit targets:\n\n```yaml\n- link:\n ~/bin/ack: ack\n ~/.vim: vim\n ~/.vimrc:\n relink: true\n path: vimrc\n ~/.zshrc:\n force: true\n path: zshrc\n ~/.config/:\n glob: true\n path: config/*\n relink: true\n exclude: [ config/Code ]\n ~/.config/Code/User/:\n create: true\n glob: true\n path: config/Code/User/*\n relink: true\n```\n\nImplicit targets:\n\n```yaml\n- link:\n ~/bin/ack:\n ~/.vim:\n ~/.vimrc:\n relink: true\n ~/.zshrc:\n force: true\n ~/.config/:\n glob: true\n path: config/*\n relink: true\n exclude: [ config/Code ]\n ~/.config/Code/User/:\n create: true\n glob: true\n path: config/Code/User/*\n relink: true\n```\n\n### Create\n\nCreate 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.\n\n#### Format\n\nCreate 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.\n\n| Parameter | Explanation |\n| --- | --- |\n| `mode` | The file mode to use for creating the leaf directory (default: 0777) |\n\nThe `mode` parameter is treated in the same way as in Python's [os.mkdir](https://docs.python.org/3/library/os.html#mkdir-modebits). Its behavior is platform-dependent. On Unix systems, the current umask value is first masked out.\n\n#### Example\n\n```yaml\n- create:\n - ~/downloads\n - ~/.vim/undo-history\n- create:\n ~/.ssh:\n mode: 0700\n ~/projects:\n```\n\n### Shell\n\nShell commands specify shell commands to be run. Shell commands are run in the base directory (that is specified when running the installer).\n\n#### Format\n\nShell 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.\n\nAnother 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.\n\nShell commands support an extended syntax as well, which provides more fine-grained control.\n\n| Parameter | Explanation |\n| --- | --- |\n| `command` | The command to be run |\n| `description` | A human-readable message describing the command (default: null) |\n| `quiet` | Show only the description but not the command in log output (default: false) |\n| `stdin` | Allow a command to read from standard input (default: false) |\n| `stdout` | Show a command's output from stdout (default: false) |\n| `stderr` | Show a command's error output from stderr (default: false) |\n\nNote 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.\n\n#### Example\n\n```yaml\n- shell:\n - chsh -s $(which zsh)\n - [chsh -s $(which zsh), Making zsh the default shell]\n -\n command: read var && echo Your variable is $var\n stdin: true\n stdout: true\n description: Reading and printing variable\n quiet: true\n -\n command: read fail\n stderr: true\n```\n\n### Clean\n\nClean 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`.\n\n#### Format\n\nClean commands are specified as an array of directories to be cleaned.\n\nClean commands also support an extended configuration syntax.\n\n| Parameter | Explanation |\n| --- | --- |\n| `force` | Remove dead links even if they don't point to a file inside the dotfiles directory (default: false) |\n| `recursive` | Traverse the directory recursively looking for dead links (default: false) |\n\nNote: using the `recursive` option for `~` is not recommended because it will be slow.\n\n#### Example\n\n```yaml\n- clean: ['~']\n\n- clean:\n ~/:\n force: true\n ~/.config:\n recursive: true\n```\n\n### Defaults\n\nDefault 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.\n\nDefaults 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.\n\n#### Format\n\nDefaults are specified as a dictionary mapping action names to settings, which are dictionaries from option names to values.\n\n#### Example\n\n```yaml\n- defaults:\n link:\n create: true\n relink: true\n```\n\n### Plugins\n\nDotbot 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.\n\nPlugins should declare support for dry-run with `supports_dry_run = True`, and implement this support by logging what the plugin _would_ do (without doing it) when `Context.dry_run()` is set. Plugins that don't explicitly declare support for dry-run will be skipped when Dotbot is run with `--dry-run`.\n\nAll 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.\n\nSee [here][plugins] for a current list of third-party plugins.\n\n#### Loading plugins via configuration\n\nYou can specify plugins in your configuration file as an array of files or directories (containing plugins) to load:\n\n```yaml\n- plugins:\n - dotbot-plugins/dotbot-brew/\n - dotbot-plugins/custom_plugin.py\n```\n\nPaths specified in the config file are interpreted relative to the _base directory_.\n\n#### Loading plugins via command line\n\nPlugins can also be loaded using the `--plugin` option. You can use this argument multiple times:\n\n```bash\ndotbot --plugin dotbot-plugins/dotbot-brew/ --plugin dotbot-plugins/custom_plugin.py ...\n```\n\nPaths specified this way are interpreted relative to the _working directory_ where `dotbot` is invoked.\n\nIt is recommended that these options are added directly to your `install` script for consistency across installations.\n\n## Command-line arguments\n\nDotbot takes a number of command-line arguments; you can run Dotbot with `--help`, for example, by running `./install --help`, to see the full list of options. Here, we highlight a couple that are particularly interesting.\n\n### `--dry-run`\n\nYou can call `./install --dry-run`, and Dotbot will explain what it _would_ do, without actually making any changes. This can be helpful for safely testing your configuration. Plugins that don't support dry-run will be skipped.\n\n### `--only`\n\nYou can call `./install --only [list of directives]`, such as `./install --only link`, and Dotbot will only run those sections of the config file.\n\n### `--except`\n\nYou 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.\n\n## Wiki\n\nCheck out the [Dotbot wiki][wiki] for more information, tips and tricks, user-contributed plugins, and more.\n\n## Contributing\n\nDo you have a feature request, bug report, or patch? Great! See [CONTRIBUTING.md][contributing] for information on what you can do about that.\n\n## License\n\nCopyright (c) Anish Athalye. Released under the MIT License. See [LICENSE.md][license] for details.\n\n[PyPI]: https://pypi.org/project/dotbot/\n[uv]: https://github.com/astral-sh/uv\n[homebrew-dotbot]: https://formulae.brew.sh/formula/dotbot\n[arch-dotbot]: https://aur.archlinux.org/packages/dotbot\n[init-dotfiles]: https://github.com/Vaelatern/init-dotfiles\n[dotfiles-template]: https://github.com/anishathalye/dotfiles_template\n[inspiration]: https://github.com/anishathalye/dotbot/wiki/Users\n[windows-symlinks]: https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links\n[json2yaml]: https://www.json2yaml.com/\n[plugins]: https://github.com/anishathalye/dotbot/wiki/Plugins\n[wiki]: https://github.com/anishathalye/dotbot/wiki\n[contributing]: CONTRIBUTING.md\n[license]: LICENSE.md\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool that bootstraps your dotfiles",
"version": "1.23.1",
"project_urls": {
"homepage": "https://github.com/anishathalye/dotbot",
"issues": "https://github.com/anishathalye/dotbot/issues",
"repository": "https://github.com/anishathalye/dotbot.git"
},
"split_keywords": [
"dotfiles"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "238e66c0a61c716509c4ad2ea505ad12a05971257f51042e5d985cd039cd665b",
"md5": "27a05a020231247314bb19d60e27412d",
"sha256": "9d54098d03a6b4f3350509b93e00857a79564973c7425fb0def530cddbbcc967"
},
"downloads": -1,
"filename": "dotbot-1.23.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27a05a020231247314bb19d60e27412d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26937,
"upload_time": "2025-08-03T00:30:03",
"upload_time_iso_8601": "2025-08-03T00:30:03.553334Z",
"url": "https://files.pythonhosted.org/packages/23/8e/66c0a61c716509c4ad2ea505ad12a05971257f51042e5d985cd039cd665b/dotbot-1.23.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "054b8308f726306d3d983323dd9bfa55e3610a07168f56ef612ecae05998ed55",
"md5": "76ce245e14b982a9e3c53975f3e9cd4f",
"sha256": "b6e419a898c03d2ecaaf802af9764041ac583fc59e367bdde509640c5d193f3b"
},
"downloads": -1,
"filename": "dotbot-1.23.1.tar.gz",
"has_sig": false,
"md5_digest": "76ce245e14b982a9e3c53975f3e9cd4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40413,
"upload_time": "2025-08-03T00:30:02",
"upload_time_iso_8601": "2025-08-03T00:30:02.348698Z",
"url": "https://files.pythonhosted.org/packages/05/4b/8308f726306d3d983323dd9bfa55e3610a07168f56ef612ecae05998ed55/dotbot-1.23.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 00:30:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anishathalye",
"github_project": "dotbot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dotbot"
}
