Cargo Describe

Basically cargo metadata, but with output that can be scripted against that doesn't require cryptic jq commands.

Install

The usual way. cargo install cargo-describe.

Usage

CLI tool to produce human-friendly information from cargo-metadata

Usage: cargo-describe.exe [OPTIONS]

Options:
  -m, --manifest <MANIFEST>
          Path to a non-standard 'Cargo.toml' package manifest, if not in current directory

  -o, --output-format <OUTPUT_FORMAT>
          The output format of this tool

          [default: human-text]

          Possible values:
          - human-text: Pretty human text
          - csv:        Comma separated values
          - md-table:   Markdown Table
          - plain:      No formatting, one value per line

  -f, --fields <FIELDS>
          An optional list of manifest fields to display

          [default: name version]

          Possible values:
          - name:                          Name of the package
          - version:                       Version of the package from the manifest
          - git-version:                   'Git Describe' output of the specific package
          - module-relative-path:          Path to the module's dir, relative to the root dir
          - module-absolute-path:          Absolute path on disk to the module dir
          - module-relative-manifest-path: Path to the module's Cargo.toml, relative to the root dir
          - module-absolute-manifest-path: Absolute path on disk to the module's Cargo.toml
          - all:                           Prints everything

  -p, --package <PACKAGE>
          An optional list of crate packages members to display in this workspace

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Examples

...when run from the root of this repository:

No Arguments, "Human Pretty Format":

$> cargo run --bin cargo-describe -- 
irox
        Version : 0.5.0
irox-carto
        Version : 0.5.0
irox-enums
        Version : 0.2.1
irox-enums_derive
        Version : 0.2.1
irox-time
        Version : 0.3.5
...snipped...

Human Pretty, all fields:

$> cargo run --bin cargo-describe -- -fall
irox
        Version : 0.5.0
        Git Version : irox-0.5.0-10-g23110f9
        Module Relative Path : irox
        Module Absolute Path : V:\irox\irox\
        Manifest Relative Path : irox\Cargo.toml
        Manifest Absolute Path : V:\irox\irox\Cargo.toml
irox-carto
        Version : 0.5.0
        Git Version : irox-carto-0.5.0-44-gf2d62c7
        Module Relative Path : libraries\carto
        Module Absolute Path : V:\irox\libraries\carto\
        Manifest Relative Path : libraries\carto\Cargo.toml
        Manifest Absolute Path : V:\irox\libraries\carto\Cargo.toml
irox-enums
        Version : 0.2.1
        Git Version : irox-enums-0.2.1-48-g7b1646e
        Module Relative Path : libraries\enums
        Module Absolute Path : V:\irox\libraries\enums\
        Manifest Relative Path : libraries\enums\Cargo.toml
        Manifest Absolute Path : V:\irox\libraries\enums\Cargo.toml
irox-enums_derive
        Version : 0.2.1
        Git Version : irox-enums_derive-0.2.1-49-g845a800
        Module Relative Path : libraries\enums_derive
        Module Absolute Path : V:\irox\libraries\enums_derive\
        Manifest Relative Path : libraries\enums_derive\Cargo.toml
        Manifest Absolute Path : V:\irox\libraries\enums_derive\Cargo.toml
...snipped..

Plain Output (easiest for scripting):

Will print just the values of the specified fields, one per line organized by package.

$> cargo run --bin cargo-describe -- -o plain -f module-relative-manifest-path
irox\Cargo.toml
libraries\carto\Cargo.toml
libraries\enums\Cargo.toml
libraries\enums_derive\Cargo.toml
libraries\time\Cargo.toml
libraries\tools\Cargo.toml
libraries\units\Cargo.toml
data-formats\csv\Cargo.toml
libraries\egui_extras\Cargo.toml
data-formats\gpx\Cargo.toml
interfaces\influxdb_v1\Cargo.toml
libraries\network\Cargo.toml
libraries\types\Cargo.toml
libraries\log\Cargo.toml
data-formats\nmea0183\Cargo.toml
libraries\progress\Cargo.toml
data-formats\raymarine-sonar\Cargo.toml
data-formats\sirf\Cargo.toml
libraries\structs\Cargo.toml
libraries\structs_derive\Cargo.toml
libraries\stats\Cargo.toml
libraries\threading\Cargo.toml
interfaces\win-location-api\Cargo.toml
eieio\api\Cargo.toml
eieio\nmea0183\Cargo.toml
libraries\build-rs\Cargo.toml
tools\cargo-describe\Cargo.toml
tools\gpsd\Cargo.toml
tools\halflifes\Cargo.toml
tools\influx-cli\Cargo.toml
tools\sonar-sdf-convert\Cargo.toml

CSV with Filtering:

$> cargo run --bin cargo-describe -- -o csv -p irox-tools -p cargo-describe
Name,Version
irox-tools,0.4.1
cargo-describe,0.1.0

Markdown Table (filtered):

using -o md-table will print a markdown-formatted table

$> cargo run --bin cargo-describe -- -o md-table -p irox-tools -p cargo-describe
| Name           | Version |
|----------------|---------|
| irox-tools     | 0.4.1   |
| cargo-describe | 0.1.0   |

Which renders as:

Markdown Table with All Fields (filtered):

using -f all will print all available fields:

$> cargo run --bin cargo-describe -- -o md-table -p irox-tools -p cargo-describe -f all

| Name           | Version | GitVersion                      | ModuleRelativePath   | ModuleAbsolutePath            | ModuleRelativeManifestPath      | ModuleAbsoluteManifestPath              |
|----------------|---------|---------------------------------|----------------------|-------------------------------|---------------------------------|-----------------------------------------|
| irox-tools     | 0.4.1   | irox-tools-0.4.1-14-g465c708    | libraries\tools      | V:\irox\libraries\tools\      | libraries\tools\Cargo.toml      | V:\irox\libraries\tools\Cargo.toml      |
| cargo-describe | 0.1.0   | cargo-describe-0.1.0-1-g1762e52 | tools\cargo-describe | V:\irox\tools\cargo-describe\ | tools\cargo-describe\Cargo.toml | V:\irox\tools\cargo-describe\Cargo.toml |

Which renders as:

Fields

Name

• -f name or -f all
• Output: The package name from the Cargo.toml manifest
• Example for irox-tools: irox-tools

Version

• -f version or -f all
• Output: The package version from the Cargo.toml manifest
• Example for irox-tools: 0.4.1

Git Version

This provides a slightly different variant of git describe. Rather than operating on the entire repository, it only operates on the specific package directory of the repository. It would be like if git describe accepted a path filtering parameter like git log <path>... does. As if git log <package-dir> | git describe worked.

• -f git-version or -f all
• Output: My preferred variant of git describe:
  • {name}-{version}-{commit_count}-g{short_hash}{-dirty}
    • name: The same as -f name - the package name from the manifest
    • tag: Attempts to find the latest git tag that contains the last commit for that packages directory. If it cannot find a commit, then will revert back to the output of -f version - the version from the manifest file
    • commit_count: The number of commits HEAD is after {tag}
    • short_hash: The git short-hash of HEAD
    • -dirty: Optional dirty suffix if the working tree is dirty
• Example for irox-tools: irox-tools-0.4.1-14-g465c708
• Example for dirty irox-tools: irox-tools-0.4.1-14-g465c708-dirty

Module Relative Path

• -f module-relative-path or -f all
• Output: The relative path of the package against the root of the workspace. What would be in the root manifests members array
• Example for irox-tools: libraries\tools

Module Absolute Path

• -f module-absolute-path or -f all
• Output: The absolute path on disk of the package. If run from the root of the workspace, the same as pwd/module-relative-path
• Example for irox-tools: V:\irox\libraries\tools

Module Relative Manifest Path

• -f module-relative-manifest-path or -f all
• Output: module-relative-path + Cargo.toml.
• Example for irox-tools: libaries\tools\Cargo.toml

Module Absolute Manifest Path

• -f module-absolute-manifest-path or -f all
• Output: module-absolute-path + Cargo.toml
• Example for irox-tools: V:\irox\libraries\tools\Cargo.toml