git-changelog(1)

1GIT-CHANGELOG(1)                  Git Extras                  GIT-CHANGELOG(1)
2
3
4

NAME

6       git-changelog - Generate a changelog report
7

SYNOPSIS

9       git-changelog [options] [<file>]
10       git-changelog {-h | --help | ?}
11

DESCRIPTION

13       Generates  a  changelog from git(1) tags (annotated or lightweight) and
14       commit messages. Existing changelog files  with  filenames  that  begin
15       with  Change  or  History  will be identified automatically with a case
16       insensitive match pattern and existing content will be appended to  the
17       new  output  generated--this behavior can be disabled by specifying the
18       prune option (-p|--prune-old). The generated file  will  be  opened  in
19       $EDITOR when set.
20
21       If no tags exist, then all commits are output; if tags exist, then only
22       the most-recent commits are output up to the last identified tag.  This
23       behavior  can be changed by specifying one or both of the range options
24       (-f|--final-tag and -s|--start-tag).
25
26       You could customize the changelog format via some git config options.
27
28       ·   git config changelog.format $format controls  the  format  of  each
29           commit.  It  will be passed as git log --pretty=format:$format. The
30           default value is * %s.
31
32       ·   git config changelog.mergeformat $format is  like  changelog.format
33           but only used when --merges-only is specified. The default value is
34           * %s%n%w(64,4,4)%b.
35
36
37

OPTIONS

39       <file>
40
41       The name of the output file. By default the new file will be History.md
42       unless  an  existing  changelog  is detected in which case the existing
43       file will be updated.
44
45       -a, --all
46
47       Retrieve all commits. Ignores -s|--start-tag/commit and  -f|--final-tag
48       options (if set).
49
50       -l, --list
51
52       Show commits in list format (without titles, dates).
53
54       -t, --tag
55
56       Specify a tag label to use for most-recent (untagged) commits.
57
58       -f, --final-tag
59
60       When specifying a range, the newest tag at which point commit retrieval
61       will end. Commits will be returned from the very first commit until the
62       final tag unless a start tag is also specified.
63
64       -s, --start-tag
65
66       When  specifying a range, the oldest tag to retrieve commits from. Com‐
67       mits will be returned from the start tag to now unless a final  tag  is
68       also specified.
69
70       --start-commit
71
72       Like the --start-tag but specify the oldest commit instead of tag. Note
73       that the specified commit will be contained in the changelog.
74
75       -n, --no-merges
76
77       Filters out merge commits (commits with more than 1 parent) from gener‐
78       ated changelog.
79
80       -m, --merges-only
81
82       Uses only merge commits (commits with more than 1 parent) for generated
83       changelog. It also changes the default format to include the merge com‐
84       mit  messages body, as on github the commits subject line only contains
85       the branch name but no information about the content of the merge.
86
87       -p, --prune-old
88
89       Replace existing  changelog  entirely  with  newly  generated  content,
90       thereby  disabling the default behavior of appending the content of any
91       detected changelog to the end of newly generated content.
92
93       -x, --stdout
94
95       Write output to stdout instead of to a new changelog file.
96
97       -h, --help, ?
98
99       Show a help message with basic usage information.
100

EXAMPLES

102       Updating existing file or creating a new History.md  file  with  pretty
103       formatted output:
104
105              $ git changelog
106
107       Listing commits from the current version:
108
109              $ git changelog --list
110
111       Listing a range of commits from 2.1.0 to now:
112
113              $ git changelog --list --start-tag 2.1.0
114
115       Listing a pretty formatted version of the same:
116
117              $ git changelog --start-tag 2.1.0
118
119       Listing a range of commits from initial commit to 2.1.0:
120
121              $ git changelog --list --final-tag 2.1.0
122
123       Listing a pretty formatted range of commits between 0.5.0 and 1.0.0:
124
125              $ git changelog --start-tag 0.5.0 --final-tag 1.0.0
126
127       Listing a pretty formatted range of commits between 0b97430 and 1.0.0:
128
129              $ git changelog --start-commit 0b97430 --final-tag 1.0.0
130
131       Specifying a file for output:
132
133              $ git changelog ChangeLog.md
134
135       And if an existing Changelog exists, replace its contents entirely:
136
137              $ git changelog --prune-old
138

AUTHOR

140       Written by Mark Eissler <mark@mixtur.com>
141

REPORTING BUGS

143       <https://github.com/tj/git-extras/issues>
144