summaryrefslogtreecommitdiffstats
path: root/examples
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-09 13:38:02 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-09 13:38:02 +0000
commit6f442e774b9236c999f36c2d7af17640f49bff99 (patch)
tree47e73755bffd41bdde2d59d76cc595f5a1fa75d4 /examples
parentInitial commit. (diff)
downloadgitlint-upstream.tar.xz
gitlint-upstream.zip
Adding upstream version 0.19.1.upstream/0.19.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--examples/commit-message-15
-rw-r--r--examples/commit-message-106
-rw-r--r--examples/commit-message-117
-rw-r--r--examples/commit-message-25
-rw-r--r--examples/commit-message-33
-rw-r--r--examples/commit-message-43
-rw-r--r--examples/commit-message-51
-rw-r--r--examples/commit-message-61
-rw-r--r--examples/commit-message-74
-rw-r--r--examples/commit-message-86
-rw-r--r--examples/commit-message-97
-rw-r--r--examples/gitlint58
-rw-r--r--examples/my_commit_rules.py92
-rw-r--r--examples/my_configuration_rules.py69
-rw-r--r--examples/my_line_rules.py55
15 files changed, 322 insertions, 0 deletions
diff --git a/examples/commit-message-1 b/examples/commit-message-1
new file mode 100644
index 0000000..7be3ddd
--- /dev/null
+++ b/examples/commit-message-1
@@ -0,0 +1,5 @@
+WIP: This is the title of a commit message.
+The second line should typically be empty
+Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120.
+# All of the following is ignored
+# This line starts with a hard tab
diff --git a/examples/commit-message-10 b/examples/commit-message-10
new file mode 100644
index 0000000..f5bff2a
--- /dev/null
+++ b/examples/commit-message-10
@@ -0,0 +1,6 @@
+This h@s $pecialCh@rs!
+
+Commit body
+with more
+than 3 lines
+and no signed off by line \ No newline at end of file
diff --git a/examples/commit-message-11 b/examples/commit-message-11
new file mode 100644
index 0000000..72c7fa8
--- /dev/null
+++ b/examples/commit-message-11
@@ -0,0 +1,7 @@
+Release: Holy Smokes, Batman!
+
+This release contains a bunch of features.
+
+- Here's a description of a feature that exceeds the default maximum line length of 80 characters
+
+$ my-fancy-tool: this line is auto-generated by our release tool and is always too long $ \ No newline at end of file
diff --git a/examples/commit-message-2 b/examples/commit-message-2
new file mode 100644
index 0000000..8ca3b4a
--- /dev/null
+++ b/examples/commit-message-2
@@ -0,0 +1,5 @@
+This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping
+This line should not contain text
+Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120.
+
+# This line will be ignored by gitlint because it starts with a #.
diff --git a/examples/commit-message-3 b/examples/commit-message-3
new file mode 100644
index 0000000..9a3eb59
--- /dev/null
+++ b/examples/commit-message-3
@@ -0,0 +1,3 @@
+ This is the wip title of a commit message!
+
+Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120.
diff --git a/examples/commit-message-4 b/examples/commit-message-4
new file mode 100644
index 0000000..3a15cb4
--- /dev/null
+++ b/examples/commit-message-4
@@ -0,0 +1,3 @@
+ This title has a leading tab whitespace
+
+tooshort
diff --git a/examples/commit-message-5 b/examples/commit-message-5
new file mode 100644
index 0000000..0088dae
--- /dev/null
+++ b/examples/commit-message-5
@@ -0,0 +1 @@
+US1234: This commit message has no body
diff --git a/examples/commit-message-6 b/examples/commit-message-6
new file mode 100644
index 0000000..631cf62
--- /dev/null
+++ b/examples/commit-message-6
@@ -0,0 +1 @@
+Merge "US1234: This merge has no body and that's OK"
diff --git a/examples/commit-message-7 b/examples/commit-message-7
new file mode 100644
index 0000000..6f7c192
--- /dev/null
+++ b/examples/commit-message-7
@@ -0,0 +1,4 @@
+This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping
+This line should not contain text
+Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120.
+gitlint-ignore: all
diff --git a/examples/commit-message-8 b/examples/commit-message-8
new file mode 100644
index 0000000..4ba6e86
--- /dev/null
+++ b/examples/commit-message-8
@@ -0,0 +1,6 @@
+This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping
+This line should not contain text
+Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120.
+
+# This line will be ignored by gitlint because it starts with a #.
+gitlint-ignore: B4, title-hard-tab \ No newline at end of file
diff --git a/examples/commit-message-9 b/examples/commit-message-9
new file mode 100644
index 0000000..018ac46
--- /dev/null
+++ b/examples/commit-message-9
@@ -0,0 +1,7 @@
+Merge: "This is a merge commit with a long title that most definitely exceeds the normal limit of 72 chars"
+This line should be empty
+This is the first line is meant to test a line that exceeds the maximum line length of 80 characters.
+
+You will notice that gitlint ignores all of these errors by default because this is a merge commit.
+
+If you want to change this behavior, set the following option: 'general.ignore-merge-commits=false'
diff --git a/examples/gitlint b/examples/gitlint
new file mode 100644
index 0000000..0261752
--- /dev/null
+++ b/examples/gitlint
@@ -0,0 +1,58 @@
+# Edit this file as you like.
+#
+# All these sections are optional. Each section with the exception of general represents
+# one rule and each key in it is an option for that specific rule.
+#
+# Rules and sections can be referenced by their full name or by id. For example
+# section "[body-max-line-length]" could be written as "[B1]". Full section names are
+# used in here for clarity.
+# Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/
+#
+# Note that this file is not exhaustive, it's just an example
+# Use 'gitlint generate-config' to generate a config file with all possible options
+[general]
+ignore=title-trailing-punctuation, T3
+# verbosity should be a value between 1 and 3, the commandline -v flags take precedence over this
+verbosity = 2
+# By default gitlint will ignore merge commits. Set to 'false' to disable.
+ignore-merge-commits=true
+# Enable debug mode (prints more output). Disabled by default
+debug = true
+
+# Set the extra-path where gitlint will search for user defined rules
+# See http://jorisroovers.github.io/gitlint/user_defined_rules for details
+# extra-path=examples/
+
+[title-max-length]
+line-length=50
+
+[title-must-not-contain-word]
+# Comma-separated list of words that should not occur in the title. Matching is case
+# insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING"
+# will not cause a violation, but "WIP: my title" will.
+words=wip,title
+
+[title-match-regex]
+# python like regex (https://docs.python.org/2/library/re.html) that the
+# commit-msg title must be matched to.
+# Note that the regex can contradict with other rules if not used correctly
+# (e.g. title-must-not-contain-word).
+regex=^US[0-9]*
+
+[body-max-line-length]
+line-length=72
+
+[body-min-length]
+min-length=5
+
+[body-is-missing]
+# Whether to ignore this rule on merge commits (which typically only have a title)
+# default = True
+ignore-merge-commits=false
+
+[body-changed-file-mention]
+# List of files that need to be explicitly mentioned in the body when they are changed
+# This is useful for when developers often erroneously edit certain files or git submodules.
+# By specifying this rule, developers can only change the file when they explicitly reference
+# it in the commit message.
+files=gitlint-core/gitlint/rules.py,README.md
diff --git a/examples/my_commit_rules.py b/examples/my_commit_rules.py
new file mode 100644
index 0000000..35bb836
--- /dev/null
+++ b/examples/my_commit_rules.py
@@ -0,0 +1,92 @@
+from gitlint.rules import CommitRule, RuleViolation
+from gitlint.options import IntOption, ListOption
+
+"""
+Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules
+
+The classes below are examples of user-defined CommitRules. Commit rules are gitlint rules that
+act on the entire commit at once. Once the rules are discovered, gitlint will automatically take care of applying them
+to the entire commit. This happens exactly once per commit.
+
+A CommitRule contrasts with a LineRule (see examples/my_line_rules.py) in that a commit rule is only applied once on
+an entire commit. This allows commit rules to implement more complex checks that span multiple lines and/or checks
+that should only be done once per gitlint run.
+
+While every LineRule can be implemented as a CommitRule, it's usually easier and more concise to go with a LineRule if
+that fits your needs.
+"""
+
+
+class BodyMaxLineCount(CommitRule):
+ # A rule MUST have a human friendly name
+ name = "body-max-line-count"
+
+ # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule).
+ id = "UC1"
+
+ # A rule MAY have an option_spec if its behavior should be configurable.
+ options_spec = [IntOption("max-line-count", 3, "Maximum body line count")]
+
+ def validate(self, commit):
+ self.log.debug("BodyMaxLineCount: This will be visible when running `gitlint --debug`")
+
+ line_count = len(commit.message.body)
+ max_line_count = self.options["max-line-count"].value
+ if line_count > max_line_count:
+ message = f"Body contains too many lines ({line_count} > {max_line_count})"
+ return [RuleViolation(self.id, message, line_nr=1)]
+
+
+class SignedOffBy(CommitRule):
+ """This rule will enforce that each commit contains a "Signed-off-by" line.
+ We keep things simple here and just check whether the commit body contains a line that starts with "Signed-off-by".
+ """
+
+ # A rule MUST have a human friendly name
+ name = "body-requires-signed-off-by"
+
+ # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule).
+ id = "UC2"
+
+ def validate(self, commit):
+ self.log.debug("SignedOffBy: This will be visible when running `gitlint --debug`")
+
+ for line in commit.message.body:
+ if line.startswith("Signed-off-by"):
+ return
+
+ return [RuleViolation(self.id, "Body does not contain a 'Signed-off-by' line", line_nr=1)]
+
+
+class BranchNamingConventions(CommitRule):
+ """This rule will enforce that a commit is part of a branch that meets certain naming conventions.
+ See GitFlow for real-world example of this: https://nvie.com/posts/a-successful-git-branching-model/
+ """
+
+ # A rule MUST have a human friendly name
+ name = "branch-naming-conventions"
+
+ # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule).
+ id = "UC3"
+
+ # A rule MAY have an option_spec if its behavior should be configurable.
+ options_spec = [ListOption("branch-prefixes", ["feature/", "hotfix/", "release/"], "Allowed branch prefixes")]
+
+ def validate(self, commit):
+ self.log.debug("BranchNamingConventions: This line will be visible when running `gitlint --debug`")
+
+ violations = []
+ allowed_branch_prefixes = self.options["branch-prefixes"].value
+ for branch in commit.branches:
+ valid_branch_name = False
+
+ for allowed_prefix in allowed_branch_prefixes:
+ if branch.startswith(allowed_prefix):
+ valid_branch_name = True
+ break
+
+ if not valid_branch_name:
+ msg = f"Branch name '{branch}' does not start with one of {allowed_branch_prefixes}"
+ violations.append(RuleViolation(self.id, msg, line_nr=1))
+
+ return violations
diff --git a/examples/my_configuration_rules.py b/examples/my_configuration_rules.py
new file mode 100644
index 0000000..7715c0b
--- /dev/null
+++ b/examples/my_configuration_rules.py
@@ -0,0 +1,69 @@
+from gitlint.rules import ConfigurationRule
+from gitlint.options import IntOption
+
+
+"""
+Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules
+
+The ReleaseConfigurationRule class below is an example of a user-defined ConfigurationRule. Configuration rules are
+gitlint rules that are applied once per commit and BEFORE any other rules are run. Configuration Rules are meant to
+dynamically change gitlint's configuration and/or the commit that is about to be linted. A typically use-case for this
+is modifying the behavior of gitlint's rules based on a commit contents.
+
+Notes:
+- Modifying the commit object DOES NOT modify the actual git commit message in the target repo, only gitlint's copy of
+ it.
+- Modifying the config object only has effect on the commit that is being linted, subsequent commits will not
+ automatically inherit this configuration.
+"""
+
+
+class ReleaseConfigurationRule(ConfigurationRule):
+ """
+ This rule will modify gitlint's behavior for Release Commits.
+
+ This example might not be the most realistic for a real-world scenario,
+ but is meant to give an overview of what's possible.
+ """
+
+ # A rule MUST have a human friendly name
+ name = "release-configuration-rule"
+
+ # A rule MUST have a *unique* id, we recommend starting with UCR
+ # (for User-defined Configuration-Rule), but this can really be anything.
+ id = "UCR1"
+
+ # A rule MAY have an option_spec if its behavior should be configurable.
+ options_spec = [IntOption("custom-verbosity", 2, "Gitlint verbosity for release commits")]
+
+ def apply(self, config, commit):
+ self.log.debug("ReleaseConfigurationRule: This will be visible when running `gitlint --debug`")
+
+ # If the commit title starts with 'Release', we want to modify
+ # how all subsequent rules interpret that commit
+ if commit.message.title.startswith("Release"):
+ # If your Release commit messages are auto-generated, the
+ # body might contain trailing whitespace. Let's ignore that
+ config.ignore.append("body-trailing-whitespace")
+
+ # Similarly, the body lines might exceed 80 chars,
+ # let's set gitlint's limit to 200
+ # To set rule options use:
+ # config.set_rule_option(<rule-name>, <rule-option>, <value>)
+ config.set_rule_option("body-max-line-length", "line-length", 200)
+
+ # For kicks, let's set gitlint's verbosity to 2
+ # To set general options use
+ # config.set_general_option(<general-option>, <value>)
+ config.set_general_option("verbosity", 2)
+ # Wwe can also use custom options to make this configurable
+ config.set_general_option("verbosity", self.options["custom-verbosity"].value)
+
+ # Strip any lines starting with $ from the commit message
+ # (this only affects how gitlint sees your commit message, it does
+ # NOT modify your actual commit in git)
+ commit.message.body = [line for line in commit.message.body if not line.startswith("$")]
+
+ # You can add any extra properties you want to the commit object, these will be available later on
+ # in all rules.
+ commit.my_property = "This is my property"
diff --git a/examples/my_line_rules.py b/examples/my_line_rules.py
new file mode 100644
index 0000000..58b0108
--- /dev/null
+++ b/examples/my_line_rules.py
@@ -0,0 +1,55 @@
+from gitlint.rules import LineRule, RuleViolation, CommitMessageTitle
+from gitlint.options import ListOption
+
+"""
+Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules
+
+The SpecialChars class below is an example of a user-defined LineRule. Line rules are gitlint rules that only act on a
+single line at once. Once the rule is discovered, gitlint will automatically take care of applying this rule
+against each line of the commit message title or body (whether it is applied to the title or body is determined by the
+`target` attribute of the class).
+
+A LineRule contrasts with a CommitRule (see examples/my_commit_rules.py) in that a commit rule is only applied once on
+an entire commit. This allows commit rules to implement more complex checks that span multiple lines and/or checks
+that should only be done once per gitlint run.
+
+While every LineRule can be implemented as a CommitRule, it's usually easier and more concise to go with a LineRule if
+that fits your needs.
+"""
+
+
+class SpecialChars(LineRule):
+ """This rule will enforce that the commit message title does not contain any of the following characters:
+ $^%@!*()"""
+
+ # A rule MUST have a human friendly name
+ name = "title-no-special-chars"
+
+ # A rule MUST have a *unique* id, we recommend starting with UL (for User-defined Line-rule), but this can
+ # really be anything.
+ id = "UL1"
+
+ # A line-rule MUST have a target (not required for CommitRules).
+ target = CommitMessageTitle
+
+ # A rule MAY have an option_spec if its behavior should be configurable.
+ options_spec = [
+ ListOption(
+ "special-chars",
+ ["$", "^", "%", "@", "!", "*", "(", ")"],
+ "Comma separated list of characters that should not occur in the title",
+ )
+ ]
+
+ def validate(self, line, _commit):
+ self.log.debug("SpecialChars: This will be visible when running `gitlint --debug`")
+
+ violations = []
+ # options can be accessed by looking them up by their name in self.options
+ for char in self.options["special-chars"].value:
+ if char in line:
+ msg = f"Title contains the special character '{char}'"
+ violation = RuleViolation(self.id, msg, line)
+ violations.append(violation)
+
+ return violations