You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://gitter.im/thoughtram/clog?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
`clog` creates a changelog automatically from your local git metadata. See the `clog`s [changelog.md](https://github.com/thoughtram/clog/blob/master/changelog.md) for an example.
14
+
`clog` creates a changelog automatically from your local git metadata. See the `clog`s [changelog.md](https://github.com/clog-tool/clog-lib/blob/master/changelog.md) for an example.
15
15
16
-
The way this works, is every time you make a commit, you ensure your commit subject line follows the [conventional](https://github.com/thoughtram/clog/blob/master/changelog.md) format. Then when you wish to update your changelog, you simply run `clog` inside your local repository with any options you'd like to specify.
16
+
The way this works, is every time you make a commit, you ensure your commit subject line follows the [conventional](https://github.com/ajoslin/conventional-changelog/blob/a5505865ff3dd710cf757f50530e73ef0ca641da/conventions/angular.md) format.
17
17
18
18
*NOTE:*`clog` also supports empty components by making commit messages such as `alias: message` or `alias(): message` (i.e. without the component)
19
19
20
20
21
21
## Usage
22
22
23
-
There are two ways to use `clog`, as a binary via the command line or as a library in your applicaitons.
23
+
There are two ways to use `clog`, as a binary via the command line (See [clog-cli](https://github.com/clog-tool/clog-cli) for details) or as a library in your applicaitons.
24
24
25
-
### Binary (Command Line)
26
-
27
-
In order to use `clog` via the command line you must first obtain a binary by either compiling it yourself, or downlading and installing one of the precompiled binaries.
28
-
29
-
#### Compiling
30
-
31
-
Follow these instructions to compile `clog`, then skip down to Installation.
32
-
33
-
1. Ensure you have current version of `cargo` and [Rust](https://www.rust-lang.org) installed
34
-
2. Clone the project `$ git clone https://github.com/thoughtram/clog && cd clog`
35
-
3. Build the project `$ cargo build --release`
36
-
4. Once complete, the binary will be located at `target/release/clog`
37
-
38
-
#### Using a Precompiled Binary
39
-
40
-
There are several precompiled binaries readily availbe. Browse to http://wod.twentyfives.net/bin/clog/ and download the latest binary for your particular OS. Once you download and extract the tar file (or zip for Windows), the binary will be located at `bin/clog`
41
-
42
-
**Note**: The Mac distribution is available on npm via [clog-cli](http://npm.im/clog-cli).
43
-
44
-
#### Installation
45
-
46
-
Once you have downloaded, or compiled, `clog` you simply need to place the binary somewhere in your `$PATH`. If you are not familiar with `$PATH` read-on; otherwise skip down to Using clog.
47
-
48
-
##### Arch Linux
49
-
50
-
You can use `clog-bin` from the AUR, or follow the instructions for Linux / OS X
51
-
52
-
##### Linux / OS X
53
-
54
-
You have two options, place `clog` into a directory that is already located in your `$PATH` variable (To see which directories those are, open a terminal and type `echo "${PATH//:/\n}"`, the quotation marks are important), or you can add a custom directory to your `$PATH`
55
-
56
-
**Option 1**
57
-
If you have write permission to a directory listed in your `$PATH` or you have root permission (or via `sudo`), simply copy the `clog` to that directory `# sudo cp clog /usr/local/bin`
58
-
59
-
**Option 2**
60
-
If you do not have root, `sudo`, or write permission to any directory already in `$PATH` you can create a directory inside your home directory, and add that. Many people use `$HOME/.bin` to keep it hidden (and not clutter your home directory), or `$HOME/bin` if you want it to be always visible. Here is an example to make the directory, add it to `$PATH`, and copy `clog` there.
61
-
62
-
Simply change `bin` to whatever you'd like to name the directory, and `.bashrc` to whatever your shell startup file is (usually `.bashrc`, `.bash_profile`, or `.zshrc`)
63
-
64
-
```sh
65
-
$ mkdir ~/bin
66
-
$ echo"export PATH=$PATH:$HOME/bin">>~/.bashrc
67
-
$ cp clog ~/bin
68
-
$ source~/.bashrc
69
-
```
70
-
71
-
##### Windows
72
-
73
-
On Windows 7/8 you can add directory to the `PATH` variable by opening a command line as an administrator and running
74
-
75
-
```sh
76
-
C:\> setx path "%path%;C:\path\to\clog\binary"
77
-
```
78
-
Otherwise, ensure you have the `clog` binary in the directory which you operating in the command line from, because Windows automatically adds your current directory to PATH (i.e. if you open a command line to `C:\my_project\` to use `clog` ensure `clog.exe` is inside that directory as well).
79
-
80
-
#### Using clog from the Command Line
81
-
82
-
`clog` works by reading your `git` metadata and specially crafted commit messages and subjects to create a changelog. `clog` has the following options availble.
83
-
84
-
```sh
85
-
USAGE:
86
-
clog [FLAGS] [OPTIONS]
87
-
88
-
FLAGS:
89
-
-F, --from-latest-tag use latest tag as start (instead of --from)
90
-
-h, --help Prints help information
91
-
-M, --major Increment major version by one (Sets minor and patch to 0)
92
-
-m, --minor Increment minor version by one (Sets patch to 0)
93
-
-p, --patch Increment patch version by one
94
-
-V, --version Prints version information
95
-
96
-
OPTIONS:
97
-
-C, --changelog <changelog> A previous changelog to prepend new changes to (this is like
98
-
using the same file for both --infile and --outfile and
99
-
should not be used in conjuction with either)
100
-
-c, --config <config> The Clog Configuration TOML file to use (Defaults to
101
-
'.clog.toml')**
102
-
-T, --format <format> The output format, defaults to markdown
103
-
(valid values: markdown, json)
104
-
-f, --from <from> e.g. 12a8546
105
-
-g, --git-dir <gitdir> Local .git directory (defaults to current dir + '.git')*
106
-
-i, --infile <infile> A changelog to append to, but *NOT* write to (Useful in
107
-
conjunction with --outfile)
108
-
-o, --outfile <outfile> Where to write the changelog (Defaults to stdout when omitted)
109
-
-r, --repository <repo> Repository used for generating commit and issue links
110
-
(without the .git, e.g. https://github.com/thoughtram/clog)
111
-
-l, --link-style <style> The style of repository link to generate
112
-
(Defaults to github) [values: Github Gitlab Stash]
113
-
-s, --subtitle <subtitle> e.g. "Crazy Release Title"
114
-
-t, --to <to> e.g. 8057684 (Defaults to HEAD when omitted)
115
-
--setversion <ver> e.g. 1.0.1
116
-
-w, --work-tree <workdir> Local working tree of the git project
117
-
(defaults to current dir)*
118
-
119
-
* If your .git directory is a child of your project directory (most common, such as
120
-
/myproject/.git) AND not in the current working directory (i.e you need to use --work-tree or
121
-
--git-dir) you only need to specify either the --work-tree (i.e. /myproject) OR --git-dir (i.e.
122
-
/myproject/.git), you don't need to use both.
123
-
124
-
** If using the --config to specify a clog configuration TOML file NOT in the current working
125
-
directory (meaning you need to use --work-tree or --git-dir) AND the TOML file is inside your
126
-
project directory (i.e. /myproject/.clog.toml) you do not need to use --work-tree or --git-dir.
127
-
```
128
-
129
-
#### Try it!
25
+
See the [documentation](http://clog-tool.github.io/clog-lib/) for information on using `clog` in your applications.
130
26
131
27
In order to see it in action, you'll need a repository that already has some of those specially crafted commit messages in it's history. For this, we'll use the `clog` repository itself.
132
28
133
-
1. Clone the repo `git clone https://github.com/thoughtram/clog &&cd clog`
134
-
135
-
2. Ensure you already `clog` binary from any of the steps above
136
-
137
-
4. There are many, many ways to run `clog`. Note, in these examples we will be typing the same options over and over again, intimes like that we could a [clog TOML configuration file](https://github.com/thoughtram/clog#default-options) to specify those options that don't normally change. Also note, all these CLI options have short versions as well, we're using the long version because they're easier to understand.
138
-
a. Let's start by picking up only new commits since our last release (this may not be a lot...or none)
139
-
b. Run `clog -r https://github.com/thoughtram/clog --outfile only_new.md`
140
-
c. By default, `clog` outputs to `stdout` unless you have a file set inside a TOML configuration file. (Note, we could have used the shell `>` operator instead of `--outfile`)
141
-
d. Anything options you set via the CLI will override anything you set the configuration file.
142
-
e. Let's now tell `clog` where it can find our old changelog, and prepend any new commits to that old data
143
-
f. Run `clog -r https://github.com/thoughtram/clog --infile changelog.md --outfile new_combined.md`
144
-
g. Finally, let's assume like most projects we just want to use one file, and prepend all new data to our old changelog (most useful)
145
-
h. First make a backup of the `changelog.md` so you can compare it later `cp changelog.md changelog.md.bak`
146
-
i. Run `clog -r https://github.com/thoughtram/clog --changelog changelog.md`
147
-
j. Try viewing any of the `only_new.md`, `new_combined.md`, `changelog.md.bak`, or `changelog.md`in your favorite markdown viewer to compare them.
148
-
149
-
### As a Library
150
-
151
-
See the documentation forinformation on using `clog`in your applications.
152
-
153
-
#### Try it!
154
-
155
-
In order to see it in action, you'll need a repository that already has some of those specially crafted commit messages in it's history. For this, we'll use the `clog` repository itself.
156
-
157
-
1. Clone the `clog` repository (we will clone to our home directory to make things simple, feel free to change it)
29
+
1. Clone the `clog-lib` repository (we will clone to our home directory to make things simple, feel free to change it)
# The preferred way to set a constant changelog. This file will be read for old changelog
219
-
# data, then prepended to for new changelog data. It's the equivilant to setting
91
+
# data, then prepended to for new changelog data. It's the equivilant to setting
220
92
# both infile and outfile to the same file.
221
93
#
222
94
# Do not use with outfile or infile fields!
@@ -240,7 +112,7 @@ outfile = "MyChangelog.md"
240
112
# from one file and append that data to the clog output in another
241
113
infile = "My_old_changelog.md"
242
114
243
-
# This sets the output format. There are two options "json" or "markdown" and
115
+
# This sets the output format. There are two options "json" or "markdown" and
244
116
# defaults to "markdown" when omitted
245
117
output-format = "json"
246
118
@@ -249,10 +121,6 @@ output-format = "json"
249
121
from-latest-tag = true
250
122
```
251
123
252
-
Now you can update your `MyChangelog.md` with `clog --patch` (assuming you want to update from the latest tag version, and increment your patch version by 1).
253
-
254
-
*Note:* Any options you specify at the command line will override options setin your `.clog.toml`
255
-
256
124
### Custom Sections
257
125
258
126
By default, `clog` will display three sections in your changelog, `Features`, `Performance`, and `Bug Fixes`. You can add additional sections by using a `.clog.toml` file. To add more sections, simply add a `[sections]` table, along with the section name and aliases you'd like to use in your commit messages:
0 commit comments