diff --git a/CHANGELOG.md b/CHANGELOG.md index 9543d3e..e4d366e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,10 @@ Changelog ========= -UNRELEASED - 2020-04-24 +UNRELEASED - 2020-04-25 ----------------------- -- :wrench: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Improve the done and merge recipes - _Casey Rodarmor _ +- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Improve documentation - _Casey Rodarmor _ +- :wrench: [`f8711a79a3d9`](https://github.com/casey/intermodal/commit/f8711a79a3d92da5b30fd3e8b7bba7a5e2d73766) Improve the done and merge recipes - _Casey Rodarmor _ - :wrench: [`97ee5684f8e0`](https://github.com/casey/intermodal/commit/97ee5684f8e0f8de7dbdb4f930018c8df0f012b1) Don't invalid build cache when `Cargo.lock` changes - _Casey Rodarmor _ - :books: [`c75ec39b14bb`](https://github.com/casey/intermodal/commit/c75ec39b14bb4375a875d2d2c73718b44eb54e12) Remove watch dropdown image from readme - _Casey Rodarmor _ - :books: [`8fbe39726fe6`](https://github.com/casey/intermodal/commit/8fbe39726fe6c5bdc342dbd0764f8052ddd03597) Add notes for packagers to readme - _Casey Rodarmor _ diff --git a/README.md b/README.md index 2244208..6623cd2 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ For more about the project and its goals, check out - [Linux and MacOS Install Script](#linux-and-macos-install-script) - [Cargo](#cargo) - [Shell Completion Scripts](#shell-completion-scripts) +- [Usage](#usage) + - [Commands](#commands) + - [Examples](#examples) + - [FAQ](#faq) - [Notes for Packagers](#notes-for-packagers) - [Package Artifacts](#package-artifacts) - [Binary](#binary) @@ -131,6 +135,36 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`: $ imdl completions --shell zsh --dir $fpath[0] ``` + +## Usage + +Online documentation is available in the book, hosted +[here](https://imdl.io/book/). + +### Commands + +Adding `--help` to any command will print help text about how to use that +command, including detailed information about any command-line arguments it +accepts. + +So, to get information about `imdl torrent create`, run `imdl torrent create +--help`. + +Additionally, the same help text is available online in +[the book](https://imdl.io/book/). + +### Examples + +The intro to [the book](https://imdl.io/book/) has a few simple examples. Check +[the FAQ](https://imdl.io/book/faq.html) for more complex usage examples. + +### FAQ + +The [FAQ](https://imdl.io/book/faq.html) covers a variety of specific +use-cases. If there's a use case you think should be covered, feel free to open +[an issue](https://github.com/casey/intermodal/issues/new). + + ## Notes for Packagers First off, thank you very much! If I can do anything to make packaging diff --git a/bin/gen/config.yaml b/bin/gen/config.yaml index 0cee6e9..71bff7d 100644 --- a/bin/gen/config.yaml +++ b/bin/gen/config.yaml @@ -123,7 +123,7 @@ references: description: 'Grin Slate Serialization' faq: -- title: Can intermodal be used to preview torrents with `fzf`? +- title: Can Intermodal be used to preview torrents with `fzf`? anchor: fzf-preview text: |- Yes! [@mustaqimM](https://github.com/mustaqimM) came up with the following: @@ -136,7 +136,7 @@ faq: find . -name '*.torrent' | fzf --preview='imdl -c always -t torrent show -i {}' -- title: Can intermodal be used to create a torrent from a Git repo? +- title: Can Intermodal be used to create a torrent from a Git repo? anchor: git-repo text: |- Yes! The `--ignore` flag, contributed by [@Celeo](https://github.com/Celeo), can be used @@ -151,3 +151,41 @@ faq: Equivalently, with short flags: imdl torrent create --ignore -hjg '!.git/*' -i . + +- title: How do I include and exclude files when creating a torrent? + anchor: include + text: |- + There are a few ways to control which files are included when you create a torrent. + + By default, symlinks, hidden files, and common "junk" files are excluded. To include these files, use: + + - `--follow-symlinks` to include files pointed to by a symlink. + - `--include-hidden` to include files with names that start with `.` or are hidden by a file attribute. + - `--include-junk` to include "junk" files like `.DS_Store`. + + The `--ignore` flag makes Intermodal respect `.gitignore` and `.ignore` files. + + This can be used to [create a torrent from a Git repository](#git-repo), or to exclude files by creating a file called `.ignore`, adding patterns with the same syntax as `.gitignore` that match those files, and using `--ignore` when you create the torrent. + + Additionally, you can use `--glob PATTERN` to both include and exclude files. + + If `PATTERN` does not start with `!`, only those files that match `PATTERN` will be included. + + If `PATTERN` starts with `!`, those files that match `PATTERN` will be excluded. + + `--glob` can be passed multiple times, to include multiple subsets of files: + + # only include `foo/bar` and `foo/bob` + imdl torrent create --input foo --glob bar/ --glob bob/ + + To exclude multiple subsets of files: + + # don't include `foo/bar` and `foo/bob` + imdl torrent create --input foo --glob '!bar/' --glob '!bob/' + + Or to refine a pattern: + + # include everything in `foo/bar` but not anything in `foo/bar/baz` + imdl torrent create --input foo --glob `bar/` --glob `!bar/baz/` + + `--glob` can be passed any number of times. If multiple `PATTERN`s match a path, the last one on the command line takes precedence. diff --git a/bin/gen/templates/README.md b/bin/gen/templates/README.md index 5f3257e..fd3c316 100644 --- a/bin/gen/templates/README.md +++ b/bin/gen/templates/README.md @@ -108,6 +108,36 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`: $ imdl completions --shell zsh --dir $fpath[0] ``` + +## Usage + +Online documentation is available in the book, hosted +[here](https://imdl.io/book/). + +### Commands + +Adding `--help` to any command will print help text about how to use that +command, including detailed information about any command-line arguments it +accepts. + +So, to get information about `imdl torrent create`, run `imdl torrent create +--help`. + +Additionally, the same help text is available online in +[the book](https://imdl.io/book/). + +### Examples + +The intro to [the book](https://imdl.io/book/) has a few simple examples. Check +[the FAQ](https://imdl.io/book/faq.html) for more complex usage examples. + +### FAQ + +The [FAQ](https://imdl.io/book/faq.html) covers a variety of specific +use-cases. If there's a use case you think should be covered, feel free to open +[an issue](https://github.com/casey/intermodal/issues/new). + + ## Notes for Packagers First off, thank you very much! If I can do anything to make packaging