psi-jack/dotbot
1
0
Fork 0
mirror of synced 2024-09-19 11:12:53 -04:00
Code Issues Releases Wiki Activity

fix(#362): Improving documentation for returning customers

Browse source
This commit is contained in:
Tristan Watson 2024-06-16 13:35:44 +02:00
parent 720206578a
commit 302e2f77a8
1 changed files with 60 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
README.md
View file

@ -4,6 +4,7 @@ Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
&& ./install`, even on a freshly installed system! && ./install`, even on a freshly installed system!
- [Rationale](#rationale) - [Rationale](#rationale)
- [Installing Your Files](#installing-your-files)
- [Getting Started](#getting-started) - [Getting Started](#getting-started)
- [Configuration](#configuration) - [Configuration](#configuration)
- [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults)) - [Directives](#directives) ([Link](#link), [Create](#create), [Shell](#shell), [Clean](#clean), [Defaults](#defaults))
@ -16,7 +17,7 @@ Dotbot makes installing your dotfiles as easy as `git clone $url && cd dotfiles
## Rationale ## Rationale
Dotbot is a tool that bootstraps your dotfiles (it's a [Dot]files 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. control systems do more than you think.
Dotbot is designed to be lightweight and self-contained, with no external Dotbot is designed to be lightweight and self-contained, with no external
@ -30,6 +31,17 @@ resources on the [tutorials
page](https://github.com/anishathalye/dotbot/wiki/Tutorials) for more detailed page](https://github.com/anishathalye/dotbot/wiki/Tutorials) for more detailed
explanations of how to organize your dotfiles. 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 ## Getting Started
### Starting Fresh? ### Starting Fresh?
@ -111,7 +123,7 @@ The conventional name for the configuration file is `install.conf.yaml`.
link: link:
relink: true relink: true
- clean: ['~'] - clean: ["~"]
- link: - link:
~/.tmux.conf: tmux.conf ~/.tmux.conf: tmux.conf
@ -168,7 +180,7 @@ files if necessary. Environment variables in paths are automatically expanded.
Link commands are specified as a dictionary mapping targets to source Link commands are specified as a dictionary mapping targets to source
locations. Source locations are specified relative to the base directory (that 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. include a trailing slash.
Link commands support an optional extended configuration. In this type of Link commands support an optional extended configuration. In this type of
@ -176,7 +188,7 @@ configuration, instead of specifying source locations directly, targets are
mapped to extended configuration dictionaries. mapped to extended configuration dictionaries.
| Parameter | Explanation | | Parameter | Explanation |
| --- | --- | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path` | The source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below)) | | `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) | | `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) | | `relink` | Removes the old target if it's a symlink (default: false) |
@ -185,14 +197,14 @@ mapped to extended configuration dictionaries.
| `canonicalize` | Resolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths) | | `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. | | `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) | | `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) | | `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) | | `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: '') | | `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: 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 | | Pattern | Meaning |
|:---------|:-----------------------------------| | :------- | :--------------------------------- |
| `*` | matches anything | | `*` | matches anything |
| `**` | matches any **file**, recursively | | `**` | matches any **file**, recursively |
| `?` | matches any single character | | `?` | matches any single character |
@ -218,14 +230,14 @@ When using glob with the `exclude:` option, the paths in the exclude paths shoul
force: true force: true
path: zshrc path: zshrc
~/.hammerspoon: ~/.hammerspoon:
if: '[ `uname` = Darwin ]' if: "[ `uname` = Darwin ]"
path: hammerspoon path: hammerspoon
~/.config/: ~/.config/:
path: dotconf/config/** path: dotconf/config/**
~/: ~/:
glob: true glob: true
path: dotconf/* path: dotconf/*
prefix: '.' prefix: "."
``` ```
If the source location is omitted or set to `null`, Dotbot will use the If the source location is omitted or set to `null`, Dotbot will use the
@ -292,7 +304,7 @@ as dictionaries. For convenience, it's permissible to leave the options blank
(null) in the dictionary syntax. (null) in the dictionary syntax.
| Parameter | Explanation | | Parameter | Explanation |
| --- | --- | | --------- | -------------------------------------------------------------------- |
| `mode` | The file mode to use for creating the leaf directory (default: 0777) | | `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 The `mode` parameter is treated in the same way as in Python's
@ -329,7 +341,7 @@ Shell commands support an extended syntax as well, which provides more
fine-grained control. fine-grained control.
| Parameter | Explanation | | Parameter | Explanation |
| --- | --- | | ------------- | ---------------------------------------------------------------------------- |
| `command` | The command to be run | | `command` | The command to be run |
| `description` | A human-readable message describing the command (default: null) | | `description` | A human-readable message describing the command (default: null) |
| `quiet` | Show only the description but not the command in log output (default: false) | | `quiet` | Show only the description but not the command in log output (default: false) |
@ -349,14 +361,12 @@ printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /
- shell: - shell:
- chsh -s $(which zsh) - chsh -s $(which zsh)
- [chsh -s $(which zsh), Making zsh the default shell] - [chsh -s $(which zsh), Making zsh the default shell]
- - command: read var && echo Your variable is $var
command: read var && echo Your variable is $var
stdin: true stdin: true
stdout: true stdout: true
description: Reading and printing variable description: Reading and printing variable
quiet: true quiet: true
- - command: read fail
command: read fail
stderr: true stderr: true
``` ```
@ -374,7 +384,7 @@ Clean commands are specified as an array of directories to be cleaned.
Clean commands also support an extended configuration syntax. Clean commands also support an extended configuration syntax.
| Parameter | Explanation | | Parameter | Explanation |
| --- | --- | | ----------- | --------------------------------------------------------------------------------------------------- |
| `force` | Remove dead links even if they don't point to a file inside the dotfiles directory (default: false) | | `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) | | `recursive` | Traverse the directory recursively looking for dead links (default: false) |
@ -384,7 +394,7 @@ be slow.
#### Example #### Example
```yaml ```yaml
- clean: ['~'] - clean: ["~"]
- clean: - clean:
~/: ~/: