[][crate]
[][copyright]
[](https://github.com/watchexec/gitignores/actions/workflows/check.yml)
# Gitignores
_GitHub’s collection of gitignores, embedded, automatically updated._
- **[API documentation][docs]**.
- [Public Domain][copyright] via CC0-1.0 (same as [source data][gh-gitignore]).
- **MSRV: 1.37.0** (increases are breaking changes)
- Doesn't require std.
- No dependencies.
- Works offline.
[crate]: https://lib.rs/crates/gitignores
[copyright]: https://creativecommons.org/publicdomain/zero/1.0/
[docs]: https://docs.rs/gitignores
[gh-gitignore]: https://github.com/github/gitignore
## Quick start
```toml
[dependencies]
gitignores = "1.0.0"
```
```rust
dbg!(gitignores::Root::Rust);
```
## API
Each gitignore is available as a variant of one of three enums:
```rust
(
gitignores::Root::Rust,
gitignores::Global::Emacs,
gitignores::Community::Racket,
)
```
The enums implement `Display` / `.to_string()`, which will return the contents of the gitignore
(only when the `std` feature is enabled):
```rust
println!("{}", gitignores::Root::Rust);
gitignores::Global::Emacs.to_string();
```
The enums also implement a `GitIgnore` trait:
```rust
trait GitIgnore {
/// The contents of the gitignore
///
/// Returns an empty string if the `no-contents` feature is enabled.
fn contents(self) -> &'static str;
/// The file name of the gitignore
fn file_name(self) -> &'static str;
/// The full path of the gitignore relative to repo root
fn file_path(self) -> &'static str;
/// The list of all included gitignores
fn list() -> Vec<&'static str>;
}
```
Finally, there is a constant with the git reference of the commit the crate was built from:
```rust
dbg!(gitignores::GIT_COMMIT_REF);
```
## Features
By default all gitignores are included, but you can customise this as granularily as you wish. To
get started with selecting your custom set, first disable the default features:
```toml
[dependencies.gitignores]
default-features = false
features = []
```
### Collections
| `root` | `/*.gitignore` | `Root::` |
| `global` | `/Global/**/*.gitignore` | `Global::` |
| `community` | `/community/**/*.gitignore` | `Community::` |
### Individual gitignores
Each gitignore can be enabled with the `<collection>-<name>` feature. Gitignores in subfolders have
the folder name prepended to the name, like `<collection>-<folder>-<name>`. All are lowercased.
### Other
- `no-contents`: omit the embedded file contents, leaving only the metadata.
- `std`: implement the `Display` trait on the enums.
### Examples
#### All globals and only Rust root
```toml
[dependencies.gitignores]
default-features = false
features = ["global", "root-rust"]
```
#### Some specific gitignores
```toml
[dependencies.gitignores]
default-features = false
features = ["community-racket", "global-emacs", "root-commonlisp"]
```
## Versioning
This crate respects semver!
It will bump the major version (breaking release) when:
- Gitignores disappear from a collection
- Gitignores move from a collection to another
- Gitignores are renamed
- The minimum required Rust version increases
It will bump the minor version when:
- New gitignores are added to a collection
It will bump the patch version when:
- Gitignore contents change
This repo [checks for updates](https://github.com/watchexec/gitignores/actions/workflows/update.yml)
to the [gitignore repo][gh-gitignore] once a day, and automatically releases if changes are found.
## License
The published crate ([`gitignores`][crate]) is generated from the data, which is CC0-1.0, and so it
itself is CC0-1.0 (Public Domain).
The generator code is [Apache 2.0 / MIT](updater/COPYRIGHT).