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

> Learn how to use git ignore rules with act --use-gitignore to exclude files from Docker containers in your GitHub Actions workflows with nektos/act. Improve your CI/CD.

- Repository: [nektos/act](https://github.com/nektos/act)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/pkg/container/docker_run.go)** conditionally creates the gitignore matcher using `gitignore.ReadPatterns`
4. **[`pkg/filecollector/file_collector.go`](https://github.com/nektos/act/blob/main/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):

```bash
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:

```bash
act --use-gitignore=false

```

### Programmatic Matcher Creation

The following simplified Go excerpt from [`pkg/container/docker_run.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_run.go) demonstrates how the matcher is instantiated when the flag is enabled:

```go
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`](https://github.com/nektos/act/blob/main/pkg/filecollector/file_collector.go), the `CollectFiles` method implements the filtering decision:

```go
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`](https://github.com/nektos/act/blob/main/cmd/root.go)**: Declares the `--use-gitignore` CLI flag and maps it to `Config.UseGitIgnore`
- **[`pkg/runner/runner.go`](https://github.com/nektos/act/blob/main/pkg/runner/runner.go)**: Stores the `UseGitIgnore` field in the runner configuration struct
- **[`pkg/container/docker_run.go`](https://github.com/nektos/act/blob/main/pkg/container/docker_run.go)**: Reads `.gitignore` patterns and constructs the matcher when the flag is enabled
- **[`pkg/filecollector/file_collector.go`](https://github.com/nektos/act/blob/main/pkg/filecollector/file_collector.go)**: Executes the directory walk and applies ignore rules via the `Ignorer` interface
- **[`pkg/runner/action.go`](https://github.com/nektos/act/blob/main/pkg/runner/action.go)** and **[`pkg/runner/step_action_remote.go`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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`](https://github.com/nektos/act/blob/main/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.