git-changelog 0.3.1

A tool to automate project changelog generation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

// Copyright 2017-2018 by Aldrin J D'Souza.
// Licensed under the MIT License <https://opensource.org/licenses/MIT>
//! A generator for categorized change logs.
//!
//! This crate generates change logs (a.k.a release notes) that are typically distributed at project
//! release milestones. Unlike other tools that do the same, this one does not require you to follow
//! any particular git workflow conventions. All it assumes is that you'll pick a few *keywords* (or
//! use the built-in ones) to annotate lines in your commit messages.
//!
//! When you wish to record a user visible change (e.g. new feature, bug fix, breaking change, etc.)
//! you write a normal commit message and annotate some lines in it with your chosen keywords. The
//! annotated lines are used at report generation time to organize changes into *categories* and
//! *scopes*. The organized changes are then rendered as a pretty and accurate change log. Commit
//! messages without tags are quietly ignored and you are free to tag as little or as much as you
//! want.
//!
//! See [README] for details.
//!
//! # Usage
//!
//! Install the executable wrapper as follows:
//!
//! ```bash
//! $ cargo install git-changelog
//! ```
//!
//! Once on `PATH`, the tool works like a normal git sub-command (e.g. `git log`) and takes a
//! [revision range] as input. It looks at all commits in the range and uses the keywords it finds
//! in their messages to generate the report. Simple. 🙂
//!
//! ```bash
//! $ git changelog v0.1.1..v0.2.0
//! ```
//!
//! If you don't provide a revision range, `<last-tag>..HEAD` is used. If no tags are defined, just
//! the last commit is picked.
//!
//! ```bash
//! $ git changelog -d
//! INFO: Reading file '/Users/aldrin/Code/git-changelog/.changelog.yml'
//! INFO: Using revision range 'v0.2.0..HEAD (15 commits)'
//! ...
//! ```
//!
//! Note that using `-d` can you give you some insight into the tool operations. For more complex range
//! selections you can use `git log` arguments as shown below:
//!
//! ```bash
//! $ git changelog -- --author aldrin --reverse --since "1 month ago"
//! ```
//!
//! Note the `--` before you start the `git log` arguments.
//!
//! # Library Usage
//!
//! The crate functionality is also usable as a library as shown below:
//!
//! ```toml
//! [dependencies]
//! git-changelog = "0.3"
//! ```
//!
//! ```rust
//! extern crate changelog;
//! println!("{}", changelog::ChangeLog::new());
//! ```
//!
//! The configuration used in simple example shown above is picked from the repository configuration
//! file (if one is found) or from built-in defaults. Advanced usage can programmatically manage
//! these as follows:
//!
//! ```rust
//! use changelog::{Configuration, Keyword, ChangeLog};
//!
//! // Create a custom configuration
//! let mut config = Configuration::new();
//!
//! // Pick the category or scope keywords that match your project conventions
//! config.conventions.categories.push(Keyword::new("feature", "New Features"));
//! config.conventions.categories.push(Keyword::new("break", "Breaking Changes"));
//!
//! // Pick the range of commits
//! let range = "v0.1.1..v0.2.0";
//!
//! // Generate a changelog for the range with the configuration
//! let changelog = ChangeLog::from_range(range, &config);
//!
//! // Pick output preferences
//! config.output.json = true;
//!
//! // Render
//! assert!(changelog::render(&changelog, &config.output).is_ok());
//! ```
//! [revision range]: https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#double_dot
//! [README]: https://github.com/aldrin/git-changelog/blob/master/README.md

extern crate chrono;
#[macro_use]
extern crate failure;
extern crate handlebars;
#[macro_use]
extern crate log;
#[macro_use]
extern crate nom;
extern crate regex;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;
extern crate serde_yaml;

mod git;
mod input;
mod commit;
mod output;
mod changelog;

pub use git::in_git_repository;
pub use input::Configuration;
pub use input::Conventions;
pub use input::OutputPreferences;
pub use input::Keyword;
pub use input::PostProcessor;
pub use input::TEMPLATE_FILE;
pub use input::CONFIG_FILE;
pub use commit::Commit;
pub use commit::CommitList;
pub use commit::CommitMessage;
pub use changelog::ChangeLog;
pub use changelog::Category;
pub use changelog::Scope;
pub use output::render;

pub type Result<T> = std::result::Result<T, failure::Error>;