PHPackages magelan/readmegen - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. magelan/readmegen ActiveLibrary magelan/readmegen ================= Readme file / doc generator. It uses VCS logs as a source of information. It also links commits with Github or Jira issues trackers. 1.2.3(7y ago)0124MITPHP Since Dec 7Pushed 7y agoCompare [ Source](https://github.com/magelanLab/readmegen)[ Packagist](https://packagist.org/packages/magelan/readmegen)[ RSS](/packages/magelan-readmegen/feed)WikiDiscussions master Synced 2mo ago READMEChangelogDependenciesVersions (13)Used By (0) ReadmeGen ========= [](#readmegen) **Notice**: The package currently supports only GIT and the \*.md output files. **Notice 2**: Don't forget to update config file `readmegen.yml` with your parameters. ### Installation [](#installation) #### Global installation (recommended) [](#global-installation-recommended) ``` composer global require magelan/readmegen ``` You can read more about global installation in the [composer docs](https://getcomposer.org/doc/03-cli.md#global). #### Local installation [](#local-installation) ``` composer require magelan/readmegen ``` #### Windows installation [](#windows-installation) Make sure the Windows `PATH` variable contains the path to the composer bin dir: ``` C:\Users\{USER}\AppData\Roaming\Composer\vendor\bin ``` Restart any shell terminal you want to use for changes to take effect. ### Usage [](#usage) This package is intended to be used as an executable script, not a library you would include in your project. Assuming you installed ReadmeGen globally, to update your changelog file, simply run: ``` readmegen --from TAG --to TAG --release RELEASE_NUMBER --break BREAKPOINT ``` For example: ``` readmegen --from 1.12.0 --to 1.13.0 --release 1.13.0 --break #Changelog ``` This tells the script to generate a changelog update named `1.13.0` and that it should scan the log since tag `1.12.0` up to `1.13.0`. No earlier (or latter) commits will be taken into consideration. ReadmeGen will create a `CHANGELOG.md file and inject the generated log *after* the `\#Changelog` line. If you want to generate the changelog from a specific tag (or commit checksum) up to the latest commit (`HEAD`) just omit the `--to` argument: ``` readmegen --from a04cf99 --release 1.13.0 --break #Changelog ``` You can also specify the breakpoint in the `readmegen.yml` config file so the command will be even cleaner: ``` readmegen --from a04cf99 --release 1.13.0 ``` ### Message format [](#message-format) ReadmeGen will search for messages that start with a specific keyword. These keywords tell the script to which group the commit should be appended. The message groups can be overwritten. For example - the default configuration supports four types of commits: Features, Bugfixes, Documentation, Design, Performance, Chore and Refactoring. The commit will be appended to a certain group only if it starts with a specific word. The default config allows two keywords for bugfixes: `bugfix` and `fix`. This means, that for a message to be appended to the Bugfix group it has to start with either `bugfix: blabla` or `Fix: foo bar` (notice the colon `:` sign - it has to be right after the keyword). The keywords are case insensitive. All commits that do not fit into any of the groups will be ignored (we don't want merges and stuff like that in the changelog). ### Grouping commits [](#grouping-commits) Each commit that fits into a group will be grouped (yeah, that sounds silly). Groups will be printed out in the order they appear in the config file, so if you have `Features` and `Bugfixes`, this is the order they will appear in the changelog: ``` Features - feature 1 - feature 2 Bugfixes - fix 1 ``` You can override the groups in your custom config file (details below). ### Link patterns [](#link-patterns) ReadmeGen can link issues to a issue tracker - all numbers starting with `#` or `KEY-` will be linked to a website defined in the config under the `issue_tracker_pattern` key. If a commit message has a string `#1234` or `KEY-1234` in it, it will be converted to a link targeting the issue tracker. ### Local config [](#local-config) The default config holds the definitions of commit groups and the issue link pattern. It also specifies which VCS to use and the type of the output file. You can override these settings (project-wide) by creating a `readmegen.yml` file in the root dir of your project. When ReadmeGen will be run it will check if this file exists and merge the settings accordingly. The default `readmegen.yml` config looks like this: ``` vcs: git format: md issue_tracker_key: /(KEY-[0-9]+)/ issue_tracker_pattern: '[[\1]](http://some.issue.tracker.com/\1)' break: "#Changelog" output_file_name: "CHANGELOG.md" message_groups: Features: - feature - feat Bugfixes: - fix - bugfix Breaking Changes: - break Design: - design Documentation: - docs Refactoring: - refactoring - refactor Performance: - perf Chore : - chore ``` Each of the `message_groups` key is the name of the group that will be put in the changelog. The values inside the group are the keywords the commit must start with (followed by the colon `:` sign) to be appended to that group. `issue_tracker_key= /(KEY-[0-9]+)/` is the key used by your Issues Tracker (i.e. *JIRA*, *Github*, or anything else). The way it works depends on your Issue Tracker service. Here some examples : 1. For *JIRA* : replace `KEY` by **your project key** 2. For *Github* : replace `KEY-` by `#` ### Release number [](#release-number) ReadmeGen requires a release number (`--release`) to be provided. This will be the title of the generated changelog. ### Breakpoint [](#breakpoint) By default the changes will go onto the beginning of the changelog file. You can though specify a "breakpoint" beneath which these changes should be appended. Usually, you'll have some "intro" in you changelog, and the changes listed below. You don't want the script to push the changes on top of the file, but below a certain line. You can specify this line in the `readmegen.yml` config file or using the `--break` argument. For example: ``` readmegen --from 1.12.0 --to 1.13.0 --release 1.3.3 --break #Changelog ``` The script will append the changes *below* the line that contains the `#Changelog` phrase. This should be the only phrase in this line. If you use the CLI argument method (`--break`), the breakpoint **must not contain spaces**. Thus you are encouraged to use the config method - you can use spaces there, as shown in the default config. ReadmeGen will search for the `# Changelog` breakpoint by default. If the breakpoint phrase is not found, the output will go onto the beginning of the changelog file. ### Example commits [](#example-commits) Here are some example commit messages that will be grabbed by ReadmeGen (with the default config): ``` feature: Added some cool stuff (#1234) fix: #4245, regarding client login bug docs: Updated the transaction section of the docs feat: Some more cool stuff ``` Changelog --------- [](#changelog) 1.2.3 ----- [](#123) *(2018-08-20)* #### Bugfixes [](#bugfixes) - Correct wrong local installation package #### Chore [](#chore) - Update dependency ulrichsg/getopt-php from v2 to v3 - Update dependency symfony/yaml from v3 to v4 --- 1.2.0 ----- [](#120) *(2018-07-16)* #### Features [](#features) - Update config file - Add JIRA issue tracker support #### Documentation [](#documentation) - Update Readme & License ### Health Score 30 — LowBetter than 65% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity10 Limited adoption so far Community7 Small or concentrated contributor base Maturity70 Established project with proven stability Bus Factor1 Top contributor holds 89.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~150 days Recently: every ~282 days Total 10 Last Release 2820d ago ### Community --- Top Contributors [![fojuth](https://avatars.githubusercontent.com/u/2622146?v=4)](https://github.com/fojuth "fojuth (80 commits)")[![golovetska](https://avatars.githubusercontent.com/u/2945533?v=4)](https://github.com/golovetska "golovetska (6 commits)")[![reva2work](https://avatars.githubusercontent.com/u/538756?v=4)](https://github.com/reva2work "reva2work (3 commits)") ### Embed Badge ![Health badge](/badges/magelan-readmegen/health.svg) ``` [![Health](https://phpackages.com/badges/magelan-readmegen/health.svg)](https://phpackages.com/packages/magelan-readmegen) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)