changelog:
  1f8023d13a399e381176c20bbb6a71763b7c352a:
    type: documentation

examples:
- command: imdl
  text:    "The binary is called `imdl`:"
  code:    "imdl --help"

- command: imdl torrent
  text:    "BitTorrent metainfo related functionality is under the `torrent` subcommand:"
  code:    "imdl torrent --help"

- command: imdl torrent create
  text:    "Intermodal can be used to create `.torrent` files:"
  code:    "imdl torrent create --input foo"

- command: imdl torrent show
  text:    "Print information about existing `.torrent` files:"
  code:    "imdl torrent show --input foo.torrent"

- command: imdl torrent verify
  text:    "Verify downloaded torrents:"
  code:    "imdl torrent verify --input foo.torrent --content foo"

- command: imdl torrent link
  text:    "Generate magnet links from `.torrent` files:"
  code:    "imdl torrent link --input foo.torrent"

- command: imdl torrent piece-length
  text:    "Show infromation about the piece length picker:"
  code:    "imdl torrent piece-length"

- command: imdl completions
  text:    "Print completion scripts for the `imdl` binary:"
  code:    "imdl completions --shell zsh"

- command:  imdl torrent stats
  unstable: true
  text:     "Print information about a collection of torrents:"
  code:     "imdl --unstable torrent stats --input dir"

packages:
- operating-system: '[Various](https://forge.rust-lang.org/release/platform-support.html)'
  package-manager:  '[Cargo](https://www.rust-lang.org)'
  package:          '[imdl](https://crates.io/crates/imdl)'
  command:          '`cargo install imdl`'

- operating-system: '[Arch Linux](https://www.archlinux.org)'
  package-manager:  '[Yay](https://github.com/Jguer/yay)'
  package:          '[intermodal-bin](https://aur.archlinux.org/packages/intermodal-bin)<sup>AUR</sup>'
  command:          '`yay -S intermodal-bin`'

- operating-system: '[Arch Linux](https://www.archlinux.org)'
  package-manager:  '[Yay](https://github.com/Jguer/yay)'
  package:          '[intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup>'
  command:          '`yay -S intermodal`'

- operating-system: '[Arch Linux](https://www.archlinux.org)'
  package-manager:  'Manual Installation'
  package:          '[intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup>'
  command:          '[wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages)'

references:
  - title: BitTorrent
    entries:
    - url: https://github.com/bittorrent/bittorrent.org
      description: >-
        GitHub repository hosting protocol development discussion and contents of
        bittorrent.org.

    - url: https://www.bittorrent.org
      description: >-
        Official web site site hosting BEPs and other information about the
        protocol.

    - url: https://wiki.theory.org/index.php/Main_Page
      description: >-
        Wiki with lots of information about all aspects of the BitTorrent
        protocol and implementations.

    - url: https://archive.org/details/2014_torrent_archive_organized)
      description: >-
        Massive 158 GiB archive containing 5.5 million torrents, assembled in
        2014.

    - url: https://github.com/internetarchive/dweb-transport
      description: >-
        Github repository hosting The Internet Archive's distributed web and
        BitTorrent-related software.

    - url: https://libtorrent.org/udp_tracker_protocol.html
      description: UDP tracker protocol description.

  - title: Metadata
    entries:
    - title: Media RSS Specification
      url: http://www.rssboard.org/media-rss
      description: >-
        _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._

  - title: Cryptography
    entries:
    - url: https://ssbc.github.io/scuttlebutt-protocol-guide/
      description: Secure Scuttlebutt Protocol guide

    - url: https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md
      description: 'Lightning Network Encrypted and Authenticated Transport'

    - url: http://noiseprotocol.org/noise.html
      description: 'Noise Protocol'

    - url: https://github.com/handshake-org/hsd/blob/master/lib/net/brontide.js
      description: 'Handshake P2P Encryption Protocol'

    - url: https://github.com/j01tz/grin-rfcs/blob/slate-serialization/text/0000-slate-serialization.md
      description: 'Grin Slate Serialization'

faq:
- 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:

        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 {}'

- 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
    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 .

- 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.