@actions/glob

What is @actions/glob?

@actions/glob is an npm package designed to help with file matching and globbing patterns in GitHub Actions workflows. It allows users to find files and directories using glob patterns, which can be useful for tasks such as file manipulation, testing, and deployment.

What are @actions/glob's main functionalities?

Basic File Matching

This feature allows you to match files based on a glob pattern. In this example, it matches all JavaScript files in the directory and its subdirectories.

const glob = require('@actions/glob');

async function run() {
  const pattern = '**/*.js';
  const globber = await glob.create(pattern);
  for await (const file of globber.globGenerator()) {
    console.log(file);
  }
}

run();

Excluding Files

This feature allows you to exclude certain files or directories from the matching process. In this example, it matches all JavaScript files except those in the node_modules directory.

const glob = require('@actions/glob');

async function run() {
  const pattern = '**/*.js';
  const excludePattern = '**/node_modules/**';
  const globber = await glob.create(pattern, { ignore: [excludePattern] });
  for await (const file of globber.globGenerator()) {
    console.log(file);
  }
}

run();

Matching Directories

This feature allows you to match directories based on a glob pattern. In this example, it matches all directories in the current directory and its subdirectories.

const glob = require('@actions/glob');

async function run() {
  const pattern = '**/';
  const globber = await glob.create(pattern);
  for await (const dir of globber.globGenerator()) {
    console.log(dir);
  }
}

run();

Other packages similar to @actions/glob

glob

The 'glob' package is a popular library for file matching using glob patterns. It is widely used in the Node.js ecosystem and offers similar functionality to @actions/glob, such as pattern matching and file exclusion. However, @actions/glob is specifically optimized for use in GitHub Actions workflows.

fast-glob

The 'fast-glob' package is another alternative for file matching using glob patterns. It is known for its performance and efficiency, especially with large sets of files. Compared to @actions/glob, 'fast-glob' offers faster matching and additional options for customization.

minimatch

The 'minimatch' package provides a minimalistic approach to glob pattern matching. It is a lightweight library that focuses on simplicity and ease of use. While it offers similar functionality to @actions/glob, it may not have the same level of integration with GitHub Actions workflows.

README

@actions/glob

Usage

Basic

You can use this package to search for files matching glob patterns.

Relative paths and absolute paths are both allowed. Relative paths are rooted against the current working directory.

const glob = require('@actions/glob');

const patterns = ['**/tar.gz', '**/tar.bz']
const globber = await glob.create(patterns.join('\n'))
const files = await globber.glob()

Opt out of following symbolic links

const glob = require('@actions/glob');

const globber = await glob.create('**', {followSymbolicLinks: false})
const files = await globber.glob()

Iterator

When dealing with a large amount of results, consider iterating the results as they are returned:

const glob = require('@actions/glob');

const globber = await glob.create('**')
for await (const file of globber.globGenerator()) {
  console.log(file)
}

Recommended action inputs

Glob follows symbolic links by default. Following is often appropriate unless deleting files.

Users may want to opt-out from following symbolic links for other reasons. For example, excessive amounts of symbolic links can create the appearance of very, very many files and slow the search.

When an action allows a user to specify input patterns, it is generally recommended to allow users to opt-out from following symbolic links.

Snippet from action.yml:

inputs:
  files:
    description: 'Files to print'
    required: true
  follow-symbolic-links:
    description: 'Indicates whether to follow symbolic links'
    default: true

And corresponding toolkit consumption:

const core = require('@actions/core')
const glob = require('@actions/glob')

const globOptions = {
  followSymbolicLinks: core.getInput('follow-symbolic-links').toUpper() !== 'FALSE'
}
const globber = glob.create(core.getInput('files'), globOptions)
for await (const file of globber.globGenerator()) {
  console.log(file)
}

Patterns

Glob behavior

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

With the following behaviors:

• File names that begin with . may be included in the results
• Case insensitive on Windows
• Directory separator / and \ 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.