Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix(#362): Improving documentation for returning customers #363

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(#362): Improving documentation for returning customers #363

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 60 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
&& ./install`, even on a freshly installed system!

- [Rationale](#rationale)
- [Installing Your Files](#installing-your-files)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults))
Expand All @@ -16,7 +17,7 @@ Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
## 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
[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
Expand All @@ -30,6 +31,17 @@ resources on the [tutorials
page](https://github.com/anishathalye/dotbot/wiki/Tutorials) for more detailed
explanations of how to organize your dotfiles.

## Installing Your Files

Here is how to install your files:

```bash
git clone $YOUR_REPOSITORY dotfiles # clone your files
cd dotfiles # change directory
chmod +x install # ensure executable
./install # install via dotbot
```

## Getting Started

### Starting Fresh?
Expand Down Expand Up @@ -111,7 +123,7 @@ The conventional name for the configuration file is `install.conf.yaml`.
link:
relink: true

- clean: ['~']
- clean: ["~"]

- link:
~/.tmux.conf: tmux.conf
Expand All @@ -123,7 +135,7 @@ The conventional name for the configuration file is `install.conf.yaml`.
- ~/.vim/undo-history

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

The configuration file is typically written in YAML, but it can also be written
Expand Down Expand Up @@ -168,31 +180,31 @@ files if necessary. Environment variables in paths are automatically expanded.

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*
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: '') |
| 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](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 |
Expand All @@ -218,14 +230,14 @@ When using glob with the `exclude:` option, the paths in the exclude paths shoul
force: true
path: zshrc
~/.hammerspoon:
if: '[ `uname` = Darwin ]'
if: "[ `uname` = Darwin ]"
path: hammerspoon
~/.config/:
path: dotconf/config/**
~/:
glob: true
path: dotconf/*
prefix: '.'
prefix: "."
```

If the source location is omitted or set to `null`, Dotbot will use the
Expand All @@ -248,7 +260,7 @@ Explicit sources:
glob: true
path: config/*
relink: true
exclude: [ config/Code ]
exclude: [config/Code]
~/.config/Code/User/:
create: true
glob: true
Expand All @@ -270,7 +282,7 @@ Implicit sources:
glob: true
path: config/*
relink: true
exclude: [ config/Code ]
exclude: [config/Code]
~/.config/Code/User/:
create: true
glob: true
Expand All @@ -280,7 +292,7 @@ Implicit sources:

### Create

Create commands specify empty directories to be created. This can be useful
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.

Expand All @@ -291,9 +303,9 @@ 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) |
| 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
Expand Down Expand Up @@ -328,14 +340,14 @@ 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) |
| 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
Expand All @@ -347,17 +359,15 @@ printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /

```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
- 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
Expand All @@ -373,18 +383,18 @@ 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) |
| 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: ["~"]

- clean:
~/:
Expand Down