Some repositories may contain more than project. This is sometimes referred to as a mono repo (as opposed to having a repo for each project - many repo). Imagine a repository structured as:
- /
- Foo/
- version.json =>
{"version": "1.0"}
- version.json =>
- Bar/
- version.json =>
{"version": "2.1"}
- version.json =>
- Quux/
- version.json =>
{"version": "4.3"}
- version.json =>
- README.md
- Foo/
With GitVersioning's default configuration, a commit to a given project's subtree will result in the version height bumping for all projects in the repository. This is typically not desirable. Intuitively, a commit to Bar
should only cause a version bump for Bar
, and not Foo
or Quux
.
Path filters provide a way to filter which subtrees in the repository affect version height. Imagine the version.json
files had a pathFilter
property:
{
"version": "1.0",
"pathFilters": ["."]
}
With this single path filter of "."
, the version height for this project would only bump when a commit was made within that subtree. Now imagine all projects in the original example have this value for pathFilters
. Consider the following commits to the repository, and note their effect on the version height for each project:
Paths changed | Result |
---|---|
/README.md |
Commit does not affect any project. No versions change. |
/Bar/Program.cs /Quux/Quux.csproj |
Commit affects both Bar and Quux . Their patch versions will bump by 1. |
/Bar/MyClass.cs |
Commit affects only Bar . Bar 's patch version will bump by 1. |
When absent, the implied value for pathFilters
is:
{
"pathFilters": [":/"]
}
This results in the entire repository tree being considered for version height calculations. This is the default behavior for GitVersioning.
Path filters take on a variety of formats, and can specify paths relative to the version.json
or relative to the root of the repository. See the Path filter format section for more information.
Multiple path filters may also be specified. The order is irrelevant. After a path matches any non-exclude path filter, it will be run through all exclude path filter. If it matches, the path is ignored.
Path filter | Description |
---|---|
./quux.txt file-here.txt sub-dir/foo.txt ../sibling/inclusion.txt |
File will be included. Path is relative to the version.json file. |
./ sub-dir ../sibling |
Directory will be included. Path is relative to the version.json file. |
/root-file.txt :/dir/file.txt |
File will be included. Path is absolute (i.e., relative to the root of the repository). |
:!bar.txt :^../foo/baz.txt |
File will be excluded. Path is relative to the version.json file. :! and :^ prefixes are synonymous. |
:!/root-file.txt |
File will be excluded. Path is absolute (i.e., relative to the root of the repository). |