Automatically generate a release-note document based on git commit messages.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Spread the Word

Automatically generate a release-note document based on git commit messages

Build Status Build Status codecov Known Vulnerabilities Average time to resolve an issue Percentage of issues still open


  • Multiple projects are supported, which means git messages from multiple repositories can be merged to produce a unified release document
  • Multiple output formats are supported, e.g. LaTeX
  • Integrates with Wrike and GitLab to fetch developement task titles
  • Integrates with Google Translate to automatically translate messages to English
  • Caches Google Translate results on your local disk (~/.spreadtheword) so that Google API could incur less fee and it saves your money

Commit Message Conventions

  • {#1} or #1 means issue #1 of Gitlab. Eg. {#63} add backend code for fields or fix #23;
  • {prj#1} or prj#1 means issue #1 of Gitlab project prj. Eg. {UI#1} add code for forms or fix UI#23;
  • {W1} menas Wrike task XXX as in Wrike's permalink Eg. {W4123780} fix config files.


gem install spreadtheword


spreadtheword [PROJECT 1] [PROJECT 2]...[PROJECT N] [OPTION 1] [OPTION 2]...[OPTION N]
      --author=STRING              Specifies the author of the output document. Default: of git config
      --console                    If present, start the console after spreadtheword initializes.
                                  Specifies a Google Translate API access key and translate commit messages that contain non-ASCII characters to English.
  -h, --help                       Prints this help and exit
      --gitlab-endpoint=URL        Specifies GitLab API endpoint URL.
      --gitlab-token=STRING        Specifies the OAuth access token of your GitLab.
      --quiet                      If present, spreadtheword would not output anything to stderr.
      --since=TAG/COMMIT-SHA1      Specifies the begining from which the git commits will be fetched. Default: the first commit
      --title=STRING               Specifies the title of the output document. Default: "Relase Notes"
      --until=TAG/COMMIT-SHA1      Specifies the end to which the git commits will be fetched. Default: master
  -v, --version                    Prints the version of spreadtheword and exit
      --wrike-token=STRING         Specifies the access token of your Wrike API app.


  • If no projects were provided, the current directory would be used as the sole project directory;
  • If multiple projects were provided, the git commit messages of those projects would be merged;
  • If no options were specified, their default (see below) will be used.


spreadtheword                                     \
  /projects/X                                     \
  /projects/Y                                     \
  --since=v1.5                                    \
  --until=origin/releasing                        \
  --title="Your Project v1.6 Release Notes"       \
  --author="Your Company, Inc."                   \
  --google-translate-key="XXX"                    \
  --gitlab-endpoint=""  \
  --gitlab-token="XXX"                            \
  --wrike-token="XXX"                             \
  > v1.6.tex

Hint: you might need to set environment variable LANG=en_US.UTF-8 to support wide characters of git log messages.



See Also