projvar - Project Variables

一个命令行界面（命令行接口）工具，用于从给定的数字项目中提取一组基础元数据属性，使用各种来源。

示例场景

projvar 设计用于最佳配合 Git 仓库使用，无论是本地还是 CI（Continuous Integration）系统，尽管它也会对其他项目（部分）有效。

本地项目

项目需要作为一个文件夹存在于本地文件系统中，从这里运行 projvar，它将该项目元数据写入文件。

$ # 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://[email protected]: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"

在 CI（构建机器人）中

1. 检出您的仓库
2. 运行此工具（projvar）
   • 它确保知道一些属性，例如
     • PROJECT_NAME="My Project"
     • PROJECT_VERSION="my-proj-1.2.3-44-ge73gf28"
     • PROJECT_REPO_WEB_URL="https://github.com/user/my-proj"
   • 它以某种方式存储它们，通常使用与 BASH 兼容的语法写入文件
3. 运行使用这些环境变量的其他工具。例如，您可以将其包含在二维码中，然后将其打印到项目中。

如何编译

您需要安装 Rust（语言）和 Cargo。

然后使用以下命令获取整个仓库和 git 子模块

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

然后您可以运行

scripts/build

如果一切顺利，可执行文件可以在 target/release/projvar 中找到。

获取工具

目前您有两种选择

1. 编译它
2. 从 发布页面 下载 Linux x86_64 静态链接的二进制文件

用法

$ 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')

所有支持键/属性列表（如 --list 所示）

资助

此项目由欧洲区域发展基金（ERDF）在INTERFACER项目的背景下资助，从2021年8月（项目开始）到2023年3月。