programmer/intermodal
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Don't commit the book

Browse Source 
To avoid bloating commits, don't commit any auto generated from the
book.

type: development
This commit is contained in:
Casey Rodarmor 2020-04-21 00:35:44 -07:00
parent 28114c3d64
commit 4d67d3a10d
No known key found for this signature in database
GPG Key ID: 556186B153EC6FE0
21 changed files with 16 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/build.yaml vendored
View File

@ -117,7 +117,9 @@ jobs:
mdbook-version: latest
- name: Build Book
run: mdbook build book --dest-dir ../www/book
run: |
cargo run --package gen book
mdbook build book --dest-dir ../www/book
- name: Record Git Revision
if: github.ref == 'refs/heads/master' && matrix.os == 'ubuntu-latest'

14
.gitignore vendored
View File

@ -1,6 +1,14 @@
/target
**/*.rs.bk
/www/book
/book/book
/wiki
/book/src/SUMMARY.md
/book/src/bittorrent.md
/book/src/commands.md
/book/src/commands/
/book/src/faq.md
/book/src/introduction.md
/book/src/references
/book/src/references.md
/completions
/target
/wiki
/www/book

3
CHANGELOG.md
View File

@ -4,7 +4,8 @@ Changelog
UNRELEASED - 2020-04-21
-----------------------
- :wrench: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Don't commit shell completion scripts - _Casey Rodarmor <casey@rodarmor.com>_
- :wrench: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Don't commit the book - _Casey Rodarmor <casey@rodarmor.com>_
- :wrench: [`28114c3d64dd`](https://github.com/casey/intermodal/commit/28114c3d64dde5e0275c936b0019eaf4760ba559) Don't commit shell completion scripts - _Casey Rodarmor <casey@rodarmor.com>_
- :art: [`4f4464e3a2a7`](https://github.com/casey/intermodal/commit/4f4464e3a2a7f4aaffea8dbe38dd110ad9be4393) Get `st_flags` from `MetadataExt` on MacOS - _Casey Rodarmor <casey@rodarmor.com>_
- :sparkles: [`deca555ac3b3`](https://github.com/casey/intermodal/commit/deca555ac3b3b8f665ee6415f80e05b2bb5e4af7) Allow suppressing output with `--quiet` - Fixes [#174](https://github.com/casey/intermodal/issues/174) - _Celeo <celeodor@gmail.com>_
- :books: [`838167c4d3bc`](https://github.com/casey/intermodal/commit/838167c4d3bcbe2fa28f27a00bd94b959ad31e15) Describe in FAQ creating torrent from git repo - _Casey Rodarmor <casey@rodarmor.com>_

29
book/src/SUMMARY.md
View File

@ -1,29 +0,0 @@
Summary
=======
[Intermodal](./introduction.md)
- [FAQ](./faq.md)
- [Commands](./commands.md)
- [`imdl`](./commands/imdl.md)
- [`imdl completions`](./commands/imdl-completions.md)
- [`imdl torrent`](./commands/imdl-torrent.md)
- [`imdl torrent create`](./commands/imdl-torrent-create.md)
- [`imdl torrent link`](./commands/imdl-torrent-link.md)
- [`imdl torrent piece-length`](./commands/imdl-torrent-piece-length.md)
- [`imdl torrent show`](./commands/imdl-torrent-show.md)
- [`imdl torrent stats`](./commands/imdl-torrent-stats.md)
- [`imdl torrent verify`](./commands/imdl-torrent-verify.md)
- [Bittorrent](./bittorrent.md)
- [Piece Length Selection](./bittorrent/piece-length-selection.md)
- [BEP Support](./bittorrent/bep-support.md)
- [Metainfo Utilities](./bittorrent/metainfo-utilities.md)
- [Distributing Large Data Sets](./bittorrent/distributing-large-data-sets.md)
- [UDP Tracker Protocol](./bittorrent/udp-tracker-protocol.md)
- [References](./references.md)
- [BitTorrent](./references/bittorrent.md)
- [Metadata](./references/metadata.md)
- [Cryptography](./references/cryptography.md)

5
book/src/bittorrent.md
View File

@ -1,5 +0,0 @@
# BitTorrent
This page intentionally left blank.

5
book/src/commands.md
View File

@ -1,5 +0,0 @@
# Commands
This page intentionally left blank.

20
book/src/commands/imdl-completions.md
View File

@ -1,20 +0,0 @@
# `imdl completions`
```
imdl-completions 0.1.6
Print shell completion scripts to standard output.
USAGE:
imdl completions [OPTIONS] --shell <SHELL>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-d, --dir <DIR> Write completion script to `DIR` with an appropriate
filename. If `--shell` is not given, write all
completion scripts.
-s, --shell <SHELL> Print completion script for `SHELL`. [possible
values: zsh, bash, fish, powershell, elvish]
```

142
book/src/commands/imdl-torrent-create.md
View File

@ -1,142 +0,0 @@
# `imdl torrent create`
```
imdl-torrent-create 0.1.6
Create a .torrent file.
USAGE:
imdl torrent create [FLAGS] [OPTIONS] --input <PATH>
FLAGS:
-n, --dry-run Skip writing `.torrent` file to disk.
-F, --follow-symlinks Follow symlinks in torrent input. By default,
symlinks to files and directories are not included
in torrent contents.
-f, --force Overwrite the destination `.torrent` file, if it
exists.
--help Print help message.
--ignore Skip files listed in `.gitignore`, `.ignore`,
`.git/info/exclude`, and `git config --get
core.excludesFile`.
-h, --include-hidden Include hidden files that would otherwise be
skipped, such as files that start with a `.`, and
files hidden by file attributes on macOS and
Windows.
-j, --include-junk Include junk files that would otherwise be
skipped.
-M, --md5 Include MD5 checksum of each file in the torrent.
N.B. MD5 is cryptographically broken and only
suitable for checking for accidental corruption.
--no-created-by Do not populate `created by` key of generated
torrent with imdl version information.
--no-creation-date Do not populate `creation date` key of generated
torrent with current time.
-O, --open Open `.torrent` file after creation. Uses `xdg-
open`, `gnome-open`, or `kde-open` on Linux;
`open` on macOS; and `cmd /C start` on Windows
--link Print created torrent `magnet:` URL to standard
output
-P, --private Set the `private` flag. Torrent clients that
understand the flag and participate in the swarm
of a torrent with the flag set will only announce
themselves to the announce URLs included in the
torrent, and will not use other peer discovery
mechanisms, such as the DHT or local peer
discovery. See BEP 27: Private Torrents for more
information.
-S, --show Display information about created torrent file.
-V, --version Print version number.
OPTIONS:
-A, --allow <LINT>...
Allow `LINT`. Lints check for conditions which, although permitted,
are not usually desirable. For example, piece length can be any non-
zero value, but probably shouldn't be below 16 KiB. The lint
`small-piece-size` checks for this, and `--allow small-piece-size`
can be used to disable this check. [possible values: private-
trackerless, small-piece-length, uneven-piece-length]
-a, --announce <URL>
Use `URL` as the primary tracker announce URL. To supply multiple
announce URLs, also use `--announce-tier`.
-t, --announce-tier <URL-LIST>...
Use `URL-LIST` as a tracker announce tier. Each instance adds a new
tier. To add multiple trackers to a given tier, separate their
announce URLs with commas:
`--announce-tier
udp://example.com:80/announce,https://example.net:443/announce`
Announce tiers are stored in the `announce-list` key of the top-
level metainfo dictionary as a list of lists of strings, as
defined by BEP 12: Multitracker Metadata Extension.
Note: Many BitTorrent clients do not implement the behavior
described in BEP 12. See the discussion here for more details:
https://github.com/bittorrent/bittorrent.org/issues/82
-c, --comment <TEXT>
Include `TEXT` as the comment for generated `.torrent` file. Stored
under `comment` key of top-level metainfo dictionary.
--node <NODE>...
Add DHT bootstrap node `NODE` to torrent. `NODE` should be in the
form `HOST:PORT`, where `HOST` is a domain name, an IPv4 address, or
an IPv6 address surrounded by brackets. May be given more than once
to add multiple bootstrap nodes.
Examples:
--node router.example.com:1337
--node 203.0.113.0:2290
--node [2001:db8:4275:7920:6269:7463:6f69:6e21]:8832
-g, --glob <GLOB>...
Include or exclude files that match `GLOB`. Multiple glob may be
provided, with the last one taking precedence. Precede a glob with
`!` to exclude it.
-i, --input <PATH>
Read torrent contents from `PATH`. If `PATH` is a file, torrent will
be a single-file torrent. If `PATH` is a directory, torrent will be
a multi-file torrent. If `PATH` is `-`, read from standard input.
Piece length defaults to 256KiB when reading from standard input if
`--piece-length` is not given.
-N, --name <TEXT>
Set name of torrent to `TEXT`. Defaults to the filename of the
argument to `--input`. Required when `--input -`.
-o, --output <TARGET>
Save `.torrent` file to `TARGET`, or print to standard output if
`TARGET` is `-`. Defaults to the argument to `--input` with an
`.torrent` extension appended. Required when `--input -`.
--peer <PEER>... Add `PEER` to magnet link.
-p, --piece-length <BYTES>
Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and
gib.
--sort-by <SPEC>...
Set the order of files within a torrent. `SPEC` should be of the
form `KEY:ORDER`, with `KEY` being one of `path` or `size`, and
`ORDER` being `ascending` or `descending`. `:ORDER` defaults to
`ascending` if omitted. The `--sort-by` flag may be given more than
once, with later values being used to break ties. Ties that remain
are broken in ascending path order.
Sort in ascending order by path, the default:
--sort-by path:ascending
Sort in ascending order by path, more concisely:
--sort-by path
Sort in ascending order by size, break ties in descending path
order:
--sort-by size:ascending --sort-by path:descending
-s, --source <TEXT>
Set torrent source to `TEXT`. Stored under `source` key of info
dictionary. This is useful for keeping statistics from being mis-
reported when participating in swarms with the same contents,
but with different trackers. When source is set to a unique value
for torrents with the same contents, torrent clients will treat them
as distinct torrents, and not share peers between them, and will
correctly report download and upload statistics to multiple
trackers.
```

25
book/src/commands/imdl-torrent-link.md
View File

@ -1,25 +0,0 @@
# `imdl torrent link`
```
imdl-torrent-link 0.1.6
Generate a magnet link from a .torrent file.
USAGE:
imdl torrent link [FLAGS] [OPTIONS] --input <METAINFO>
FLAGS:
-h, --help Print help message.
-O, --open Open generated magnet link. Uses `xdg-open`, `gnome-open`,
or `kde-open` on Linux; `open` on macOS; and `cmd /C start`
on Windows.
-V, --version Print version number.
OPTIONS:
-s, --select-only <INDICES>...
Select files to download. Values are indices into the `info.files`
list, e.g. `--select-only 1,2,3`.
-i, --input <METAINFO>
Generate magnet link from metainfo at `PATH`. If `PATH` is `-`, read
metainfo from standard input.
-p, --peer <PEER>... Add `PEER` to magnet link.
```

13
book/src/commands/imdl-torrent-piece-length.md
View File

@ -1,13 +0,0 @@
# `imdl torrent piece-length`
```
imdl-torrent-piece-length 0.1.6
Display information about automatic piece length selection.
USAGE:
imdl torrent piece-length
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
```

17
book/src/commands/imdl-torrent-show.md
View File

@ -1,17 +0,0 @@
# `imdl torrent show`
```
imdl-torrent-show 0.1.6
Display information about a .torrent file.
USAGE:
imdl torrent show --input <PATH>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-i, --input <PATH> Show information about torrent at `PATH`. If `Path` is
`-`, read torrent metainfo from standard input.
```

31
book/src/commands/imdl-torrent-stats.md
View File

@ -1,31 +0,0 @@
# `imdl torrent stats`
```
imdl-torrent-stats 0.1.6
Show statistics about a collection of .torrent files.
USAGE:
imdl torrent stats [FLAGS] [OPTIONS] --input <PATH>
FLAGS:
-h, --help Print help message.
-p, --print Pretty print the contents of each torrent as it is
processed.
-V, --version Print version number.
OPTIONS:
-e, --extract-pattern <REGEX>...
Extract and display values under key paths that match `REGEX`.
Subkeys of a bencodeded dictionary are delimited by `/`, and values
of a bencoded list are delmited by `*`. For example, given the
following bencoded dictionary `{"foo": [{"bar": {"baz": 2}}]}`, the
value `2`'s key path will be `foo*bar/baz`. The value `2` would be
displayed if any of `bar`, `foo[*]bar/baz`, or `foo.*baz` were
passed to `--extract-pattern.
-i, --input <PATH>
Search `PATH` for torrents. May be a directory or a single torrent
file.
-l, --limit <N>
Stop after processing `N` torrents. Useful when processing large
collections of `.torrent` files.
```

21
book/src/commands/imdl-torrent-verify.md
View File

@ -1,21 +0,0 @@
# `imdl torrent verify`
```
imdl-torrent-verify 0.1.6
Verify files against a .torrent file.
USAGE:
imdl torrent verify [OPTIONS] --input <METAINFO>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-c, --content <PATH> Verify torrent content at `PATH` against torrent
metainfo. Defaults to `name` field of torrent info
dictionary.
-i, --input <METAINFO> Verify torrent contents against torrent metainfo
in `METAINFO`. If `METAINFO` is `-`, read metainfo
from standard input.
```

24
book/src/commands/imdl-torrent.md
View File

@ -1,24 +0,0 @@
# `imdl torrent`
```
imdl-torrent 0.1.6
Subcommands related to the BitTorrent protocol.
USAGE:
imdl torrent <SUBCOMMAND>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
SUBCOMMANDS:
create Create a .torrent file.
help Prints this message or the help of the given
subcommand(s)
link Generate a magnet link from a .torrent file.
piece-length Display information about automatic piece length
selection.
show Display information about a .torrent file.
stats Show statistics about a collection of .torrent files.
verify Verify files against a .torrent file.
```

39
book/src/commands/imdl.md
View File

@ -1,39 +0,0 @@
# `imdl`
```
imdl v0.1.6
Casey Rodarmor <casey@rodarmor.com>
📦 A 40' shipping container for the internet -
https://github.com/casey/intermodal
USAGE:
imdl [FLAGS] [OPTIONS] <SUBCOMMAND>
FLAGS:
-h, --help Print help message.
-q, --quiet Suppress normal output.
-t, --terminal Disable automatic terminal detection and behave as if both
standard output and standard error are connected to a
terminal.
-u, --unstable Enable unstable features. To avoid premature stabilization
and excessive version churn, unstable features are
unavailable unless this flag is set. Unstable features are
not bound by semantic versioning stability guarantees, and
may be changed or removed at any time.
-V, --version Print version number.
OPTIONS:
-c, --color <WHEN> Print colorful output according to `WHEN`. When
`auto`, the default, colored output is only enabled if
imdl detects that it is connected to a terminal, the
`NO_COLOR` environment variable is not set, and the
`TERM` environment variable is not set to `dumb`.
[default: auto] [possible values: auto, always,
never]
SUBCOMMANDS:
completions Print shell completion scripts to standard output.
help Prints this message or the help of the given
subcommand(s)
torrent Subcommands related to the BitTorrent protocol.
```

40
book/src/faq.md
View File

@ -1,40 +0,0 @@
FAQ
===
- [Can intermodal be used to preview torrents with `fzf`?](#fzf-preview)
- [Can intermodal be used to create a torrent from a Git repo?](#git-repo)
<a name="fzf-preview"></a>
## Can intermodal be used to preview torrents with `fzf`?
</h2>
Yes! [@mustaqimM](https://github.com/mustaqimM) came up with the following:
fzf --preview='imdl --color always --terminal torrent show --input {}
_Note the use of `--color always` and `--terminal` to force colored, human readable output._
This can be used to, for example, preview the torrents in a directory:
find . -name '*.torrent' | fzf --preview='imdl -c always -t torrent show -i {}'
<a name="git-repo"></a>
## Can intermodal be used to create a torrent from a Git repo?
</h2>
Yes! The `--ignore` flag, contributed by [@Celeo](https://github.com/Celeo), can be used
to make `imdl torrent create` respect `.gitignore` files:
imdl torrent create --ignore --include-hidden --include-junk --glob '!.git/*' --input .
In addition to `--ignore`, `--include-hidden`, `--include-junk`, and `--glob '!.git/*'`
are used to include files, like `.gitignore`, that are present in the repo but would
otherwise be skipped, and to skip the contents of the `.git` directory.
Equivalently, with short flags:
imdl torrent create --ignore -hjg '!.git/*' -i .

62
book/src/introduction.md
View File

@ -1,62 +0,0 @@
# Intermodal: A 40' shipping container for the Internet
Intermodal is a user-friendly and featureful command-line BitTorrent metainfo utility for Linux, Windows, and macOS.
Project development is hosted on [GitHub](https://github.com/casey/intermodal).
The binary is called `imdl`:
```sh
$ imdl --help
```
BitTorrent metainfo related functionality is under the `torrent` subcommand:
```sh
$ imdl torrent --help
```
Intermodal can be used to create `.torrent` files:
```sh
$ imdl torrent create --input foo
```
Print information about existing `.torrent` files:
```sh
$ imdl torrent show --input foo.torrent
```
Verify downloaded torrents:
```sh
$ imdl torrent verify --input foo.torrent --content foo
```
Generate magnet links from `.torrent` files:
```sh
$ imdl torrent link --input foo.torrent
```
Show infromation about the piece length picker:
```sh
$ imdl torrent piece-length
```
Print completion scripts for the `imdl` binary:
```sh
$ imdl completions --shell zsh
```
Functionality that is not yet finalized, but still available for preview, can be accessed with the `--unstable` flag:
Print information about a collection of torrents:
```sh
$ imdl --unstable torrent stats --input dir
```
Happy sharing!

5
book/src/references.md
View File

@ -1,5 +0,0 @@
# References
This page intentionally left blank.

13
book/src/references/bittorrent.md
View File

@ -1,13 +0,0 @@
# BitTorrent
- [https://github.com/bittorrent/bittorrent.org](https://github.com/bittorrent/bittorrent.org) — GitHub repository hosting protocol development discussion and contents of bittorrent.org.
- [https://www.bittorrent.org/](https://www.bittorrent.org/) — Official web site site hosting BEPs and other information about the protocol.
- [https://wiki.theory.org/index.php/Main_Page](https://wiki.theory.org/index.php/Main_Page) — Wiki with lots of information about all aspects of the BitTorrent protocol and implementations.
- [https://archive.org/details/2014_torrent_archive_organized)](https://archive.org/details/2014_torrent_archive_organized)) — Massive 158 GiB archive containing 5.5 million torrents, assembled in 2014.
- [https://github.com/internetarchive/dweb-transport](https://github.com/internetarchive/dweb-transport) — Github repository hosting The Internet Archive's distributed web and BitTorrent-related software.
- [https://libtorrent.org/udp_tracker_protocol.html](https://libtorrent.org/udp_tracker_protocol.html) — UDP tracker protocol description.

11
book/src/references/cryptography.md
View File

@ -1,11 +0,0 @@
# Cryptography
- [https://ssbc.github.io/scuttlebutt-protocol-guide/](https://ssbc.github.io/scuttlebutt-protocol-guide/) — Secure Scuttlebutt Protocol guide
- [https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md) — Lightning Network Encrypted and Authenticated Transport
- [http://noiseprotocol.org/noise.html](http://noiseprotocol.org/noise.html) — Noise Protocol
- [https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js](https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js) — Handshake P2P Encryption Protocol
- [https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md](https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md) — Grin Slate Serialization

3
book/src/references/metadata.md
View File

@ -1,3 +0,0 @@
# Metadata
- [Media RSS Specification](http://www.rssboard.org/media-rss) — _Media RSS is a new RSS module that supplements the <enclosure> capabilities of RSS 2.0. RSS enclosures are already being used to syndicate audio files and images. Media RSS extends enclosures to handle other media types, such as short films or TV, as well as provide additional metadata with the media. Media RSS enables content publishers and bloggers to syndicate multimedia content such as TV and video clips, movies, images and audio._