Beatriz Vieira
parent
7871515ac0
commit
2c741062f7
1 changed files with 115 additions and 10 deletions
125
README.md
125
README.md
|
|
@ -1,6 +1,6 @@
|
|||
<p align="center">
|
||||
<h1 align="center">sv4git</h1>
|
||||
<p align="center">semantic version for git</p>
|
||||
<p align="center">A command line tool (CLI) to validate commit messages, bump version, create tags and generate changelogs!</p>
|
||||
<p align="center">
|
||||
<a href="https://github.com/bvieira/sv4git/releases/latest"><img alt="Release" src="https://img.shields.io/github/release/bvieira/sv4git.svg?style=for-the-badge"></a>
|
||||
<a href="https://pkg.go.dev/github.com/bvieira/sv4git/v2"><img alt="Go Reference" src="https://img.shields.io/badge/-Reference-blue?style=for-the-badge&logo=go&labelColor=gray"></a>
|
||||
|
|
@ -26,11 +26,17 @@
|
|||
If you want to install from source using `go install`, just run:
|
||||
|
||||
```bash
|
||||
# keep in mind that with this, it will compile from source and won't show the version on cli -h.
|
||||
go install github.com/bvieira/sv4git/v2/cmd/git-sv@latest
|
||||
|
||||
# if you want to add the version on the binary, run this command instead.
|
||||
SV4GIT_VERSION=$(go list -f '{{ .Version }}' -m github.com/bvieira/sv4git/v2@latest | sed 's/v//') && go install --ldflags "-X main.Version=$SV4GIT_VERSION" github.com/bvieira/sv4git/v2/cmd/git-sv@v$SV4GIT_VERSION
|
||||
```
|
||||
|
||||
### Config
|
||||
|
||||
#### YAML
|
||||
|
||||
There are 3 config levels when using sv4git: [default](#default), [user](#user), [repository](#repository). All of them are merged considering the follow priority: **repository > user > default**.
|
||||
|
||||
To see the current config, run:
|
||||
|
|
@ -39,9 +45,9 @@ To see the current config, run:
|
|||
git sv cfg show
|
||||
```
|
||||
|
||||
#### Configuration Types
|
||||
##### Configuration Types
|
||||
|
||||
##### Default
|
||||
###### Default
|
||||
|
||||
To check the default configuration, run:
|
||||
|
||||
|
|
@ -49,7 +55,7 @@ To check the default configuration, run:
|
|||
git sv cfg default
|
||||
```
|
||||
|
||||
##### User
|
||||
###### User
|
||||
|
||||
For user config, it is necessary to define the `SV4GIT_HOME` environment variable, eg.:
|
||||
|
||||
|
|
@ -64,14 +70,14 @@ And create a `config.yml` file inside it, eg.:
|
|||
└── config.yml
|
||||
```
|
||||
|
||||
##### Repository
|
||||
###### Repository
|
||||
|
||||
Create a `.sv4git.yml` file on the root of your repository, eg.: [.sv4git.yml](.sv4git.yml).
|
||||
|
||||
#### Configuration format
|
||||
##### Configuration format
|
||||
|
||||
```yml
|
||||
version: "1.0" #config version
|
||||
version: "1.1" #config version
|
||||
|
||||
versioning: # versioning bump
|
||||
update-major: [] # Commit types used to bump major.
|
||||
|
|
@ -85,14 +91,24 @@ tag:
|
|||
pattern: '%d.%d.%d' # Pattern used to create git tag.
|
||||
|
||||
release-notes:
|
||||
# Headers names for release notes markdown. To disable a section just remove the header line.
|
||||
# It's possible to add other commit types, the release note will be created respecting the following order:
|
||||
# feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change
|
||||
# Deprecated!!! please use 'sections' instead! Headers names for release notes markdown. To disable a section
|
||||
# just remove the header line. It's possible to add other commit types, the release note will be created
|
||||
# respecting the following order: feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change.
|
||||
headers:
|
||||
breaking-change: Breaking Changes
|
||||
feat: Features
|
||||
fix: Bug Fixes
|
||||
|
||||
sections: # Array with each section of release note. Check template section for more information.
|
||||
- name: Features # Name used on section name.
|
||||
section-type: commits # Type of the section, supported types: commits, breaking-changes.
|
||||
commit-types: [feat] # Commit types for commit section-type, one commit type cannot be in more than one section.
|
||||
- name: Bug Fixes
|
||||
section-type: commits
|
||||
commit-types: [fix]
|
||||
- name: Breaking Changes
|
||||
section-type: breaking-changes
|
||||
|
||||
branches: # Git branches config.
|
||||
prefix: ([a-z]+\/)? # Prefix used on branch name, it should be a regex group.
|
||||
suffix: (-.*)? # Suffix used on branch name, it should be a regex group.
|
||||
|
|
@ -116,6 +132,95 @@ commit-message:
|
|||
regex: '[A-Z]+-[0-9]+' # Regex for issue id.
|
||||
```
|
||||
|
||||
#### Templates
|
||||
|
||||
**sv4git** uses go templates to format the output for `release-notes` and `changelog`, to see how the default template is configured check [template directory](cmd/git-sv/resources/templates). On v2.7.0+, its possible to overwrite the default configuration by adding `.sv4git/templates` on your repository. The cli expects that at least 2 files exists on your directory: `changelog-md.tpl` and `releasenotes-md.tpl`.
|
||||
|
||||
```bash
|
||||
.sv4git
|
||||
└── templates
|
||||
├── changelog-md.tpl
|
||||
└── releasenotes-md.tpl
|
||||
```
|
||||
|
||||
Everything inside `.sv4git/templates` will be loaded, so it's possible to add more files to be used as needed.
|
||||
|
||||
##### Variables
|
||||
|
||||
To execute the template the `releasenotes-md.tpl` will receive a single ReleaseNote and `changelog-md.tpl` will receive a list of **ReleaseNote** as variables.
|
||||
|
||||
Each **ReleaseNoteSection** will be configured according with `release-notes.section` from config file. The order for each section will be maintained and the SectionType is defined according with `section-type` attribute as described on the table below.
|
||||
|
||||
| section-type | ReleaseNoteSection |
|
||||
| -- | -- |
|
||||
| commits | ReleaseNoteCommitsSection |
|
||||
| breaking-changes | ReleaseNoteBreakingChangeSection |
|
||||
|
||||
> warning: currently only `commits` and `breaking-changes` are supported as `section-types`, using a different value for this field will make the section to be removed from the template variables.
|
||||
|
||||
Check below the variables available:
|
||||
|
||||
```go
|
||||
ReleaseNote
|
||||
Release string // If has a version, it will be used, if not use tag instead.
|
||||
Tag string // Current tag, if available.
|
||||
Version *Version // Version from tag or next version according with semver.
|
||||
Date time.Time
|
||||
Sections []ReleaseNoteSection // ReleaseNoteCommitsSection or ReleaseNoteBreakingChangeSection
|
||||
AuthorNames []string // Author names recovered from commit message (user.name from git)
|
||||
|
||||
Version
|
||||
Major int
|
||||
Minor int
|
||||
Patch int
|
||||
Prerelease string
|
||||
Metadata string
|
||||
Original string
|
||||
|
||||
ReleaseNoteCommitsSection (SectionType == commits)
|
||||
SectionType string
|
||||
SectionName string
|
||||
Types []string
|
||||
Items []GitCommitLog
|
||||
HasMultipleTypes bool
|
||||
|
||||
ReleaseNoteBreakingChangeSection (SectionType == breaking-changes)
|
||||
SectionType string
|
||||
SectionName string
|
||||
Messages []string
|
||||
|
||||
GitCommitLog
|
||||
Date string
|
||||
Timestamp int
|
||||
AuthorName string
|
||||
Hash string
|
||||
Message CommitMessage
|
||||
|
||||
CommitMessage
|
||||
Type string
|
||||
Scope string
|
||||
Description string
|
||||
Body string
|
||||
IsBreakingChange bool
|
||||
Metadata map[string]string
|
||||
```
|
||||
|
||||
##### Functions
|
||||
|
||||
Beside the [go template functions](https://pkg.go.dev/text/template#hdr-Functions), the folowing functions are availiable to use in the templates. Check [formatter_functions.go](sv/formatter_functions.go) to see the function implementation.
|
||||
|
||||
###### timefmt
|
||||
|
||||
**Usage:** timefmt time "2006-01-02"
|
||||
|
||||
Receive a time.Time and a layout string and returns a textual representation of the time according with the layout provided. Check <https://pkg.go.dev/time#Time.Format> for more information.
|
||||
|
||||
###### getsection
|
||||
|
||||
**Usage:** getsection sections "Features"
|
||||
|
||||
Receive a list of ReleaseNoteSection and a Section name and returns a section with the provided name. If no section is found, it will return `nil`.
|
||||
|
||||
### Running
|
||||
|
||||
Run `git-sv` to get the list of available parameters:
|
||||
|
|
|
|||
Loading…
Reference in a new issue