How to Use Git Ignore Rules with act --use-gitignore

The --use-gitignore flag in nektos/act controls whether files matching .gitignore patterns are excluded when copying repository files into Docker containers for GitHub Actions workflows.

When running GitHub Actions locally with act, the tool must copy your repository into Docker containers to execute workflows. By default, the act --use-gitignore flag is set to true, which automatically excludes any paths listed in your .gitignore file from being staged inside the action environment.

Understanding the --use-gitignore Implementation

CLI Flag Declaration and Configuration

In cmd/root.go, the --use-gitignore flag is declared as a boolean option defaulting to true. This value is stored in the runner configuration struct defined in pkg/runner/runner.go as Config.UseGitIgnore. This configuration propagates through the runner initialization to determine whether the Docker container preparation should respect ignore patterns.

Pattern Matching with go-git

The filtering logic executes in pkg/container/docker_run.go. When the dockerRun function receives useGitIgnore as true, it invokes gitignore.ReadPatterns from the go-git library to parse the repository's .gitignore file. This generates a gitignore.Matcher object capable of testing paths against standard Git ignore patterns.

File Collection and Filtering

The FileCollector struct in pkg/filecollector/file_collector.go receives the matcher via its Ignorer field. During the directory traversal performed by CollectFiles, each path is validated against fc.Ignorer.Match(split, fi.IsDir()). When the matcher returns true:

• For directories: The function returns filepath.SkipDir, pruning the entire subtree from the copy operation
• For files: The function returns nil, silently omitting the file from the container

Execution Flow

The end-to-end data flow follows this path through the nektos/act source code:

1. cmd/root.go parses the CLI flag into Config.UseGitIgnore
2. runner.New passes the configuration to the Docker runtime
3. pkg/container/docker_run.go conditionally creates the gitignore matcher using gitignore.ReadPatterns
4. pkg/filecollector/file_collector.go applies the matcher during CollectFiles to filter the file tree

When --use-gitignore is explicitly set to false, the matcher remains nil, causing act to copy all files—including those listed in .gitignore—mirroring the tool's historical behavior before this flag was introduced.

Usage Examples

Running with Default Git Ignore Behavior

To run workflows while respecting .gitignore rules (the default behavior):

act -P ubuntu-latest=nektos/act-environments-ubuntu:18.04

Disabling Git Ignore Filtering

To include ignored files in the container—useful for testing build artifacts or temporary files:

act --use-gitignore=false

Programmatic Matcher Creation

The following simplified Go excerpt from pkg/container/docker_run.go demonstrates how the matcher is instantiated when the flag is enabled:

var ignorer gitignore.Matcher
if useGitIgnore {
    ps, _ := gitignore.ReadPatterns(polyfill.New(osfs.New(srcPath)), nil)
    ignorer = gitignore.NewMatcher(ps)
}
fc := &filecollector.FileCollector{
    Ignorer: ignorer,
    SrcPath: srcPath,
    // …
}

Directory Pruning Logic

Inside pkg/filecollector/file_collector.go, the CollectFiles method implements the filtering decision:

if err != nil && fc.Ignorer != nil && fc.Ignorer.Match(split, fi.IsDir()) {
    if fi.IsDir() {
        return filepath.SkipDir   // skip whole ignored directory
    }
    return nil                    // skip ignored file
}

Key Source Files

• cmd/root.go: Declares the --use-gitignore CLI flag and maps it to Config.UseGitIgnore
• pkg/runner/runner.go: Stores the UseGitIgnore field in the runner configuration struct
• pkg/container/docker_run.go: Reads .gitignore patterns and constructs the matcher when the flag is enabled
• pkg/filecollector/file_collector.go: Executes the directory walk and applies ignore rules via the Ignorer interface
• pkg/runner/action.go and pkg/runner/step_action_remote.go: Invoke CopyDir operations that respect the UseGitIgnore setting when staging local files

Summary

• The --use-gitignore flag defaults to true, automatically excluding .gitignore patterns from Docker container copies
• Setting --use-gitignore=false copies all files, including those historically ignored, which is useful for debugging artifact generation
• The implementation leverages the go-git library's gitignore package in pkg/container/docker_run.go for pattern parsing
• File filtering occurs in FileCollector.CollectFiles, which uses filepath.SkipDir to efficiently prune entire ignored directories
• This mechanism prevents sensitive files, build artifacts, and temporary data from entering the GitHub Actions runtime environment

Frequently Asked Questions

What is the default value of --use-gitignore in act?

The default value is true. Unless explicitly disabled, act will always respect .gitignore patterns when copying files into action containers, preventing ignored files from being visible to your workflows.

Why would I disable --use-gitignore?

Disable this flag when testing workflows that depend on files normally excluded by .gitignore, such as compiled binaries in dist/, local environment files, or temporary test data generated during development but not committed to the repository.

How does act parse .gitignore patterns?

According to the nektos/act source code, the tool uses gitignore.ReadPatterns from the go-git library within pkg/container/docker_run.go. This ensures pattern parsing remains consistent with standard Git behavior, supporting negation patterns, directory-specific rules, and wildcard syntax.

Does --use-gitignore affect remote actions?

The flag primarily controls how act copies your local working directory into containers. While pkg/runner/step_action_remote.go invokes the copy logic for action steps, the --use-gitignore setting applies to your repository's files being staged, not the internal file operations of remote actions being checked out separately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}