Improve documentation
- Document the various ways files can be included and excluded from torrents in the book. - Make links to the book more prominent in the readme, by including them in sections with obvious names. type: documentation
This commit is contained in:
Casey Rodarmor
parent
f8711a79a3
commit
d077da405e
|
|
@ -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 <casey@rodarmor.com>_
|
||||
- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Improve documentation - _Casey Rodarmor <casey@rodarmor.com>_
|
||||
- :wrench: [`f8711a79a3d9`](https://github.com/casey/intermodal/commit/f8711a79a3d92da5b30fd3e8b7bba7a5e2d73766) Improve the done and merge recipes - _Casey Rodarmor <casey@rodarmor.com>_
|
||||
- :wrench: [`97ee5684f8e0`](https://github.com/casey/intermodal/commit/97ee5684f8e0f8de7dbdb4f930018c8df0f012b1) Don't invalid build cache when `Cargo.lock` changes - _Casey Rodarmor <casey@rodarmor.com>_
|
||||
- :books: [`c75ec39b14bb`](https://github.com/casey/intermodal/commit/c75ec39b14bb4375a875d2d2c73718b44eb54e12) Remove watch dropdown image from readme - _Casey Rodarmor <casey@rodarmor.com>_
|
||||
- :books: [`8fbe39726fe6`](https://github.com/casey/intermodal/commit/8fbe39726fe6c5bdc342dbd0764f8052ddd03597) Add notes for packagers to readme - _Casey Rodarmor <casey@rodarmor.com>_
|
||||
|
|
|
|||
34
README.md
34
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user