change-log
Command line generation of a Semantic Versioning based change log.
Please note: the tool intelligence is currently low. Be careful not to
remove sections created by change-log init, especially under the
Unreleased section.
You can see an editable example of this format here.
This project was inspired by Keep a Change Log but the format is different, with a focus on the SemVer versions.
API
Execute without arguments to view a list of command arguments and options
change-log
init
Create a new CHANGELOG.md file. The name is taken from package.json if it exists, and from the folder name if it does not.
change-log init
major
Add an entry under Major in the Unreleased section.
-
The message is echoed to stdout.
change-log major "What was changed"
minor
Add an entry under Minor in the Unreleased section.
-
The message is echoed to stdout.
change-log minor "What was added"
patch
Add an entry under Patch in the Unreleased section.
-
The message is echoed to stdout.
change-log patch "What was fixed"
release
Marks the unreleased section as a release:
- Calculates the SemVer based on the previous release in the change log and on unreleased Major, Minor and Patch entries.
- Adds a new empty unreleased section.
- Writes release version to the console
- Update package.json, npm-shrinkwrap.json and package-lock.json if they exist
change-log release
Pass STDOUT to command
For the major, minor, and patch commands, the message you provided is echoed to STDOUT.
# major
git commit -am "$(change-log major 'message')"
# minor
git commit -am "$(change-log minor 'message')"
# patch
git commit -am "$(change-log patch 'message')"
For the release command, the version, of form v#.#.# is written to stdout.
# release
git commit -am "$(change-log release)"
Git commit options
The following options will cause git commands to be executed when using the major, minor, patch and release commands.
--commit
This option calls git commit -m "message", committing only staged changes.
The CHANGELOG.md file will be automatically staged before committing.
For the release command, package.json will be automatically staged, and
also npm-shrinkwrap.json and package-lock.json if they exist (the version will
have been updated in these files if they exist).
change-log release 'message' --commit
--commit-all
This option calls git commit -am "message", committing all changes, both
staged and unstaged.
change-log release 'message' --commit-all
Options
Default settings can be overridden using a .changelog file in the
current working directory or in your home directory. You can also
specify the same options at command line.
Here are the options that can be provided to override the defaults:
unreleasedUriTemplate
- A string template for a git uri of changes not yet published
- Used during release
startUriTemplate
- A string template for a git uri of changes from the first commit
- Used during init and release
uriTemplate
- A string template for a git uri of changes between releases.
- Used during release
organization
- The group name associated with a git repository
- Used during init and release
name
- The project name associated with a git repository
- The default comes from the repository field of package.json, the name in package.json or the containing directory.
- Used during init and release
Here are the recognized tokens that will be replaced in each string template above:
- ${organization}
- This is the git repository group name
- Taken from the repository field of package.json by default
- ${name}
- The git repository project name
- Taken from repository field of package.json, name in package.json or directory
- ${fromVersion}
- In the case of startUriTemplate, this value will be an empty string
- The version prior to release
- ${toVersion}
- The current release version
These tokens are replaced with a simple find and replace operation, with no evaluation of what is between the braces.
Example .changelog file:
{
"unreleasedUriTemplate": "https://github.com/${organization}/${name}/compare/v${toVersion}...master",
"startUriTemplate": "https://github.com/${organization}/${name}/commits/v${toVersion}",
"uriTemplate": "https://github.com/${organization}/${name}/compare/v${fromVersion}...v${toVersion}",
"organization": "myOrg",
"name": "projectName"
}
Example cli options:
change-log release --unreleasedUriTemplate="https://github.com/${organization}/${name}/compare/v${toVersion}...master"
Example
See the change log for this project for a full working example of the format.
Here is an example of creating a new file, adding changes and cutting a release:
Intialize a new CHANGELOG.md file:
$ change-log init && cat CHANGELOG.md
# change-log Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased] - YYYY-MM-DD
### Major
### Minor
### Patch
[Unreleased]: https://github.com/majgis/change-log/commits/v1.0.0
Add a minor entry:
$ change-log minor "Added a new feature" && cat CHANGELOG.md
# change-log Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased] - YYYY-MM-DD
### Major
### Minor
- Added a new feature
### Patch
[Unreleased]: https://github.com/majgis/change-log/commits/v1.0.0
Add a patch entry:
$ change-log patch "Fixed an issue" && cat CHANGELOG.md
# change-log Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased] - YYYY-MM-DD
### Major
### Minor
- Added a new feature
### Patch
- Fixed an issue
[Unreleased]: https://github.com/majgis/change-log/commits/v1.0.0
Cut a release:
$ change-log release && cat CHANGELOG.md
v1.0.0
# change-log Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased] - YYYY-MM-DD
### Major
### Minor
### Patch
## [v1.0.0] - 2016-11-15
### Minor
- Added a new feature
### Patch
- Fixed an issue
[Unreleased]: https://github.com/majgis/change-log/compare/v1.0.0...master
[v1.0.0]: https://github.com/majgis/change-log/commits/v1.0.0