projvar - Project Variables

A CLI (Command-line Interface) tool that extracts a base set of meta data properties from a given, digital project, using various sources.

Example scenarios

projvar is designed to work best for git repositories, both locally or on a CI (Continous Integration) system, though it will also work (partly) for other projects.

Local project

The project needs to be present as a folder on the local file-system, from which one runs projvar, which in turn writes the meta-data for that project into a file

$ # Here we show output for running projvar on its self,
$ # but in your case this will be something else:
# MY_PROJECT_PATH="$HOME/Projects/projvar"
$ cd "$MY_PROJECT_PATH"
$ projvar
[INFO] Using the default out file: .projvars.env.txt
$ cat .projvars.env.txt
PROJECT_BUILD_ARCH="x86_64"
PROJECT_BUILD_BRANCH="master"
PROJECT_BUILD_DATE="2021-12-25 12:50:50"
PROJECT_BUILD_HOSTING_URL="https://hoijui.github.io/projvar"
PROJECT_BUILD_OS="linux"
PROJECT_BUILD_OS_FAMILY="unix"
PROJECT_BUILD_TAG="0.8.0"
PROJECT_CI="false"
PROJECT_LICENSE="AGPL-3.0-only"
PROJECT_LICENSES="CC0-1.0, AGPL-3.0-or-later, Unlicense"
PROJECT_NAME="projvar"
PROJECT_NAME_MACHINE_READABLE="projvar"
PROJECT_REPO_CLONE_URL="https://github.com/hoijui/projvar.git"
PROJECT_REPO_CLONE_URL_SSH="ssh://git@github.com:hoijui/projvar.git"
PROJECT_REPO_COMMIT_PREFIX_URL="https://github.com/hoijui/projvar/commit"
PROJECT_REPO_ISSUES_URL="https://github.com/hoijui/projvar/issues"
PROJECT_REPO_RAW_VERSIONED_PREFIX_URL="https://raw.githubusercontent.com/hoijui/projvar"
PROJECT_REPO_VERSIONED_DIR_PREFIX_URL="https://github.com/hoijui/projvar/tree"
PROJECT_REPO_VERSIONED_FILE_PREFIX_URL="https://github.com/hoijui/projvar/blob"
PROJECT_REPO_WEB_URL="https://github.com/hoijui/projvar"
PROJECT_VERSION="0.8.0-dirty"
PROJECT_VERSION_DATE="2021-12-13 09:18:25"

In CI (build-bot)

1. Check out your repo
2. Run this tool (projvar)
   • it ensures a a few properties are known, for example:
     • PROJECT_NAME="My Project"
     • PROJECT_VERSION="my-proj-1.2.3-44-ge73gf28"
     • PROJECT_REPO_WEB_URL="https://github.com/user/my-proj"
   • it stores them somehow, typically into a file, using BASH source compatible syntax
3. Run some other tool that uses these environment variables. For example, you may include it in a QRCode, which you then print onto your project.

How to compile

You need to install Rust(lang) and Cargo.

Then get the whole repo plus git sub-modules with:

git clone --recurse-submodules https://github.com/hoijui/projvar.git
cd projvar

Then you can run:

scripts/build

If all goes well, the executable can be found at target/release/projvar.

Get the tool

As for now, you have two choices:

1. Compile it yourself
2. Download a Linux x86_64 statically linked binary from the releases page

Usage

$ projvar --version
projvar 0.17.0
$ projvar --help

    A tiny CLI tool that tries to gather project specific meta-data in different ways,
    to store them into environment variables in a file
    for later use by other tools.
    See --list for the keys set by this tool.


Usage: projvar [OPTIONS]

Options:
  -V, --version
          Print version information and exit. May be combined with -q,--quiet, to really only output the version string.

  -C, --project-root <DIR>
          The root directory of the project, mainly used for SCM (e.g. git) information gathering.

          [default: .]

      --raw-panic
          Do not wrap rusts native panic handling functionality in a more end-user-friendly way. This is particularly useful when running on CI.

  -D, --variable <KEY=VALUE>
          A key-value pair (aka a variable) to be used as input, as it it was specified as an environment variable. Values provided with this take precedense over environment variables - they overwrite them. See -I,--variables-file for supplying a lot of such pairs at once.

  -I, --variables-file <FILE>
          An input file containing KEY=VALUE pairs, one per line (BASH style). Empty lines, and those starting with "#" or "//" are ignored. See -D,--variable for specifying one pair at a time.

  -x, --no-env-in
          Disable the use of environment variables as input

  -e, --env-out
          Write resulting values directy into the environment

  -O, --file-out <FILE>
          Write evaluated values into a file. Two file formats are supported: * ENV: one KEY=VALUE pair per line (BASH syntax) * JSON: a dictionary of KEY: "value" You can choose which format is used by the file-extension.
                      Note that "-" has no special meaning here; it does not mean stdout, but rather the file "./-".

          [default: .projvars.env.txt]

  -t, --hosting-type <hosting-type>
          As usually most kinds of repo URL property values are derived from the clone URL, it is essential to know how to construct them. Different hosting softwares construct them differently. By default, we try to derive it from the clone URL domain, but if this is not possible, this switch allows to set the hosting software manually.

          Possible values:
          - git-hub:    <https://github.com> - proprietary
          - git-lab:    <https://about.gitlab.com> - OSS
          - bit-bucket: <https://bitbucket.org> - proprietary
          - source-hut: <https://sr.ht/~sircmpwn/sourcehut> - OSS - LowTech (no JS) hacker tool, (almost) suckless style
          - gitea:      <https://gitea.io> - OSS
          - girocco:    <https://repo.or.cz/girocco.git> - OSS
          - rocket-git: <https://rocketgit.com> - OSS
          - allura:     <https://allura.apache.org> - OSS
          - unknown:    NOTE: The rust masters said, this is better then Option<None>!

  -v, --verbose...
          More verbose log output; useful for debugging. See -F,--log-level for more fine-grained control.

  -F, --log-level <log-level>
          Set the log-level

          [possible values: none, errors, warnings, info, debug, trace]

  -q, --quiet
          Minimize or suppress output to stdout, and only shows log output on stderr. See -F,--log-level to also disable the later. This does not affect the log level for the log-file.

  -f, --fail
          Fail if no value is available for any of the required properties. See --all, --none, --require, --require-not.

  -a, --all
          Marks all properties as required. See --none, --fail, --require, --require-not.

  -n, --none
          Marks all properties as *not* required. See --all, --fail, --require, --require-not.

  -R, --require <KEY>
          Mark a propery as required. \
                      You may use the property name (e.g. "Name") \
                      or the variable key (e.g. "PROJECT_NAME"); \
                      See --list for all possible keys. \
                      If at least one such option is present, \
                      the default required values list is cleared. \
                      See --fail, --all, --none, --require-not.

  -N, --require-not <KEY>
          A key of a variable whose value is *not* required. For example PROJECT_NAME (see --list for all possible keys). Can be used either on the base of the default requried list or all. See --fail, --all, --none, --require.

      --only-required
          Only output the required values. See --all, --none, --require, --require-not.

      --key-prefix <STRING>
          The key prefix to be used when writing out values in the sinks. For example "PROJECT_" -> "PROJECT_VERSION", "PROJECT_NAME", ...

          [default: PROJECT_]

  -d, --dry
          Set Whether to skip the actual setting of environment variables.

  -o, --overwrite <overwrite>
          Whether to overwrite already set values in the output.

          [possible values: all, none, main, alternative]

  -l, --list
          Prints a list of all the environment variables that are potentially set by this tool onto stdout and exits.

  -T, --date-format <date-format>
          Date format string for generated (vs supplied) dates. For details, see https://docs.rs/chrono/latest/chrono/format/strftime/index.html

          [default: "%Y-%m-%d %H:%M:%S"]

  -A, --show-all-retrieved [<MD-FILE>]
          Shows a table (in Markdown syntax) of all properties and the values retrieved for each from each individual source. Writes to log(Info), if no target file is given as argument.

  -P, --show-primary-retrieved [<MD-FILE>]
          Shows a list (in Markdown syntax) of all properties and the primary values retrieved for each, accumulated over the sources. Writes to log(Info), if no target file is given as argument.

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

The list of all supported keys/properties (as shown by --list):

Funding

This project was funded by the European Regional Development Fund (ERDF) in the context of the INTERFACER Project, from August 2021 (project start) until March 2023.