Feature: Support ignoring (filtering) paths in git tree

docs/input/docs/reference/configuration.md

@@ -191,6 +191,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit
@@ -208,7 +209,7 @@ tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
-<sup><a href='/docs/workflows/GitFlow/v1.yml#L1-L166' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/docs/workflows/GitFlow/v1.yml#L1-L167' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The supported built-in configuration for the `GitHubFlow` workflow (`workflow: GitHubFlow/v1`) looks like:
@@ -315,6 +316,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit
@@ -332,7 +334,7 @@ tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
-<sup><a href='/docs/workflows/GitHubFlow/v1.yml#L1-L115' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitHubFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/docs/workflows/GitHubFlow/v1.yml#L1-L116' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitHubFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The preview built-in configuration (experimental usage only) for the `TrunkBased` workflow (`workflow: TrunkBased/preview1`) looks like:
@@ -424,6 +426,7 @@ branches:
     pre-release-weight: 30000
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit
@@ -441,7 +444,7 @@ tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
-<sup><a href='/docs/workflows/TrunkBased/preview1.yml#L1-L100' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/TrunkBased/preview1.yml' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/docs/workflows/TrunkBased/preview1.yml#L1-L101' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/TrunkBased/preview1.yml' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 The details of the available options are as follows:
@@ -621,6 +624,44 @@ Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before:
 2015-10-23T12:23:15`) to setup an exclusion range. Effectively any commit before
 `commits-before` will be ignored.
 
+#### paths
+A sequence of regular expressions that represent paths in the repository. Commits that modify these paths will be excluded from version calculations. For example, to filter out commits that belong to `docs`:
+```yaml
+ignore:
+  paths:
+    - ^docs\/
+```
+##### *Monorepo*
+This ignore config can be used to filter only those commits that belong to a specific project in a monorepo. 
+As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `projectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`.
+* Specific match on `/ProjectB/*`:
+```yaml
+ignore:
+  paths:
+    - `^\/ProductB\/.*`
+```
+* Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`:
+```yaml
+ignore:
+  paths:
+    - `^(?!\/ProductA\/|\/LibraryC\/).*`
+```
+A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored:
+* `/ProductA/*`
+* `/LibraryC/*`
+* `/ProductA/*` and  `/LibraryC/*`
+* `/ProductA/*` and `/ProductB/*`
+* `/LibraryC/*` and `/ProductB/*`
+* `/ProductA/*` and `/ProductB/*` and `/LibraryC/*`
+
+:::
+Note: The `ignore.paths` configuration is case-sensitive. This can lead to unexpected behavior on case-insensitive file systems, such as Windows. To ensure consistent matching regardless of case, you can prefix your regular expressions with the case-insensitive flag `(?i)`. For example, `(?i)^docs\/` will match both `docs/` and `Docs/`. 
+:::
+
+::: {.alert .alert-warning}
+A commit is ignored by the `ignore.paths` configuration only if **all paths** changed in that commit match one or more of the specified regular expressions. If a path in a commit does not match any one of the ignore patterns, that commit will be included in version calculations.
+:::
+
 ### merge-message-formats
 
 Custom merge message formats to enable identification of merge messages that do not

docs/input/docs/reference/mdsource/configuration.source.md

@@ -225,6 +225,44 @@ Date and time in the format `yyyy-MM-ddTHH:mm:ss` (eg `commits-before:
 2015-10-23T12:23:15`) to setup an exclusion range. Effectively any commit before
 `commits-before` will be ignored.
 
+#### paths
+A sequence of regular expressions that represent paths in the repository. Commits that modify these paths will be excluded from version calculations. For example, to filter out commits that belong to `docs`:
+```yaml
+ignore:
+  paths:
+    - ^docs\/
+```
+##### *Monorepo*
+This ignore config can be used to filter only those commits that belong to a specific project in a monorepo. 
+As an example, consider a monorepo consisting of subdirectories for `ProjectA`, `ProjectB` and a shared `LibraryC`. For GitVersion to consider only commits that are part of `projectA` and shared library `LibraryC`, a regex that matches all paths except those starting with `ProjectA` or `LibraryC` can be used. Either one of the following configs would filter out `ProjectB`.
+* Specific match on `/ProjectB/*`:
+```yaml
+ignore:
+  paths:
+    - `^\/ProductB\/.*`
+```
+* Negative lookahead on anything other than `/ProjectA/*` and `/LibraryC/*`:
+```yaml
+ignore:
+  paths:
+    - `^(?!\/ProductA\/|\/LibraryC\/).*`
+```
+A commit having changes only in `/ProjectB/*` path would be ignored. A commit having changes in the following paths wouldn't be ignored:
+* `/ProductA/*`
+* `/LibraryC/*`
+* `/ProductA/*` and  `/LibraryC/*`
+* `/ProductA/*` and `/ProductB/*`
+* `/LibraryC/*` and `/ProductB/*`
+* `/ProductA/*` and `/ProductB/*` and `/LibraryC/*`
+
+:::
+Note: The `ignore.paths` configuration is case-sensitive. This can lead to unexpected behavior on case-insensitive file systems, such as Windows. To ensure consistent matching regardless of case, you can prefix your regular expressions with the case-insensitive flag `(?i)`. For example, `(?i)^docs\/` will match both `docs/` and `Docs/`. 
+:::
+
+::: {.alert .alert-warning}
+A commit is ignored by the `ignore.paths` configuration only if **all paths** changed in that commit match one or more of the specified regular expressions. If a path in a commit does not match any one of the ignore patterns, that commit will be included in version calculations.
+:::
+
 ### merge-message-formats
 
 Custom merge message formats to enable identification of merge messages that do not

docs/input/docs/workflows/GitFlow/v1.yml

@@ -148,6 +148,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

docs/input/docs/workflows/GitHubFlow/v1.yml

@@ -97,6 +97,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

docs/input/docs/workflows/TrunkBased/preview1.yml

@@ -82,6 +82,7 @@ branches:
     pre-release-weight: 30000
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

new-cli/GitVersion.Core.Libgit2Sharp/GitVersion.Core.Libgit2Sharp.csproj

@@ -56,6 +56,9 @@
       </Compile>
       <Compile Include="..\..\src\GitVersion.LibGit2Sharp\Git\TagCollection.cs">
         <Link>Git\TagCollection.cs</Link>
+      </Compile>
+	  <Compile Include="..\..\src\GitVersion.LibGit2Sharp\Git\TreeChanges.cs">
+        <Link>Git\TreeChanges.cs</Link>
       </Compile>
     </ItemGroup>
 

src/GitVersion.Configuration.Tests/Configuration/ConfigurationProviderTests.CanWriteOutEffectiveConfiguration.approved.txt

@@ -148,6 +148,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

src/GitVersion.Configuration.Tests/Workflows/approved/GitFlow/v1.yml

@@ -148,6 +148,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

src/GitVersion.Configuration.Tests/Workflows/approved/GitHubFlow/v1.yml

@@ -97,6 +97,7 @@ branches:
     is-main-branch: false
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

src/GitVersion.Configuration.Tests/Workflows/approved/TrunkBased/preview1.yml

@@ -82,6 +82,7 @@ branches:
     pre-release-weight: 30000
 ignore:
   sha: []
+  paths: []
 mode: ContinuousDelivery
 label: '{BranchName}'
 increment: Inherit

src/GitVersion.Configuration/IgnoreConfiguration.cs

@@ -1,3 +1,4 @@
+using System.Collections.ObjectModel;
 using GitVersion.Configuration.Attributes;
 
 namespace GitVersion.Configuration;
@@ -23,6 +24,12 @@ public string? BeforeString
     [JsonPropertyDescription("A sequence of SHAs to be excluded from the version calculations.")]
     public HashSet<string> Shas { get; init; } = [];
 
+    IReadOnlyCollection<string> IIgnoreConfiguration.Paths => Paths;
+
+    [JsonPropertyName("paths")]
+    [JsonPropertyDescription("A sequence of file paths to be excluded from the version calculations.")]
+    public Collection<string> Paths { get; init; } = [];
+
     [JsonIgnore]
-    public bool IsEmpty => Before == null && Shas.Count == 0;
+    public bool IsEmpty => Before == null && Shas.Count == 0 && Paths.Count == 0;
 }

src/GitVersion.Core.Tests/Extensions/GitRepositoryTestingExtensions.cs

@@ -32,6 +32,13 @@ public static ICommit CreateMockCommit()
         return commit;
     }
 
+    public static ICommit CreateMockCommit(List<string> diffPaths)
+    {
+        var commit = CreateMockCommit();
+        commit.DiffPaths.Returns(diffPaths);
+        return commit;
+    }
+
     public static IBranch CreateMockBranch(string name, params ICommit[] commits)
     {
         var branch = Substitute.For<IBranch>();

src/GitVersion.Core.Tests/IntegrationTests/IgnoreCommitScenarios.cs

@@ -135,8 +135,9 @@ public void GivenTrunkBasedWorkflowWithIgnoreConfigurationBeforeCommitWithTagThe
         fixture.ApplyTag("1.0.0");
         fixture.MakeACommit("D");
 
+        var before = commitC.Committer.When.AddSeconds(1);
         var configuration = TrunkBasedConfigurationBuilder.New
-            .WithIgnoreConfiguration(new IgnoreConfiguration { Before = commitC.Committer.When })
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Before = before })
             .Build();
 
         // ✅ succeeds as expected
@@ -285,8 +286,9 @@ public void GivenGitHubFlowWorkflowWithIgnoreConfigurationBeforeCommitWithTagThe
         fixture.ApplyTag("1.0.0");
         fixture.MakeACommit("D");
 
+        var before = commitC.Committer.When.AddSeconds(1);
         var configuration = GitHubFlowConfigurationBuilder.New
-            .WithIgnoreConfiguration(new IgnoreConfiguration { Before = commitC.Committer.When })
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Before = before })
             .Build();
 
         // ✅ succeeds as expected
@@ -331,4 +333,104 @@ public void GivenGitHubFlowWorkflowWithCommitParameterBThenTagShouldBeConsidered
         // ✅ succeeds as expected
         fixture.AssertFullSemver(semanticVersion, configuration, commitId: commitA.Sha);
     }
+
+    [Test]
+    public void GivenTrunkBasedWorkflowWithIgnoreConfigurationForPathThenVersionShouldBeCorrect()
+    {
+        using var fixture = new EmptyRepositoryFixture();
+
+        var commitA = fixture.Repository.MakeACommit("A");
+        var commitB = fixture.Repository.MakeACommit("B");
+        fixture.MakeACommit("C");
+        fixture.MakeACommit("D");
+
+        var ignoredPath = fixture.Repository.Diff.Compare<LibGit2Sharp.TreeChanges>(commitA.Tree, commitB.Tree).Select(element => element.Path).First();
+
+        var configuration = TrunkBasedConfigurationBuilder.New
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Paths = { ignoredPath } })
+            .Build();
+
+        // commitB should be ignored, so version should be as if B didn't exist
+        fixture.AssertFullSemver("0.0.3", configuration);
+    }
+
+    [Test]
+    public void GivenTrunkBasedWorkflowWithIgnoreConfigurationForPathAndCommitParameterCThenVersionShouldBeCorrect()
+    {
+        using var fixture = new EmptyRepositoryFixture();
+
+        var commitA = fixture.Repository.MakeACommit("A");
+        fixture.MakeACommit("B");
+        var commitC = fixture.Repository.MakeACommit("C");
+        fixture.MakeACommit("D");
+
+        var ignoredPath = fixture.Repository.Diff.Compare<LibGit2Sharp.TreeChanges>(commitA.Tree, commitC.Tree).Select(element => element.Path).First();
+
+        var configuration = TrunkBasedConfigurationBuilder.New
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Paths = { ignoredPath } })
+            .Build();
+
+        // commitC should be ignored, so version should be as if C didn't exist
+        fixture.AssertFullSemver("0.0.2", configuration, commitId: commitC.Sha);
+    }
+
+    [Test]
+    public void GivenGitHubFlowWorkflowWithIgnoreConfigurationForPathThenVersionShouldBeCorrect()
+    {
+        using var fixture = new EmptyRepositoryFixture();
+
+        var commitA = fixture.Repository.MakeACommit("A");
+        var commitB = fixture.Repository.MakeACommit("B");
+        fixture.MakeACommit("C");
+        fixture.MakeACommit("D");
+
+        var ignoredPath = fixture.Repository.Diff.Compare<LibGit2Sharp.TreeChanges>(commitA.Tree, commitB.Tree).Select(element => element.Path).First();
+
+        var configuration = GitHubFlowConfigurationBuilder.New
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Paths = { ignoredPath } })
+            .Build();
+
+        // commitB should be ignored, so version should be as if B didn't exist
+        fixture.AssertFullSemver("0.0.1-3", configuration);
+    }
+
+    [Test]
+    public void GivenTrunkBasedWorkflowWithIgnoreConfigurationForTaggedCommitPathThenTagShouldBeIgnored()
+    {
+        using var fixture = new EmptyRepositoryFixture();
+
+        var commitA = fixture.Repository.MakeACommit("A");
+        var commitB = fixture.Repository.MakeACommit("B");
+        fixture.ApplyTag("1.0.0");
+        fixture.MakeACommit("C");
+
+        var ignoredPath = fixture.Repository.Diff.Compare<LibGit2Sharp.TreeChanges>(commitA.Tree, commitB.Tree).Select(element => element.Path).First();
+
+        var configuration = TrunkBasedConfigurationBuilder.New
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Paths = { ignoredPath } })
+            .Build();
+
+        // commitB should be ignored, so version should be as if B didn't exist
+        fixture.AssertFullSemver("0.0.2", configuration);
+    }
+
+    [Test]
+    public void GivenGitHubFlowWorkflowWithIgnoreConfigurationForTaggedCommitPathThenTagShouldBeIgnored()
+    {
+        using var fixture = new EmptyRepositoryFixture();
+
+        var commitA = fixture.Repository.MakeACommit("A");
+        var commitB = fixture.Repository.MakeACommit("B");
+        fixture.ApplyTag("1.0.0");
+        fixture.MakeACommit("C");
+
+        var ignoredPath = fixture.Repository.Diff.Compare<LibGit2Sharp.TreeChanges>(commitA.Tree, commitB.Tree).Select(element => element.Path).First();
+
+        var configuration = GitHubFlowConfigurationBuilder.New
+            .WithIgnoreConfiguration(new IgnoreConfiguration { Paths = { ignoredPath } })
+            .Build();
+
+        // commitB should be ignored, so version should be as if B didn't exist
+        fixture.AssertFullSemver("0.0.1-2", configuration);
+    }
 }

src/GitVersion.Core.Tests/VersionCalculation/MinDateVersionFilterTests.cs

@@ -12,7 +12,7 @@ public void VerifyNullGuard()
         var dummy = DateTimeOffset.UtcNow.AddSeconds(1.0);
         var sut = new MinDateVersionFilter(dummy);
 
-        Should.Throw<ArgumentNullException>(() => sut.Exclude(null!, out _));
+        Should.Throw<ArgumentNullException>(() => sut.Exclude((IBaseVersion)null!, out _));
     }
 
     [Test]