mirror of
https://github.com/thegeeklab/git-sv.git
synced 2024-11-21 12:00:40 +00:00
parent
7871515ac0
commit
2c741062f7
125
README.md
125
README.md
@ -1,6 +1,6 @@
|
|||||||
<p align="center">
|
<p align="center">
|
||||||
<h1 align="center">sv4git</h1>
|
<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">
|
<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://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>
|
<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:
|
If you want to install from source using `go install`, just run:
|
||||||
|
|
||||||
```bash
|
```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
|
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
|
### 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**.
|
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:
|
To see the current config, run:
|
||||||
@ -39,9 +45,9 @@ To see the current config, run:
|
|||||||
git sv cfg show
|
git sv cfg show
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Configuration Types
|
##### Configuration Types
|
||||||
|
|
||||||
##### Default
|
###### Default
|
||||||
|
|
||||||
To check the default configuration, run:
|
To check the default configuration, run:
|
||||||
|
|
||||||
@ -49,7 +55,7 @@ To check the default configuration, run:
|
|||||||
git sv cfg default
|
git sv cfg default
|
||||||
```
|
```
|
||||||
|
|
||||||
##### User
|
###### User
|
||||||
|
|
||||||
For user config, it is necessary to define the `SV4GIT_HOME` environment variable, eg.:
|
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
|
└── config.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
##### Repository
|
###### Repository
|
||||||
|
|
||||||
Create a `.sv4git.yml` file on the root of your repository, eg.: [.sv4git.yml](.sv4git.yml).
|
Create a `.sv4git.yml` file on the root of your repository, eg.: [.sv4git.yml](.sv4git.yml).
|
||||||
|
|
||||||
#### Configuration format
|
##### Configuration format
|
||||||
|
|
||||||
```yml
|
```yml
|
||||||
version: "1.0" #config version
|
version: "1.1" #config version
|
||||||
|
|
||||||
versioning: # versioning bump
|
versioning: # versioning bump
|
||||||
update-major: [] # Commit types used to bump major.
|
update-major: [] # Commit types used to bump major.
|
||||||
@ -85,13 +91,23 @@ tag:
|
|||||||
pattern: '%d.%d.%d' # Pattern used to create git tag.
|
pattern: '%d.%d.%d' # Pattern used to create git tag.
|
||||||
|
|
||||||
release-notes:
|
release-notes:
|
||||||
# Headers names for release notes markdown. To disable a section just remove the header line.
|
# Deprecated!!! please use 'sections' instead! Headers names for release notes markdown. To disable a section
|
||||||
# It's possible to add other commit types, the release note will be created respecting the following order:
|
# just remove the header line. It's possible to add other commit types, the release note will be created
|
||||||
# feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change
|
# respecting the following order: feat, fix, refactor, perf, test, build, ci, chore, docs, style, breaking-change.
|
||||||
headers:
|
headers:
|
||||||
breaking-change: Breaking Changes
|
breaking-change: Breaking Changes
|
||||||
feat: Features
|
feat: Features
|
||||||
fix: Bug Fixes
|
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.
|
branches: # Git branches config.
|
||||||
prefix: ([a-z]+\/)? # Prefix used on branch name, it should be a regex group.
|
prefix: ([a-z]+\/)? # Prefix 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.
|
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
|
### Running
|
||||||
|
|
||||||
Run `git-sv` to get the list of available parameters:
|
Run `git-sv` to get the list of available parameters:
|
||||||
|
Loading…
Reference in New Issue
Block a user