123 lines
5 KiB
Markdown
123 lines
5 KiB
Markdown
|
|
# Make Nix precisely emulate gitignore
|
|
|
|
This goal of this project lets you include local sources in your [Nix](https://builtwithnix.org) projects,
|
|
while taking [gitignore files](https://git-scm.com/docs/gitignore) into account.
|
|
|
|
Note that although this project does a good job at emulating git's behavior, it is not the same implementation!
|
|
|
|
# Installation
|
|
|
|
## Recommended with Niv
|
|
```
|
|
nix-env -iA niv -f https://github.com/nmattia/niv/tarball/master
|
|
niv init
|
|
niv add hercules-ci/gitignore.nix
|
|
```
|
|
|
|
## Plain Nix way
|
|
|
|
```nix
|
|
let
|
|
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;
|
|
in
|
|
<your nix expression>
|
|
```
|
|
|
|
Or using only `nixpkgs/lib` and only evaluation-time fetching:
|
|
|
|
```nix
|
|
import (builtins.fetchTarball "https://github.com/hercules-ci/gitignore.nix/archive/000000000000000000000000000000000000000000000000000".tar.gz") {
|
|
lib = import (builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/000000000000000000000000000000000000000000000000000".tar.gz" + "/lib");
|
|
}
|
|
```
|
|
|
|
# Usage
|
|
|
|
```nix
|
|
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`](https://github.com/NixOS/nixpkgs/blob/d1bb36d5cb5b78111f799eb26f5f17e5979bc746/lib/sources.nix#L35-L67) 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](docs/gitignoreFilter.md) for an example.
|
|
|
|
# Features
|
|
|
|
- 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
|
|
|
|
## Comparison
|
|
|
|
| Feature \ Implementation | cleanSource | [siers](https://github.com/siers/nix-gitignore) | [siers recursive](https://github.com/siers/nix-gitignore) | [icetan](https://github.com/icetan/nix-git-ignore-source) | [Profpatsch](https://github.com/Profpatsch/nixperiments/blob/master/filterSourceGitignore.nix) | [numtide](https://github.com/numtide/nix-gitignore) | 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 | ✔️ | ✔️ | ✔️ | | | |
|
|
<!-- |No traversal of ignored dirs | - | ✔️ |✔️ ?| ✔️ |✔️ ?|✔️ ?| ✔️ ? -->
|
|
|
|
| | Legend |
|
|
|---|-------------------------------------|
|
|
|✔️ | 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!
|
|
|
|
# Security
|
|
|
|
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.
|
|
|
|
# Contributing
|
|
|
|
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.
|
|
|
|
# Thanks
|
|
|
|
A great shoutout to @siers for writing the intial test suite and rule translation code!
|