Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Make Nix precisely emulate gitignore

This goal of this project lets you include local sources in your Nix projects, while taking gitignore files into account.

Note that although this project does a good job at emulating git's behavior, it is not the same implementation!


Recommended with Niv

nix-env -iA niv -f
niv init
niv add hercules-ci/gitignore.nix

Plain Nix way

  gitignoreSrc = pkgs.fetchFromGitHub { 
    owner = "hercules-ci";
    repo = "gitignore.nix";
    # put the latest commit sha of gitignore Nix library here:
    rev = "";
    # use what nix suggests in the mismatch message here:
    sha256 = "sha256:0000000000000000000000000000000000000000000000000000";
  inherit (import gitignoreSrc { inherit (pkgs) lib; }) gitignoreSource;
  <your nix expression>

Or using only nixpkgs/lib and only evaluation-time fetching:

import (builtins.fetchTarball "".tar.gz") {
  lib = import (builtins.fetchTarball "".tar.gz" + "/lib");


mkDerivation {
  name = "hello";
  src = gitignoreSource ./vendored/hello;
gitignoreSource :: path -> path

Returns result of cleanSourceWith, usable as a path but also composable.

gitignoreFilter :: path -> (path -> type -> bool)

f = gitignoreFilter path

Parentheses in the type emphasize that a partial application memoizes the git metadata. You can use Nixpkgs' cleanSourceWith to compose with other filters (by logical and) or to set a name.

path: a path being the root or a subdirectory of a local git repository

f: a function that returns false for files that should be ignored according to gitignore rules, but only for paths at or below path.

See gitignoreFilter for an example.


  • Reads parent gitignores even if only pointed at a subdirectory
  • Source hashes only change when output changes
  • Not impacted by large or inaccessible ignored directories
  • Composes with cleanSourceWith
  • Reads user git configuration; no need to bother your team with your tool config.
  • Also works with restrict-eval enabled (if avoiding fetchFromGitHub)
  • No import from derivation ("IFD")
  • Name and hash are not sensitive to checkout location


Feature \ Implementation cleanSource siers siers recursive icetan Profpatsch numtide this project
Ignores .git ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
No special Nix configuration ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
No import from derivation ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Uses subdirectory gitignores ✔️ ✔️ ✔️
Uses parent gitignores ✔️ ? ✔️
Uses user gitignores ✔️ ✔️
Has a test suite ✔️ ✔️ ✔️ ? ✔️
Works with restrict-eval / Hydra ✔️ ✔️ ✔️ ✔️ ✔️
Descends into submodule correctly ? ? ? ? ✔️ ? ? #8
Included in nixpkgs ✔️ ✔️ ✔️
✔️ Supported
✔️ ? Probably supported
Not supported
? Probably not supported
- Not applicable or depends

Please open a PR if you've found another feature, determined any of the '?' or found an inaccuracy!


Files not matched by gitignore rules will end up in the Nix store, which is readable by any process.

gitignore.nix does not yet understand git-crypt's metadata, so don't call gitignoreSource on directories containing such secrets or their parent directories. This applies to any Nix function that uses the builtins.path or builtins.filterSource functions.


This project isn't perfect (yet) so please submit test cases and fixes as pull requests. Before doing anything drastic, it's a good idea to open an issue first to discuss and optimize the approach.


A great shoutout to @siers for writing the intial test suite and rule translation code!


Nix function for filtering local git sources





No releases published


No packages published