README.md

Path Filter Orb

This orb privides simple path filtering with two commands.

• continue: Continue if no change detected & stop if change detected.
• stop: Stop if no change detected & continue if change detected.

You can check usage & example at https://circleci.com/orbs/registry/orb/mkusaka/path-filter.

Motivation

Currently, CircleCI officially provides path-filtering orb.

However, it must be invoked as a setup workflow and is therefore subject to setup workflow restrictions. For example, you cannot call a setup workflow within a setup workflow, so you cannot do another setup process after path-filtering.

Also, you need to learn a new setup workflow syntax.

This orb solves these problems

• Provided as a Reusable config, so it is not affected by the setup workflow restrictions.
• It is provided as an orb, so if you are already familiar with orb, the learning cost is low.

There are also additional benefits

• The interface is created in a similar way to the path filter in github-actions, so if you are familiar with github actions, there is less learning curve.
• Simple implementation, so that user can copy its logic ealisy.

*This orb is not provided as an official circleci orb, so its use may be restricted in some orgs. However, since the mechanism of this orb is simple, you can do almost the same thing by creating a reusable config like the following

commands:
  path_filter:
    parameters:
      path:
        type: string
    steps:
      - run:
          name: filter by path
          command: |
            if [ ! $(git diff << pipeline.git.base_revision >>. << pipeline.git.revision >> --name-only | grep -E "<< parameters.path >>")]; then
              echo ci canceled due to no diff detected
              circleci-agent step halt
            fi

---

Resources

CircleCI Orb Registry Page - The official registry page of this orb for all versions, executors, commands, and jobs described.

CircleCI Orb Docs - Docs for using, creating, and publishing CircleCI Orbs.

How to Contribute

We welcome issues to and pull requests against this repository!

How to Publish An Update

1. Merge pull requests with desired changes to the main branch.
   • For the best experience, squash-and-merge and use Conventional Commit Messages.
2. Find the current version of the orb.
   • You can run circleci orb info mkusaka/path-filter | grep "Latest" to see the current version.
3. Create a new Release on GitHub.
   • Click "Choose a tag" and create a new semantically versioned tag. (ex: v1.0.0)
     • We will have an opportunity to change this before we publish if needed after the next step.
4. Click "+ Auto-generate release notes".
   • This will create a summary of all of the merged pull requests since the previous release.
   • If you have used Conventional Commit Messages it will be easy to determine what types of changes were made, allowing you to ensure the correct version tag is being published.
5. Now ensure the version tag selected is semantically accurate based on the changes included.
6. Click "Publish Release".
   • This will push a new tag and trigger your publishing pipeline on CircleCI.

TODO

• add filter branch option such as filters