coliru

commit 74083aad6d0505631f561f33ef057dd37ff814a2
parent 6e0f79df001f5751ca0b755521803fcc303323cb
Author: Asher Morgan <59518073+ashermorgan@users.noreply.github.com>
Date:   Sun, 23 Jun 2024 19:27:04 -0700

Update README.md

Diffstat:
M
README.md
 | 
65
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
M
src/cli.rs
 | 
2
+-

2 files changed, 62 insertions(+), 5 deletions(-)
diff --git a/README.md b/README.md
@@ -1,8 +1,65 @@
 # coliru
 A minimal, flexible, dotfile installer
 
-Dotfiles are defined as a series of steps inside a manifest file, which are
+## Installation
+To install `coliru`, clone the repository and run `cargo install --path coliru/`
+
+To uninstall `coliru`, run `cargo uninstall coliru`
+
+## Usage
+Dotfiles are defined as a series of steps inside a manifest file that are
     executed conditionally based on tag rules.
-An example manifest file is located at `examples/2.yml` and the required YAML
-    structure is defined in `src/manifest.rs`.
-Tag rules follow the format described in `src/tags.rs`.
+To install dotfiles, pass the manifest file and tag rules to `coliru`:
+
+```
+coliru path/to/manifest.yml --tag-rules tag1 tag2,tag3 ^tag4
+```
+
+Some helpful options include:
+
+- `--help`, `-h`: Print full help information
+- `--dry-run`, `-n`: Do a trial run without any permanent changes
+- `--copy`, `-c`: Interpret link commands as copy commands
+
+## Manifest File
+Manifests are defined using YAML.
+Each manifest contains a series of steps that are executed to install the
+    dotfiles.
+Each step contains an array of tags and any number of copy, link, or run
+    commands.
+The copy command copies a file from a source (`src`) to a (`dst`).
+The link command links a file from a source (`src`) to a (`dst`) using symbolic
+    links on Unix platforms and hard links on Windows.
+Finally, the run command executes a script (`src`) from the command line, using
+    `sh` on Unix platforms and `powershell` on Windows, with an optional
+    `prefix` (e.g. `python3`) or `postfix` (e.g. `arg1 arg2 arg3`) string.
+
+Example YAML manifest:
+
+```yml
+steps:
+  - copy:
+    - src: git_dotfiles/.gitconfig
+      dst: ~/.gitconfig
+    link:
+    - src: vim_dotfiles/.vimrc
+      dst: ~/.vimrc
+    tags: [ windows, linux, macos ]
+  - run:
+    - src: install_programs.sh
+      prefix: bash # Unecessary if install_programs.sh is executable
+      postfix: -y
+    tags: [ linux ]
+```
+
+## Tag Rules
+Tag rules are specified on the command line using the `--tag-rules` option.
+In order for a manifest step to be executed, its tags must satisfy all of the
+    tag rules.
+If no tags rules are provided, all manifest steps will be executed.
+Each tag rule contains a comma separated list of tags that will satisfy the
+    rule.
+A leading caret (`^`) will negate the entire rule.
+In other words, commas correspond to OR, carets to NOT, and the spaces between
+    rules to AND.
+So the tag rules `A B,C ^D,E` are equivalent to `A && (B || C) && !(D || E)`.
diff --git a/src/cli.rs b/src/cli.rs
@@ -14,7 +14,7 @@ struct Args {
     #[arg(short, long, num_args=0..)]
     pub tag_rules: Vec<String>,
 
-    /// Copy files instead of creating links
+    /// Interpret link commands as copy commands
     #[arg(short, long)]
     pub copy: bool,