glob

Search for files matching glob patterns with support for returning matching deleted git tracked files, omits files and directories specified in the projects .gitignore, and excludes the .git and node_modules folders except explicitly specified.

Table of Contents

• Usage
• Inputs
• Outputs
• Path filtering
  • minimatch options
    • Enabled
    • Optionally enabled
    • Disabled
  • Pattern Gotcha
• Patterns
  • Glob behaviour
  • Tilde expansion
  • Comments
  • Exclude patterns
  • Escaping
• Credits
• Report Bugs
• Contributors ✨

Usage

Warning

• Ensure that subdirectory patterns are prefixed with **/ as **.yml only matches yml files in the top level directory and should be replaced with **/*.yml.
• All multi-line string patterns are specified without quotes. See: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet for more examples of filter patterns

...
    steps:
      - uses: actions/checkout@v4

      - name: Glob match
        uses: tj-actions/glob@v22
        id: glob
        with:
          files: |
            *.md
            **/*.yaml
            !action.yml
            **/rebase.yml

      - name: Show all matching files
        run: |
          echo "${{ steps.glob.outputs.paths }}"
        # Outputs: .github/workflows/rebase.yml .github/workflows/sync-release-version.yml .github/workflows/test.yml...

Inputs

- uses: tj-actions/glob@v22
  id: glob
  with:
    # Specify a base ref used 
    # for comparing changes, when `include-deleted-files` 
    # is set to `true` 
    # Type: string
    # Default: "${{ github.event.pull_request.base.ref }}"
    base-ref: ''

    # Specify a base commit SHA 
    # used for comparing changes, when 
    # `include-deleted-files` is set to `true` 
    # Type: string
    base-sha: ''

    # Specify a diff string `..` 
    # or `...` used for comparing 
    # changes, when `include-deleted-files` is set 
    # to `true` 
    # Type: string
    diff: ''

    # Excluded file patterns (optionally include `!` before the file pattern or it would be prepended) 
    # Type: string
    excluded-files: ''

    # Source file to populate the 
    # `excluded-files` input 
    # Type: string
    excluded-files-from-source-file: ''

    # Separator used to split the 
    # `excluded-files-from-source-file` input 
    # Type: string
    # Default: "\n"
    excluded-files-from-source-file-separator: ''

    # Separator used to split the 
    # `excluded-files` input 
    # Type: string
    # Default: "\n"
    excluded-files-separator: ''

    # File patterns
    # Type: string
    files: ''

    # Source file to populate the 
    # `files` input 
    # Type: string
    files-from-source-file: ''

    # Separator used to split the 
    # `files-from-source-file` input 
    # Type: string
    # Default: "\n"
    files-from-source-file-separator: ''

    # Separator used to split the 
    # `files` input 
    # Type: string
    # Default: "\n"
    files-separator: ''

    # Indicates whether to follow symbolic 
    # links 
    # Type: boolean
    # Default: "true"
    follow-symbolic-links: ''

    # Specify a boolean indicating a 
    # PR from a fork is 
    # used for comparing changes, when 
    # `include-deleted-files` is set to `true` 
    # Type: string
    # Default: "${{ github.event.pull_request.head.repo.fork }}"
    head-repo-fork: ''

    # Include all matching deleted files
    # Type: boolean
    # Default: "false"
    include-deleted-files: ''

    # Indicates whether to include matched 
    # directories 
    # Type: boolean
    # Default: "true"
    match-directories: ''

    # Indicates whether to match files 
    # in `.gitignore` 
    # Type: boolean
    # Default: "false"
    match-gitignore-files: ''

    # Indicates whether to read `.gitignore`. 
    # The `.gitignore` file will be 
    # ignored if set to `false`. 
    # Overrides `match-gitignore-files` 
    # Type: boolean
    # Default: "true"
    read-gitignore: ''

    # Escape special characters of filenames 
    # used in the `paths` output 
    # Type: boolean
    # Default: "true"
    safe-output: ''

    # Separator used for the paths 
    # output. 
    # Type: string
    # Default: " "
    separator: ''

    # Specify a current commit SHA 
    # used for comparing changes, when 
    # `include-deleted-files` is set to `true` 
    # Type: string
    # Default: "${{ github.sha }}"
    sha: ''

    # Strip the `$GITHUB_WORKSPACE` from the 
    # `paths` output 
    # Type: boolean
    # Default: "true"
    strip-top-level-dir: ''

    # Provide a path that is 
    # relative to `$GITHUB_WORKSPACE` for identifying 
    # the repository. 
    # Type: string
    # Default: "."
    working-directory: ''

Outputs

OUTPUT	TYPE	DESCRIPTION
has-custom-patterns	string	Indicates whether at least one pattern was provided
paths	string	List of filtered paths using the specified patterns and separator
paths-output-file	string	List of filtered paths using the specified patterns and separator stored in a temporary file

Path filtering

File and Directory patterns are evaluted using minimatch with the help of the @actions/glob package.

minimatch options

Enabled

• dot
• nocomment
• noext
• nonegate: This is handled by the @actions/glob package.

Optionally enabled

• nocase: Enabled for windows

Disabled

• nobrace: Ensures that brace or brace sets can be used.

Pattern Gotcha

The ** pattern in minimatch matches any number of directories and files recursively, but it must be followed by a directory separator (/ on Unix-like systems) to be effective. If you want to match all files with the .js extension in a directory and its subdirectories, you should use the **/*.js pattern as opposed to **.js

Patterns

Glob behaviour

Patterns *, ?, [...], and ** (globstar) are supported.

With the following behaviours:

• File names that begin with . may be included in the results
• Case insensitive on Windows
• Directory separators / and \ are both supported on Windows

Tilde expansion

Supports basic tilde expansion, for current user HOME replacement only.

Example:

• ~ may expand to /Users/johndoe
• ~/foo may expand to /Users/johndoe/foo

Comments

Patterns that begin with # are treated as comments.

Exclude patterns

Leading ! changes the meaning of an include pattern to exclude.

Multiple leading ! flips the meaning.

Escaping

Wrapping special characters in [] can be used to escape literal glob characters in a file name. For example the literal file name hello[a-z] can be escaped as hello[[]a-z].

On Linux/macOS \ is also treated as an escape character.

• Free software: MIT license

If you feel generous and want to show some extra appreciation:

Credits

This package was created with Cookiecutter using cookiecutter-action

• @actions/glob
• @actions/core
• @actions/exec
• @actions/github
• @actions/io

Report Bugs

Report bugs at https://github.com/tj-actions/glob/issues.

If you are reporting a bug, please include the following:

• Your operating system name and version.
• Any details about your workflow that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Misha Kaletsky 💻

Raphael Boidol 📖

This project follows the all-contributors specification. Contributions of any kind welcome!