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:

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

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]

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

@@ -0,0 +1,61 @@
+using GitVersion.Core.Tests.Helpers;
+using GitVersion.VersionCalculation;
+
+namespace GitVersion.Core.Tests;
+
+[TestFixture]
+public class PathFilterTests : TestBase
+{
+    [Test]
+    public void VerifyNullGuard()
+    {
+        var sut = new PathFilter([]);
+
+        Should.Throw<ArgumentNullException>(() => sut.Exclude((IBaseVersion)null!, out _));
+    }
+
+    [Test]
+    public void WhenPathMatchShouldExcludeWithReason()
+    {
+        var commit = GitRepositoryTestingExtensions.CreateMockCommit(["/path"]);
+        BaseVersion version = new("dummy", new SemanticVersion(1), commit);
+        var sut = new PathFilter(commit.DiffPaths);
+
+        sut.Exclude(version, out var reason).ShouldBeTrue();
+        reason.ShouldNotBeNullOrWhiteSpace();
+    }
+
+    [Test]
+    public void WhenPathMismatchShouldNotExclude()
+    {
+        var commit = GitRepositoryTestingExtensions.CreateMockCommit(["/path"]);
+        BaseVersion version = new("dummy", new SemanticVersion(1), commit);
+        var sut = new PathFilter(["/another_path"]);
+
+        sut.Exclude(version, out var reason).ShouldBeFalse();
+        reason.ShouldBeNull();
+    }
+
+    [Test]
+    public void WhenCommitSourceStartsWithCommitTagShouldNotBeExcluded()
+    {
+        var commit = GitRepositoryTestingExtensions.CreateMockCommit(["/path"]);
+        BaseVersion version = new("Git tag: v1.0.0", new SemanticVersion(1), commit);
+        var sut = new PathFilter(commit.DiffPaths);
+
+        var result = sut.Exclude(version, out var reason);
+
+        result.ShouldBeFalse();
+        reason.ShouldBeNull();
+    }
+
+    [Test]
+    public void ExcludeShouldAcceptVersionWithNullCommit()
+    {
+        BaseVersion version = new("dummy", new SemanticVersion(1));
+        var sut = new PathFilter(["/path"]);
+
+        sut.Exclude(version, out var reason).ShouldBeFalse();
+        reason.ShouldBeNull();
+    }
+}

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

@@ -12,7 +12,7 @@ public void VerifyNullGuard()
         var commit = GitRepositoryTestingExtensions.CreateMockCommit();
         var sut = new ShaVersionFilter([commit.Sha]);
 
-        Should.Throw<ArgumentNullException>(() => sut.Exclude(null!, out _));
+        Should.Throw<ArgumentNullException>(() => sut.Exclude((IBaseVersion)null!, out _));
     }
 
     [Test]

src/GitVersion.Core.Tests/VersionCalculation/Strategies/MergeMessageBaseVersionStrategyTests.cs

@@ -204,6 +204,7 @@ private class MockCommit : ICommit
         public IObjectId Id => throw new NotImplementedException();
         public string Sha => throw new NotImplementedException();
         public IReadOnlyList<ICommit> Parents => throw new NotImplementedException();
+        public IReadOnlyList<string> DiffPaths => throw new NotImplementedException();
         public DateTimeOffset When => throw new NotImplementedException();
         public string Message => throw new NotImplementedException();
     }

src/GitVersion.Core/Configuration/EffectiveConfiguration.cs

@@ -67,7 +67,6 @@ public EffectiveConfiguration(
         PatchVersionBumpMessage = configuration.PatchVersionBumpMessage;
         NoBumpMessage = configuration.NoBumpMessage;
         CommitMessageIncrementing = branchConfiguration.CommitMessageIncrementing.Value;
-        VersionFilters = configuration.Ignore.ToFilters();
         Ignore = configuration.Ignore;
         TracksReleaseBranches = branchConfiguration.TracksReleaseBranches ?? false;
         IsReleaseBranch = branchConfiguration.IsReleaseBranch ?? false;
@@ -122,8 +121,6 @@ public EffectiveConfiguration(
 
     public CommitMessageIncrementMode CommitMessageIncrementing { get; }
 
-    public IEnumerable<IVersionFilter> VersionFilters { get; }
-
     public IIgnoreConfiguration Ignore { get; }
 
     public string? CommitDateFormat { get; }

src/GitVersion.Core/Configuration/IIgnoreConfiguration.cs

@@ -6,5 +6,7 @@ public interface IIgnoreConfiguration
 
     IReadOnlySet<string> Shas { get; }
 
+    IReadOnlyCollection<string> Paths { get; }
+
     bool IsEmpty { get; }
 }

src/GitVersion.Core/Configuration/IgnoreConfigurationExtensions.cs

@@ -22,5 +22,5 @@ public static IEnumerable<ICommit> Filter(this IIgnoreConfiguration ignore, ICom
     }
 
     private static bool ShouldBeIgnored(ICommit commit, IIgnoreConfiguration ignore)
-        => !(commit.When <= ignore.Before) && !ignore.Shas.Contains(commit.Sha);
+        => !ignore.ToFilters().Any(filter => filter.Exclude(commit, out var _));
 }

src/GitVersion.Core/Extensions/ConfigurationExtensions.cs

@@ -44,6 +44,7 @@ public static IEnumerable<IVersionFilter> ToFilters(this IIgnoreConfiguration so
 
         if (source.Shas.Count != 0) yield return new ShaVersionFilter(source.Shas);
         if (source.Before.HasValue) yield return new MinDateVersionFilter(source.Before.Value);
+        if (source.Paths.Count != 0) yield return new PathFilter(source.Paths.ToList());
     }
 
     private static IEnumerable<IBranchConfiguration> GetBranchConfigurations(IGitVersionConfiguration configuration, string branchName)