From a2aa51f5702b18016c25d943499941323952704d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 19 Nov 2022 15:52:46 +0100 Subject: Adding upstream version 0.18.0. Signed-off-by: Daniel Baumann --- docs/index.md | 118 ++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 91 insertions(+), 27 deletions(-) (limited to 'docs/index.md') diff --git a/docs/index.md b/docs/index.md index 398b4e5..801a16e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,11 +22,11 @@ Great for use as a [commit-msg git hook](#using-gitlint-as-a-commit-msg-hook) or - **Easily integrated**: Gitlint is designed to work [with your own scripts or CI system](#using-gitlint-in-a-ci-environment). - **Sane defaults:** Many of gitlint's validations are based on [well-known](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), -[community](http://addamhardy.com/2013/06/05/good-commit-messages-and-enforcing-them-with-git-hooks.html), +[community](https://addamhardy.com/2013-06-05-good-commit-messages-and-enforcing-them-with-git-hooks), [standards](http://chris.beams.io/posts/git-commit/), others are based on checks that we've found useful throughout the years. - **Easily configurable:** Gitlint has sane defaults, but [you can also easily customize it to your own liking](configuration.md). - - **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules). + - **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules.md). - **User-defined rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules.md). - **Full unicode support:** Lint your Russian, Chinese or Emoji commit messages with ease! - **Production-ready:** Gitlint checks a lot of the boxes you're looking for: actively maintained, high unit test coverage, integration tests, @@ -38,6 +38,10 @@ useful throughout the years. # Pip is recommended to install the latest version pip install gitlint +# Alternative: by default, gitlint is installed with pinned dependencies. +# To install gitlint with looser dependency requirements, only install gitlint-core. +pip install gitlint-core + # Community maintained packages: brew install gitlint # Homebrew (macOS) sudo port install gitlint # Macports (macOS) @@ -81,6 +85,19 @@ $ cat examples/commit-message-2 | gitlint !!! note The returned exit code equals the number of errors found. [Some exit codes are special](index.md#exit-codes). +### Shell completion + +```sh +# Bash: add to ~/.bashrc +eval "$(_GITLINT_COMPLETE=bash_source gitlint)" + +# Zsh: add to ~/.zshrc +eval "$(_GITLINT_COMPLETE=zsh_source gitlint)" + +# Fish: add to ~/.config/fish/completions/foo-bar.fish +eval (env _GITLINT_COMPLETE=fish_source gitlint) +``` + ## Configuration For in-depth documentation of general and rule-specific configuration options, have a look at the [Configuration](configuration.md) and [Rules](rules.md) pages. @@ -93,7 +110,7 @@ Short example `.gitlint` file ([full reference](configuration.md)): # their id or by their full name ignore=body-is-missing,T3 -# Ignore any data send to gitlint via stdin +# Ignore any data sent to gitlint via stdin ignore-stdin=true # Configure title-max-length rule, set title length to 80 (72 = default) @@ -136,7 +153,8 @@ Options: (e.g.: -c T1.line-length=80). Flag can be used multiple times to set multiple config values. --commit TEXT Hash (SHA) of specific commit to lint. - --commits TEXT The range of commits to lint. [default: HEAD] + --commits TEXT The range of commits (refspec or comma-separated + hashes) to lint. [default: HEAD] -e, --extra-path PATH Path to a directory or python module with extra user-defined rules --ignore TEXT Ignore rules (comma-separated by id or name). @@ -145,8 +163,9 @@ Options: --msg-filename FILENAME Path to a file containing a commit-msg. --ignore-stdin Ignore any stdin data. Useful for running in CI server. - --staged Read staged commit meta-info from the local - repository. + --staged Attempt smart guesses about meta info (like + author name, email, branch, changed files, etc) + for staged commits. --fail-without-commits Hard fail when the target commit range is empty. -v, --verbose Verbosity, more v's for more verbose output (e.g.: -v, -vv, -vvv). [default: -vvv] @@ -218,7 +237,7 @@ In case you want to change gitlint's behavior, you should either use a `.gitlint your `.pre-commit-config.yaml` file like so: ```yaml - repo: https://github.com/jorisroovers/gitlint - rev: # Fill in a tag / sha here + rev: # Fill in a tag / sha here (e.g. v0.18.0) hooks: - id: gitlint args: [--contrib=CT1, --msg-filename] @@ -229,6 +248,36 @@ your `.pre-commit-config.yaml` file like so: You need to add `--msg-filename` at the end of your custom `args` list as the gitlint-hook will fail otherwise. +### gitlint and pre-commit in CI +gitlint also supports a `gitlint-ci` pre-commit hook that can be used in CI environments. + +Configure it like so: +```yaml +- repo: https://github.com/jorisroovers/gitlint + rev: # insert ref, e.g. v0.18.0 + hooks: + - id: gitlint # this is the regular commit-msg hook + - id: gitlint-ci # hook for CI environments +``` + +And invoke it in your CI environment like this: + +```sh +pre-commit run --hook-stage manual gitlint-ci +``` + +By default this will only lint the latest commit. +If you want to lint more commits you can modify the `gitlint-ci` hook like so: + +```yaml +- repo: https://github.com/jorisroovers/gitlint + rev: v0.17.0 + hooks: + - id: gitlint + - id: gitlint-ci + args: [--debug, --commits, mybranch] # enable debug mode, lint all commits in mybranch +``` + ## Using gitlint in a CI environment By default, when just running `gitlint` without additional parameters, gitlint lints the last commit in the current working directory. @@ -248,33 +297,48 @@ git log -1 --pretty=%B 62c0519 | gitlint Note that gitlint requires that you specify `--pretty=%B` (=only print the log message, not the metadata), future versions of gitlint might fix this and not require the `--pretty` argument. -## Linting specific commits +## Linting specific commits or branches -Gitlint allows users to lint a specific commit: +Gitlint can lint specific commits using `--commit`: ```sh gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16 -gitlint --commit 019cf40 # short SHAs work too +gitlint --commit 019cf40 # short SHAs work too +gitlint --commit HEAD~2 # as do special references +gitlint --commit mybranch # lint latest commit on a branch ``` -You can also lint multiple commits at once like so: +You can also lint multiple commits using `--commits` (plural): ```sh # Lint a specific commit range: gitlint --commits "019cf40...d6bc75a" -# You can also use git's special references: +# Lint all commits on a branch +gitlint --commits mybranch +# Lint all commits that are different between a branch and your main branch +gitlint --commits "main..mybranch" +# Use git's special references gitlint --commits "origin..HEAD" + +# You can also pass multiple, comma separated commit hashes: +gitlint --commits 019cf40,c50eb150,d6bc75a +# These can include special references as well +gitlint --commits HEAD~1,mybranch-name,origin/main,d6bc75a ``` The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood by [git rev-list](https://git-scm.com/docs/git-rev-list) as a single argument will work. +Alternatively, you can pass `--commits` a comma-separated list of commit hashes (both short and full-length SHAs work, +as well as special references such as `HEAD` and branch names). +Gitlint will treat these as pointers to **single** commits and lint these in the order you passed. + For cases where the `--commits` option doesn't provide the flexibility you need, you can always use a simple shell script to lint an arbitrary set of commits, like shown in the example below. ```sh #!/bin/sh -for commit in $(git rev-list master); do +for commit in $(git rev-list my-branch); do echo "Commit $commit" gitlint --commit $commit echo "--------" @@ -283,14 +347,14 @@ done !!! note One downside to this approach is that you invoke gitlint once per commit vs. once per set of commits. - This means you'll incur the gitlint startup time once per commit, making this approach rather slow if you want to + This means you'll incur the gitlint startup time once per commit, making it rather slow if you want to lint a large set of commits. Always use `--commits` if you can to avoid this performance penalty. ## Merge, fixup, squash and revert commits -_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash) and v0.13.0 (revert)_ +_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash), v0.13.0 (revert) and v0.18.0 (fixup=amend)_ -**Gitlint ignores merge, revert, fixup and squash commits by default.** +**Gitlint ignores merge, revert, fixup, and squash commits by default.** For merge and revert commits, the rationale for ignoring them is that most users keep git's default messages for these commits (i.e *Merge/Revert "[original commit message]"*). @@ -300,14 +364,14 @@ For example, a common case is that *"Merge:"* being auto-prepended triggers a [title-max-length](rules.md#t1-title-max-length) violation. Most users don't want this, so we disable linting on Merge and Revert commits by default. -For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits, the rationale is that these are temporary +For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) (including [fixup=amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)) commits, the rationale is that these are temporary commits that will be squashed into a different commit, and hence the commit messages for these commits are very -short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"* or -*"squash!"* to your commit message, certain gitlint rules might be violated +short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"*, +*"amend!"* or *"squash!"* to your commit message, certain gitlint rules might be violated (e.g. [title-max-length](rules.md#t1-title-max-length)) which is often undesirable. In case you *do* want to lint these commit messages, you can disable this behavior by setting the -general `ignore-merge-commits`, `ignore-revert-commits`, `ignore-fixup-commits` or +general `ignore-merge-commits`, `ignore-revert-commits`, `ignore-fixup-commits`, `ignore-fixup-amend-commits` or `ignore-squash-commits` option to `false` [using one of the various ways to configure gitlint](configuration.md). @@ -374,7 +438,7 @@ additional unique identifier (i.e. the rule *name*) during configuration. For example, by defining 2 `body-max-line-length` rules with different `line-length` options, you obviously create a conflicting situation. Gitlint does not do any resolution of such conflicts, it's up to you to make sure any configuration is non-conflicting. So caution advised! - + Defining a named rule is easy, for example using your `.gitlint` file: ```ini @@ -400,7 +464,7 @@ When executing gitlint, you will see the violations from the default `title-must the violations caused by the additional Named Rules. ```sh -$ gitlint +$ gitlint 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: foo wonderwoman hur bar" 1: T5:This-Can_Be*Whatever$YouWant Title contains the word 'wonderwoman' (case-insensitive): "WIP: foo wonderwoman hur bar" 1: T5:extra-words Title contains the word 'foo' (case-insensitive): "WIP: foo wonderwoman hur bar" @@ -431,8 +495,8 @@ of violations counted by the exit code is 252. Note that gitlint does not have a it can detect, it will just always return with exit code 252 when the number of violations is greater than or equal to 252. -Exit Code | Description ------------|------------------------------------------------------------ -253 | Wrong invocation of the `gitlint` command. -254 | Something went wrong when invoking git. -255 | Invalid gitlint configuration +| Exit Code | Description | +| --------- | ------------------------------------------ | +| 253 | Wrong invocation of the `gitlint` command. | +| 254 | Something went wrong when invoking git. | +| 255 | Invalid gitlint configuration | -- cgit v1.2.3