-
Notifications
You must be signed in to change notification settings - Fork 0
3 Options
There are quite a lot of options which can be configured to fit the generated changelog to your needs.
Some of them can be set directly because they're public properties, but others need to be set by using methods.
The below options can be set by invoking method
GitChangelog::setOptions($name, $value).
| Name | Default Value | Description |
|---|---|---|
| logHeader | 'Changelog' | First line of the generated changelog. |
| headTagName | 'Upcoming changes' | Name of the HEAD revision (Implies unreleased commits). |
| headTagDate | 'Undetermined' | Date of the HEAD revision (Implies date of next release). |
| noChangesMessage | 'No changes.' | Message to show when there are no commit titles to list for a tag. |
| addHashes | true | True includes commit hashes to the listed titles. |
| includeMergeCommits | false | True includes merge commits in the title lists. |
| tagOrderBy | 'creatordate' | Specify on which field the fetched tags have to be ordered. See the Git manual for valid values. |
| tagOrder | 'desc' | Set to 'asc' or 'desc' (case insensitive) to sort the tags in resp. ascending/descending order. Any other value defaults to 'desc'. |
| titleOrder | 'asc' | Set to 'asc' or 'desc' (case insensitive) to sort the titles in resp. ascending/descending order. Any other value leaves the order untouched. |
These options can be set individually by passing the name and corresponding value as parameters to the method.
Alternatively, multiple options can be set at once, by passing an array.
To define the range of tags to include in the changelog, two methods are available:
Both of them expect the same arguments: A tag name that must exist in the repository!
When omitting the argument or setting it to null, the from Tag is interpreted as the oldest tag while the to Tag
is interpreted as the HEAD revision[^2].
[^2]: Although the HEAD revision isn't really a tag, it represents upcoming changes to be listed in your changelog.
Labels are considered to be the first word of a commit title.
E.g. commit 7d5e45a: Fix issue #54 where the word Fix represents a label.
If you set labels, only commit titles which start with any of these labels are included.
Note: Labels are case-sensitive!
Labels can be set by invoking the method
GitChangeLog::setLabels(...$labels).
This method will replace all labels that where set before.
Each argument you pass represents a label to be set.
E.g. $changelog->setLabels('Fix', 'Add') makes the renderer only list commits which title starts with those words.
You can do the same by passing an array of labels as an argument if you use the splat operator.
E.g. $changelog->setLabels(...['Fix', 'Add'])
If you've set a bunch of labels before, and you want to add labels, you can invoke the method
GitChangeLog::addLabel(...$labels).
Each argument you pass represents a label to be added.
Alternatively, you can pass an array of labels as an argument if you use the splat operator.
If you've set a bunch of labels before, and you want to remove any of these labels, you can invoke the method
GitChangeLog::removeLabel(...$labels).
Each argument you pass represents a label to be removed.
Alternatively, you can pass an array of labels as an argument if you use the splat operator.
Method GitChangelog::setBaseContent($content)
lets you define a base content for the changelog.
If the value of the parameter resolves to a valid filepath, the content of this file is used as content.
Otherwise, the argument's value is used as content.
This content can be appended to the generated changelog.
The library includes several renderers to generate a changelog.
These renderers introduce their own options for customizing their output.
Public property MarkDown::$titleLength defines the maximum number of a title's characters in the Markdown changelog.
Titles exceeding this length (because of conversion) are word-wrapped.
The default value of this property is 80.
Applies to:
- Markdown Renderer
Tags and commit titles of the repository are formatted before they're added to the changelog.
The formats can be defined with method setFormat($type, $format)
of the renderer.
A format can be set for the following identifiers:
- Tag.
- Title.
Applies to:
- Markdown Renderer
- Html Renderer
Patterns and Urls are used to search in and convert commit titles, so they include links to the webinterface of a
provider's repository.
E.g., The issue-tracker of GitHub.
A pattern can be set for the following identifiers:
- Issue.
- Merge request.
The commit titles are searched for these patterns.
If found, they're converted into links[^1].
Patterns can be set with method setPattern($type, $pattern)
of the renderer.
[^1]: An url has to be defined to convert the pattern into a link.
Applies to:
- Markdown Renderer
- Html Renderer
If set, hashes and patterns (see above) found in a commit title, are converted into links.
The urls can be set with method setUrl($type, $url)
of the renderer.
An url can be set for the following identifiers:
- Commit (hash).
- Issue.
- Merge request.