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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
// Until regex_macros compiles with nightly, these should be commented out // // #![cfg_attr(feature = "unstable", feature(plugin))] // #![cfg_attr(feature = "unstable", plugin(regex_macros))] // DOCS //! clog //! ==== //! //! [](https://gitter.im/thoughtram/clog?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) //! //! [](https://travis-ci.org/thoughtram/clog) //! //! A [conventional][convention] changelog for the rest of us //! //! [convention]: https://github.com/ajoslin/conventional-changelog/blob/a5505865ff3dd710cf757f50530e73ef0ca641da/conventions/angular.md //! //! ### About //! //! `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. //! //! 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. //! //! *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`, via the command line or a library in your applicaitons. //! //! #### Command Line //! //! ```sh //! USAGE: //! clog [FLAGS] [OPTIONS] //! //! FLAGS: //! -c, --config The Clog Configuration TOML file to use (Defaults to '.clog.toml')** //! -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: //! -f, --from <from> e.g. 12a8546 //! -g, --git-dir <gitdir> Local .git directory (defaults to current dir + '.git')* //! -o, --outfile <outfile> Where to write the changelog (Defaults to 'changelog.md') //! -r, --repository <repo> Repo used for link generation (without the .git, e.g. https://github.com/thoughtram/clog) //! -l, --link-style <style> The style of repository link to generate (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! //! //! 1. Clone the repo `git clone https://github.com/thoughtram/clog && cd clog` //! //! 2. Build clog `cargo build --release` //! //! 3. Delete the old changelog file `rm changelog.md` //! //! 3. Run clog `./target/release/clog -r https://github.com/thoughtram/clog --setversion 0.1.0 --subtitle crazy-dog --from 6d8183f` //! //! #### As a Library //! //! See the documentation for information on using `clog` in your applications. //! //! ##### Try it! //! //! 1. Clone the `clog` repo so that you have something to search through (Because `clog` uses //! specially formatted commit messages) //! ``` //! $ git clone https://github.com/thoughtram/clog ~/clog //! ``` //! //! 2. Add `clog` as a dependency in your `Cargo.toml` //! //! ```toml //! [dependencies] //! clog = "*" //! ``` //! //! 3. Use the following in your `src/main.rs` //! //! ```rust //! extern crate clog; //! //! use clog::Clog; //! //! fn main() { //! // Create the struct //! let mut clog = Clog::with_dir("~/clog").unwrap_or_else(|e| { //! println!("{}",e); //! std::process::exit(1); //! }); //! //! // Set some options //! clog.repository("https://github.com/thoughtram/clog") //! .subtitle("Crazy Dog") //! .from("6d8183f") //! .version("0.1.0"); //! //! // Write the changelog to the current working directory //! // //! // Alternatively we could have used .write_changelog_to("/somedir/some_file.md") //! clog.write_changelog(); //! } //! ``` //! //! 4. Compile and run `$ cargo build --release && ./target/release/bin_name //! 5. View the output in your favorite markdown viewer! `$ vim changelog.md` //! //! ### 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. //! //! ```toml //! [clog] //! repository = "https://github.com/thoughtram/clog" //! subtitle = "my awesome title" //! //! # specify the style of commit links to generate, defaults to "github" if omitted //! link-style = "github" //! //! # sets the changelog output file, defaults to "changelog.md" if omitted //! outfile = "MyChangelog.md" //! //! # 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 two sections in your changelog, `Features` 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: //! //! ```toml //! [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"]` //! //! ## LICENSE //! //! clog is licensed under the MIT Open Source license. For more information, see the LICENSE file in this repository. extern crate regex; extern crate semver; extern crate toml; #[macro_use] extern crate clap; extern crate time; #[macro_use] mod macros; pub mod git; mod log_writer; mod sectionmap; mod clog; pub use clog::{Clog, LinkStyle}; pub use log_writer::LogWriter; pub use sectionmap::SectionMap; // The default config file const CLOG_CONFIG_FILE: &'static str = ".clog.toml";