diff --git a/README.md b/README.md index cae1622..3b67426 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

sv4git

-

semantic version for git

+

A command line tool (CLI) to validate commit messages, bump version, create tags and generate changelogs!

Release Go Reference @@ -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,13 +91,23 @@ 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. @@ -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 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: