gitbutlerapp/gitbutler · error

Refusing to read Git-ignored path

Error message

Refusing to read Git-ignored path '{}'

What it means

ensure_not_ignored checks the repository's exclude/ignore rules (gitignore, excludes, global/config includes) and refuses to read files that Git would ignore, via read_worktree_file. This prevents the app from exposing files users deliberately excluded from the repo.

Solutions

1. Read the file directly with std::fs if intentional (bypassing the git-aware API) with proper user consent.
2. Remove/adjust the .gitignore rule covering the path (e.g. add a negation !pattern).
3. Track the file in the index (git add -f) if it should be part of the project.

Example fix

// before
read_file_from_workspace(project, ".env") // ignored
// after (allowed via negation in .gitignore)
!.env
// then
read_file_from_workspace(project, ".env")

let excluded = repo
    .excludes(Some(&workdir.join(".gitignore")))?
    .pattern_matching_relative_path(rel_path, Default::default())?
    .is_some();
if excluded { return Err("path is git-ignored"); }

match result {
    Err(e) if e.to_string().contains("Git-ignored path") => {
        // read via std::fs with explicit user consent, or skip
    }
    other => other,
}

When it happens

Trigger: Calling read_worktree_file for a path matched by .gitignore/.git/info/exclude/global ignores when the path isn't present as a worktree entry (the index fast-path didn't apply), e.g. ".env", "node_modules/x", "build/out.js".

Common situations: Trying to view .env or secrets files; reading files in ignored build or dependency directories; recently-added ignore rules covering files that were previously readable.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• Path to read from at
• Refusing to read Git metadata path
• Refusing to read ' ' from commit as it's not relative to…
• another pre-commit hook is already using the repository…
• askpass broker must be initialized

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/29a436f7c7b66dc4. Report an issue: GitHub.

Appendix: source

Thrown at crates/gitbutler-repo/src/commands.rs:485

        &index,
        None,
        gix::worktree::stack::state::ignore::Source::WorktreeThenIdMappingIfNotSkipped,
    )?;
    if !excludes.at_path(relative_path, None)?.is_excluded() {
        return Ok(());
    }
    // On a case-insensitive filesystem `Tracked` names the tracked file
    // `tracked`; retry the index lookup case-insensitively before refusing.
    if repo.filesystem_options()?.ignore_case {
        let icase_accelerator = index.prepare_icase_backing();
        if index
            .entry_by_path_icase(relative_path_bstr.as_ref(), true, &icase_accelerator)
            .is_some()
        {
            return Ok(());
        }
    }
    bail!(
        "Refusing to read Git-ignored path '{}'",
        relative_path.display()
    );
}

View on GitHub (pinned to 58e5313667)