1649177061

# Clog Cli: Generate Beautiful Changelogs From Your Git Commit History

## clog-cli

A conventional changelog for the rest of us

clog creates a changelog automatically from your local git metadata. See the clogs changelog.md for an example.

The way this works, is every time you make a commit, you ensure your commit subject line follows the conventional 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.

NOTE: clog also supports empty components by making commit messages such as alias: message or alias(): message (i.e. without the component)

## Usage

There are two ways to use clog, as a binary via the command line or as a library in your applications via clog-lib.

### Binary (Command Line)

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.

#### cargo install

If you want to both compile and install clog using cargo you can simply run

cargo install clog-cli


#### Compiling

Follow these instructions to compile clog, then skip down to Installation.

1. Ensure you have current version of cargo and Rust installed
2. Clone the project $git clone https://github.com/clog-tool/clog-cli && cd clog-cli 3. Build the project $ cargo build --release
4. Once complete, the binary will be located at target/release/clog

#### Using a Precompiled Binary

Currently there are no precompiled binaries available.

Note: The Mac distribution is available on npm via clog-cli.

#### Installation

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.

Arch Linux

You can use clog-bin from the AUR, or follow the instructions for Linux / OS X

Linux / OS X

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 Option 1 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

Option 2 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.

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)

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


Windows

On Windows 7/8 you can add directory to the PATH variable by opening a command line as an administrator and running

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


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).

#### Using clog from the Command Line

clog works by reading your git metadata and specially crafted commit messages and subjects to create a changelog. clog has the following options availble.

USAGE:
clog [FLAGS] [OPTIONS]

FLAGS:
-F, --from-latest-tag    use latest tag as start (instead of --from)
-h, --help               Prints help information
-M, --major              Increment major version by one (Sets minor and patch to 0)
-m, --minor              Increment minor version by one (Sets patch to 0)
-p, --patch              Increment patch version by one
-V, --version            Prints version information

OPTIONS:
-C, --changelog <changelog>    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 conjuction with either)
-c, --config <config>          The Clog Configuration TOML file to use (Defaults to
'.clog.toml')**
-T, --format <format>          The output format, defaults to markdown
(valid values: markdown, json)
-f, --from <from>              e.g. 12a8546
-g, --git-dir <gitdir>         Local .git directory (defaults to current dir + '.git')*
-i, --infile <infile>          A changelog to append to, but *NOT* write to (Useful in
conjunction with --outfile)
-o, --outfile <outfile>        Where to write the changelog (Defaults to stdout when omitted)
-r, --repository <repo>        Repository used for generating commit and issue links
(without the .git, e.g. https://github.com/clog-tool/clog-cli)
(Defaults to github) [values: Github Gitlab Stash]
-s, --subtitle <subtitle>      e.g. "Crazy Release Title"
-t, --to <to>                  e.g. 8057684 (Defaults to HEAD when omitted)
--setversion <ver>         e.g. 1.0.1
-w, --work-tree <workdir>      Local working tree of the git project
(defaults to current dir)*

* 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.


#### Try it!

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.

Clone the repo git clone https://github.com/clog-tool/clog-cli && cd clog-cli

Ensure you already clog binary from any of the steps above

There are many, many ways to run clog. Note, in these examples we will be typing the same options over and over again, in times like that we could a clog TOML configuration file 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.

Let's start by picking up only new commits since our last release (this may not be a lot...or none)

Run clog -r https://github.com/clog-tool/clog-cli --outfile only_new.md

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)

Anything options you set via the CLI will override anything you set the configuration file.

Let's now tell clog where it can find our old changelog, and prepend any new commits to that old data

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

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)

First make a backup of the changelog.md so you can compare it later cp changelog.md changelog.md.bak

Run clog -r https://github.com/clog-tool/clog-cli --changelog changelog.md

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.

### As a Library

See the documentation or clog-lib for information on using clog in your applications. You can also see the clog crates.io page.

### Default Options

clog can also be configured using a default configuration file so that you don't have to specify all the options each time you want to update your changelog. To do this add a .clog.toml file to your repository.

[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

# 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 equivilant 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


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).

Note: Any options you specify at the command line will override options set in your .clog.toml

### Custom Sections

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:

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


Now if you make a commit message such as mysec(Component): some message or ms(Component): some message there will be a new "MySection" section along side the "Features" and "Bug Fixes" areas.

NOTE: Sections with spaces are suppported, such as "My Special Section" = ["ms", "mysec"]

## Companion Projects

• Commitizen - A command line tool that helps you writing better commit messages.

Author: clog-tool
Source Code: https://github.com/clog-tool/clog-cli

1661525400

## Generate Changelog

Generate a changelog from git commits. This is meant to be used so that for every patch, minor, or major version, you update the changelog prior to running npm version so that the git tag contains the commit that updated both the changelog and version.

## Installation

You can either install it as a dev dependency to be referenced in your npm scripts, or you can install this module globally to be used for all of your repos on your local machine.

$npm i generate-changelog -D # install it as a dev dependency # OR$ npm i generate-changelog -g # install it globally


## Usage

To use this module, your commit messages have to be in this format:

type(category): description [flags]


Where type is one of the following:

• breaking
• build
• ci
• chore
• docs
• feat
• fix
• other
• perf
• refactor
• revert
• style
• test

Where flags is an optional comma-separated list of one or more of the following (must be surrounded in square brackets):

• breaking: alters type to be a breaking change

And category can be anything of your choice. If you use a type not found in the list (but it still follows the same format of the message), it'll be grouped under other.

### CLI

You can run this module as a CLI app that prepends the new logs to a file (recommended):

$changelog -h Usage: generate [options] Generate a changelog from git commits. Options: -h, --help output usage information -V, --version output the version number -p, --patch create a patch changelog -m, --minor create a minor changelog -M, --major create a major changelog -t, --tag <range> generate from specific tag or range (e.g. v1.2.3 or v1.2.3..v1.2.4) -x, --exclude <types> exclude selected commit types (comma separated) -f, --file [file] file to write to, defaults to ./CHANGELOG.md, use - for stdout -u, --repo-url [url] specify the repo URL for commit links, defaults to checking the package.json -a, --allow-unknown allow unknown commit types  It's possible to create a ./CHANGELOG.md file for a specific commit range: generate-changelog 420c945...2a83752  Git tags are supported too: generate-changelog release/3.1.2822...release/3.1.2858  ### Code You can write a script that calls the generate function and does whatever you want with the new logs: var Changelog = require('generate-changelog'); var Fs = require('fs'); return Changelog.generate({ patch: true, repoUrl: 'https://github.com/lob/generate-changelog' }) .then(function (changelog) { Fs.writeFileSync('./CHANGELOG.md', changelog); });  ### Recommended The way that I would recommend using this module would be the way it's being used in this module: as npm scripts. You should install it as a dev dependency and then add the following to the scripts object in your package.json: "release:major": "changelog -M && git add CHANGELOG.md && git commit -m 'updated CHANGELOG.md' && npm version major && git push origin && git push origin --tags", "release:minor": "changelog -m && git add CHANGELOG.md && git commit -m 'updated CHANGELOG.md' && npm version minor && git push origin && git push origin --tags", "release:patch": "changelog -p && git add CHANGELOG.md && git commit -m 'updated CHANGELOG.md' && npm version patch && git push origin && git push origin --tags",  ### GitHub Actions You can run this module in a GitHub Actions workflow using the generate-changelog-action Action. ## Testing To run the test suite, just clone the repository and run the following: $ npm i
\$ npm test


## Contributing

To contribute, please see the CONTRIBUTING.md file.

Author: lob
Source Code: https://github.com/lob/generate-changelog

1604109000

## Best Practices for Using Git

Git has become ubiquitous as the preferred version control system (VCS) used by developers. Using Git adds immense value especially for engineering teams where several developers work together since it becomes critical to have a system of integrating everyone’s code reliably.

But with every powerful tool, especially one that involves collaboration with others, it is better to establish conventions to follow lest we shoot ourselves in the foot.

At DeepSource, we’ve put together some guiding principles for our own team that make working with a VCS like Git easier. Here are 5 simple rules you can follow:

### 1. Make Clean, Single-Purpose Commits

Oftentimes programmers working on something get sidetracked into doing too many things when working on one particular thing — like when you are trying to fix one particular bug and you spot another one, and you can’t resist the urge to fix that as well. And another one. Soon, it snowballs and you end up with so many changes all going together in one commit.

This is problematic, and it is better to keep commits as small and focused as possible for many reasons, including:

• It makes it easier for other people in the team to look at your change, making code reviews more efficient.
• If the commit has to be rolled back completely, it’s far easier to do so.
• It’s straightforward to track these changes with your ticketing system.

Additionally, it helps you mentally parse changes you’ve made using git log.

#open source #git #git basics #git tools #git best practices #git tutorials #git commit

1617875220

## Git Commands You Can Use To Dig Through Your Git History

In this short article, we’ll be exploring some quick  git commands that can help us in digging through our repositories’ history of commits. We’ll look at

1. git log
2. git shortlog
3. git show
4. git rev-list

#git #git-log #git-commands #git-history #aws

1591518708

## Git Rebase Tutorial and Comparison with Git Merge

There are many ways of working with git, if they’re clean, and don’t do damages, probably most of them are good.

But same as space vs. tab, in the IT world is a war between fans of rebase, and fans of git merge.

There are tons of arguments about:

-Which way is better?

-Which one is cleaner?

-Which is more comfortable?

-Which one gives a cleaner git graph?

-Why it’s important, and which one is more dangerous?

#quick help #tutorials #git #git branch #git commit #git interactive rebase

1597916460

## 7 Best Practices in GIT for Your Code Quality

There is no doubt that Git plays a significant role in software development. It allows developers to work on the same code base at the same time. Still, developers struggle for code quality. Why? They fail to follow git best practices. In this post, I will explain seven core best practices of Git and a Bonus Section.

## 1. Atomic Commit

Committing something to Git means that you have changed your code and want to save these changes as a new trusted version.

Version control systems will not limit you in how you commit your code.

• You can commit 1000 changes in one single commit.
• Commit all the dll and other dependencies
• Or you can check in broken code to your repository.

But is it good? Not quite.

Because you are compromising code quality, and it will take more time to review codeSo overall, team productivity will be reduced. The best practice is to make an atomic commit.

When you do an atomic commit, you’re committing only one change. It might be across multiple files, but it’s one single change.

## 2. Clarity About What You Can (& Can’t) Commit

Many developers make some changes, then commit, then push. And I have seen many repositories with unwanted files like dll, pdf, etc.

You can ask two questions to yourself, before check-in your code into the repository

1. Are you suppose to check-in all these files?
2. Are they part of your source code?

You can simply use the .gitignore file to avoid unwanted files in the repository. If you are working on more then one repo, it’s easy to use a global .gitignore file (without adding or pushing). And .gitignore file adds clarity and helps you to keep your code clean. What you can commit, and it will automatically ignore the unwanted files like autogenerated files like .dll and .class, etc.

#git basics #git command #git ignore #git best practices #git tutorial for beginners #git tutorials