# getModifiedPaths

Returns a list of paths which have been modified based on the current Git branch and the provided base commit.

This can be used in a Jenkins pipeline to determine which projects should be built based on the build context.

The branch treated as the trunk is configurable via `mainBranch` (defaults to `master`).

* If `branchName` equals `mainBranch` and `baseCommit` is null, returns all modified files.
* If `branchName` is not `mainBranch` and `baseCommit` is null, returns the files which have changed relative to the common ancestor of the provided branch and `mainBranch`
* If `branchName` is not `mainBranch` and `baseCommit` is not null, returns the files which have changed relative to `baseCommit`.

A list of paths can optionally be provided. If provided, the return value will be the subset of those paths which contain modifications.

## Parameters

| Name       | Description                                                                   | Type           | Default                                                                | Required |
|------------|-------------------------------------------------------------------------------|----------------|------------------------------------------------------------------------|----------|
| branchName | The name of the current branch                                                | `String`       | The value of the `BRANCH_NAME` environment variable                    | no       |
| paths      | A list of file paths (relative to repository root) to check for modifications | `List<String>` | -                                                                      | no       |
| baseCommit | The base commit to compare with                                               | `String`       | The value of the `GIT_PREVIOUS_SUCCESSFUL_COMMIT` environment variable | no       |
| mainBranch | The name of the repository's trunk branch (e.g. `master` or `main`)           | `String`       | `master`                                                               | no       |

## Examples

```groovy
// Automatically determine the modified paths based on Jenkins build context.
def modifiedPaths = getModifiedPaths()
```

```groovy
// Determine the paths modified relative to a specific commit.
def modifiedPaths = getModifiedPaths(
    baseCommit: 'abcdef'
)
```

```groovy
// Determine the paths modified relative to master.
def modifiedPaths = getModifiedPaths(
    branchName: 'feature-branch',
)
```

```groovy
// For repositories whose trunk is `main`, set mainBranch accordingly.
def modifiedPaths = getModifiedPaths(
    branchName: 'feature-branch',
    mainBranch: 'main',
)
```

```groovy
// Determine which of the provided paths contain modifications.
def modifiedPaths = getModifiedPaths(
    paths: ['dir1', 'dir2/file.txt'],
)
echo modifiedPaths
// Output: [] or ['dir1'] or ['dir2/file.txt'] or ['dir1', 'dir2/file.txt']
```