clog-cli

适用于我们的常规变更日志

关于

clog 从您的本地git元数据自动创建变更日志。请参阅 clog 的 changelog.md 以获取示例。

工作方式是，每次您提交时，都要确保您的提交主题行遵循 常规 格式。然后，当您希望更新您的变更日志时，只需在本地仓库中运行 clog 并指定任何您想使用的选项。

注意： clog 还支持空组件，通过创建如下形式的提交消息（即没有组件）：alias: message 或 alias(): message

用法

使用 clog 有两种方式：通过命令行作为二进制文件，或通过 clog-lib 作为您应用程序中的库。

二进制（命令行）

要使用命令行通过 clog，您必须首先通过自行编译或下载并安装预编译的二进制文件来获取一个二进制文件。

cargo安装

如果您想使用 cargo 同时编译和安装 clog，只需运行

cargo install clog-cli

编译

按照以下说明编译 clog，然后跳到安装部分。

1. 确保您已安装当前版本的 cargo 和 Rust
2. 克隆项目 $ git clone https://github.com/clog-tool/clog-cli && cd clog-cli
3. 构建项目 $ cargo build --release
4. 完成后，二进制文件将位于 target/release/clog

使用预编译的二进制文件

目前没有可用的预编译二进制文件。

注意：Mac 版本可通过 npm 在 clog-cli 获得。

安装

一旦下载或编译了 clog，只需将二进制文件放在您的 $PATH 变量中的某个位置。如果您不熟悉 $PATH，请继续阅读；否则跳到使用 clog。

Arch Linux

您可以使用 AUR 中的 clog-bin，或者按照 Linux / OS X 的说明操作。

Linux / OS X

您有两种选择，将 clog 放入已存在于您的 $PATH 变量中的目录（要查看这些目录，打开终端并输入 echo "${PATH//:/\n}"，引号很重要），或者您可以将自定义目录添加到您的 $PATH

选项 1 如果您有权访问您的 $PATH 列表中列出的任何目录，或者您具有 root 权限（或通过 sudo），只需将 clog 复制到该目录 # sudo cp clog /usr/local/bin

选项 2 如果您没有 root 权限、sudo 或对任何已存在于 $PATH 的目录的写入权限，您可以在您的家目录内创建一个目录，并将其添加进去。许多人使用 $HOME/.bin 来保持其隐藏（并不要弄乱您的家目录），或者如果您想让它始终可见，则使用 $HOME/bin。以下是一个创建目录、将其添加到 $PATH 并将 clog 复制到那里的示例。

只需将 bin 改成你想要的目录名，并将 .bashrc 改成你的 shell 启动文件（通常是 .bashrc、.bash_profile 或 .zshrc）

$ mkdir ~/bin
$ echo "export PATH=$PATH:$HOME/bin" >> ~/.bashrc
$ cp clog ~/bin
$ source ~/.bashrc

Windows

在 Windows 7/8 上，你可以通过以管理员身份打开命令提示符并运行来将目录添加到 PATH 变量

C:\> setx path "%path%;C:\path\to\clog\binary"

否则，请确保你在命令行操作的目录中有 clog 二进制文件，因为 Windows 会自动将你的当前目录添加到 PATH（例如，如果你打开一个命令行来在 C:\my_project\ 中使用 clog，确保 clog.exe 也在该目录中）。

在命令行中使用 clog

clog 通过读取你的 git 元数据和特别定制的提交信息和主题来创建变更日志。 clog 有以下可用选项。

Usage: clog [OPTIONS]

Options:
  -r, --repository <URL>  Repository used for generating commit and issue links (without the .git, e.g.
                          https://github.com/thoughtram/clog)
  -f, --from <COMMIT>     e.g. 12a8546
  -T, --format <STR>      The output format, defaults to markdown [default: markdown] [possible values: markdown,
                          json]
  -M, --major             Increment major version by one (Sets minor and patch to 0)
  -g, --git-dir <PATH>    Local .git directory (defaults to "$(pwd)/.git")
  -w, --work-tree <PATH>  Local working tree of the git project (defaults to "$(pwd)")
  -m, --minor             Increment minor version by one (Sets patch to 0)
  -p, --patch             Increment patch version by one
  -s, --subtitle <STR>    
  -t, --to <COMMIT>       e.g. 8057684 [default: HEAD]
  -o, --outfile <PATH>    Where to write the changelog (Defaults to stdout when omitted)
  -c, --config <COMMIT>   The Clog Configuration TOML file to use [default: .clog.toml]
  -i, --infile <PATH>     A changelog to append to, but *NOT* write to (Useful in conjunction with --outfile)
      --setversion <VER>  e.g. 1.0.1
  -F, --from-latest-tag   use latest tag as start (instead of --from)
  -l, --link-style <STR>  The style of repository link to generate [default: github] [possible values: github,
                          gitlab, stash, cgit]
  -C, --changelog <PATH>  A previous changelog to prepend new changes to (this is like using the same file for both
                          --infile and --outfile and should not be used in conjunction with either)
  -h, --help              Print help
  -V, --version           Print version


If your .git directory is a child of your project directory (most common, such as /myproject/.git) AND not in the
current working directory (i.e you need to use --work-tree or --git-dir) you only need to specify either the
--work-tree (i.e. /myproject) OR --git-dir (i.e. /myproject/.git), you don't need to use both.

If using the --config to specify a clog configuration TOML file NOT in the current working directory (meaning you
need to use --work-tree or --git-dir) AND the TOML file is inside your project directory (i.e.
/myproject/.clog.toml) you do not need to use --work-tree or --git-dir.

试试看！

为了看到它的实际效果，你需要一个已经包含一些这些特别定制的提交信息的仓库。为此，我们将使用 clog 仓库本身。

1. 克隆仓库 git clone https://github.com/clog-tool/clog-cli && cd clog-cli

2. 确保你已经按照上述步骤之一获取了 clog 二进制文件

3. 运行 clog 有许多方法。注意，在这些示例中，我们将反复输入相同的选项，在这种情况下，我们可以使用 clog TOML 配置文件 来指定那些通常不会更改的选项。此外，请注意，所有这些 CLI 选项都有简短版本，我们使用长版本是因为它们更容易理解。

4. 让我们先从我们的上次发布以来的新提交开始（这可能没有多少...或者没有）

5. 运行 clog -r https://github.com/clog-tool/clog-cli --outfile only_new.md

6. 默认情况下，clog 输出到 stdout，除非你在 TOML 配置文件中设置了文件。（注意，我们可以用 shell 的 > 运算符来代替 --outfile）

7. 通过 CLI 设置的任何选项都将覆盖配置文件中设置的任何选项。

8. 现在让我们告诉 clog 它在哪里可以找到我们的旧变更日志，并将任何新提交预接到旧数据上

9. 运行 clog -r https://github.com/clog-tool/clog-cli --infile changelog.md --outfile new_combined.md

10. 最后，假设我们像大多数项目一样，只想使用一个文件，并将所有新数据预接到我们的旧变更日志上（最有用）

11. 首先备份 changelog.md，以便你可以稍后比较它 cp changelog.md changelog.md.bak

12. 运行 clog -r https://github.com/clog-tool/clog-cli --changelog changelog.md

13. 尝试在你的喜欢的 Markdown 查看器中查看 only_new.md、new_combined.md、changelog.md.bak 或 changelog.md 以比较它们。

[clog]
# A repository link with the trailing '.git' which will be used to generate
# all commit and issue links
repository = "https://github.com/clog-tool/clog-cli"
# A constant release title
subtitle = "my awesome title"

# specify the style of commit links to generate, defaults to "github" if omitted
link-style = "github"

# The preferred way to set a constant changelog. This file will be read for old changelog
# data, then prepended to for new changelog data. It's the equivalent to setting
# both infile and outfile to the same file.
#
# Do not use with outfile or infile fields!
#
# Defaults to stdout when omitted
changelog = "mychangelog.md"

# This sets an output file only! If it exists already, new changelog data will be
# prepended, if not it will be created.
#
# This is useful in conjunction with the infile field if you have a separate file
# that you would like to append after newly created clog data
#
# Defaults to stdout when omitted
outfile = "MyChangelog.md"

# This sets the input file old! Any data inside this file will be appended to any
# new data that clog picks up
#
# This is useful in conjunction with the outfile field where you may wish to read
# from one file and append that data to the clog output in another
infile = "My_old_changelog.md"

# This sets the output format. There are two options "json" or "markdown" and
# defaults to "markdown" when omitted
output-format = "json"

# If you use tags, you can set the following if you wish to only pick
# up changes since your latest tag
from-latest-tag = true

[sections]
MySection = ["mysec", "ms"]