psi-jack/dotbot
1
0
Fork 0
mirror of synced 2024-11-22 08:15:34 -05: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

110
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
@ -123,7 +135,7 @@ The conventional name for the configuration file is `install.conf.yaml`.
- ~/.vim/undo-history - ~/.vim/undo-history
- shell: - 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 The configuration file is typically written in YAML, but it can also be written
@ -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 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
configuration, instead of specifying source locations directly, targets are 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) |
| `force` | Force removes the old target, file or folder, and forces a new link (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) | | `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) | | `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
@ -248,7 +260,7 @@ Explicit sources:
glob: true glob: true
path: config/* path: config/*
relink: true relink: true
exclude: [ config/Code ] exclude: [config/Code]
~/.config/Code/User/: ~/.config/Code/User/:
create: true create: true
glob: true glob: true
@ -270,7 +282,7 @@ Implicit sources:
glob: true glob: true
path: config/* path: config/*
relink: true relink: true
exclude: [ config/Code ] exclude: [config/Code]
~/.config/Code/User/: ~/.config/Code/User/:
create: true create: true
glob: true glob: true
@ -280,7 +292,7 @@ Implicit sources:
### Create ### 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 for scaffolding out folders or parent folder structure required for various
apps, plugins, shell commands, etc. apps, plugins, shell commands, etc.
@ -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 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
[os.mkdir](https://docs.python.org/3/library/os.html#mkdir-modebits). Its [os.mkdir](https://docs.python.org/3/library/os.html#mkdir-modebits). Its
@ -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 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) |
| `stdin` | Allow a command to read from standard input (default: false) | | `stdin` | Allow a command to read from standard input (default: false) |
| `stdout` | Show a command's output from stdout (default: false) | | `stdout` | Show a command's output from stdout (default: false) |
| `stderr` | Show a command's error output from stderr (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 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 output, it does not control whether the output from running the command is
@ -347,17 +359,15 @@ printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /
```yaml ```yaml
- 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
- stderr: true
command: read fail
stderr: true
``` ```
### Clean ### Clean
@ -373,10 +383,10 @@ 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) |
Note: using the `recursive` option for `~` is not recommended because it will Note: using the `recursive` option for `~` is not recommended because it will
be slow. be slow.
@ -384,7 +394,7 @@ be slow.
#### Example #### Example
```yaml ```yaml
- clean: ['~'] - clean: ["~"]
- clean: - clean:
~/: ~/: