> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/path-filtering

Continue a pipeline based on paths of changed files. This can be useful in a monorepo setup where one may want to trigger different workflows based on which module(s) in the repo has changed. This orb does not support server at this time.


## Commands

### generate-config

Generate config file from the config list.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config-list-path` | string | /tmp/filtered-config-list | A file path to append config paths. Each path in this file should be relative to the working directory.
 |
| `generated-config-path` | string | /tmp/generated-config.yml | A file path for the generated config file.
 |

### set-parameters

Generates a set of pipeline parameters from `mapping` at `output-path`. Python is required to run this command.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base-revision` | string | main | The revision to compare the current one against for the purpose of determining changed files.
 |
| `config-path` | string | .circleci/continue_config.yml | The location of the config to continue the pipeline with, please note that this parameter will be ignored if the user passes the config file per mapping in the mapping parameter
 |
| `exclude` | string |  | List of paths to exclude from the mapping. One path per line.
 |
| `mapping` | string |  | Mapping of path regular expressions to pipeline parameters and values. One mapping per line, whitespace-delimited. If duplicate parameter keys are found, the last matching pattern will apply.
 |
| `output-path` | string | /tmp/pipeline-parameters.json | Path to save the generated parameters to.
 |
| `same-base-run` | boolean | true | This is value is used to know what to do when the base revision is the same as the current commit. When set to true, it will compare with the previous commit. When set to false, it will act as if not changes were done.
 |

## Jobs

### filter

Continues a pipeline in the `setup` state based with static config and a set of pipeline parameters based on the changes in this push.
The mapping should be a set of items like so: <path regular expression> <pipeline parameter> <value> Multiple mappings can be supplied on separate lines. If the regular expression matches any file changed between HEAD and the base revision, the pipeline parameter will be set to the supplied value for the setup workflow continuation. This way the continuation config can be filtered to only perform relevant tasks.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base-revision` | string | main | The revision to compare the current one against for the purpose of determining changed files.
 |
| `checkout` | boolean | true | Whether to run an optional checkout step before continuing |
| `checkout_method` | enum | blobless | Type of checkout to use. Supported are full and blobless. Default to blobless. |
| `circleci_domain` | string | circleci.com | The domain of the CircleCI installation - defaults to circleci.com. (Only necessary for CircleCI Server users) |
| `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. |
| `config-path` | string | .circleci/continue_config.yml | The location of the config to continue the pipeline with, please note that this parameter will be ignored if the user passes the config file per mapping in the mapping parameter
 |
| `debug` | boolean | false | This mode is use for testing purposes. Defaults to False When this is set to True, the parameters and the config will be generated, but the continuation won't be called.
 |
| `exclude` | string |  | List of paths to exclude from the mapping. One path per line.
 |
| `executor` | executor | default | Executor where to run this job |
| `mapping` | string |  | Mapping of path regular expressions (grep -P) to pipeline parameters and values. If the value is a file, then it will be loaded from the disk. One mapping per line, whitespace-delimited.
 |
| `output-path` | string | /tmp/pipeline-parameters.json | Path to save the generated parameters to.
 |
| `parameter_for_files_changed` | string |  | If you want to get the list of files changed in the dynamic config, this value is the name of the parameter containing those files in there. Defaults to empty string. Set to empty string if you don't want the parameter.
 |
| `resource_class` | string | small | Resource class to use |
| `same-base-run` | boolean | true | This is value is used to know what to do when the base revision is the same as the current commit. When set to true, it will compare with the previous commit. When set to false, it will act as if not changes were done.
 |
| `workspace_path` | string |  | Path to attach the workspace to |

## Executors

### default

This is a sample executor using Docker


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | current | Pick a specific cimg/base image variant: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### path_filtering

Continue a pipeline from the setup phase with supplied configuration and pipeline parameters generated from the files changed.


```yaml
version: '2.1'
setup: true
orbs:
  path-filtering: circleci/path-filtering@0.1.7
workflows:
  generate-config:
    jobs:
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue_config.yml
          mapping: |
            src/.* build-code true
            doc/.* build-docs true
            src/tests/.* string-parameter "value"
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue_config.yml
          mapping: |
            src/.* build-code true .circleci/build-code-config.yml
            doc/.* build-docs true .circleci/build-docs-config.yml
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue-config.yml
          mapping: .circleci/mapping.conf
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue_config.yml
          exclude: |
            src/config.yml
            build/target/.*
          mapping: |
            src/.*
            doc/.* .circleci/build-docs-config.yml
            tests/.* foo bar
            build/.* foo bar .circleci/build.yml
```