|
| 1 | +<div align="center"> |
| 2 | + |
| 3 | +# gitconfig |
| 4 | + |
| 5 | +[![Build Status][ci/badge]][ci/url] |
| 6 | +[![Go Reference][godoc/badge]][godoc/url] |
| 7 | +[![MIT License][license/badge]][license/url] |
| 8 | + |
| 9 | +[Documentation][godoc/url] - [Issues][issues] - [Compatibility](docs/COMPATIBILITY.md) |
| 10 | + |
| 11 | +</div> |
| 12 | + |
| 13 | +`gitconfig` is a Go library to read and edit git configuration the way git |
| 14 | +does. |
| 15 | + |
| 16 | +- **same result as git**: same parsing, same value types (bool, int, path), |
| 17 | + tested against the `git` binary. |
| 18 | +- **every source**: system, global, local and worktree files, `GIT_CONFIG_*` |
| 19 | + variables, `include` and `includeIf`. Each value says which file and line |
| 20 | + it came from. |
| 21 | +- **lossless edits**: an edit changes only the lines it touches; comments |
| 22 | + and layout are kept. |
| 23 | +- **safe alongside git**: writes take git's lock, so a concurrent `git config` |
| 24 | + and this library never overwrite each other. |
| 25 | +- **safe on hostile repositories**: untrusted repositories are refused, as |
| 26 | + git refuses them (`safe.directory`). |
| 27 | + |
| 28 | +Where this library deliberately differs from git, and why, is listed in |
| 29 | +[COMPATIBILITY.md](docs/COMPATIBILITY.md). |
| 30 | + |
| 31 | +## Installation |
| 32 | + |
| 33 | +``` |
| 34 | +go get github.com/git-bug/gitconfig |
| 35 | +``` |
| 36 | + |
| 37 | +## Example |
| 38 | + |
| 39 | +```go |
| 40 | +package main |
| 41 | + |
| 42 | +import ( |
| 43 | + "fmt" |
| 44 | + "log" |
| 45 | + |
| 46 | + "github.com/git-bug/gitconfig" |
| 47 | +) |
| 48 | + |
| 49 | +func main() { |
| 50 | + // Find the repository and where git reads its configuration from. |
| 51 | + env, err := gitconfig.Discover(".") |
| 52 | + if err != nil { |
| 53 | + log.Fatal(err) // ErrUntrusted, as git refuses it |
| 54 | + } |
| 55 | + |
| 56 | + // Read the effective configuration: system, global, local, worktree |
| 57 | + // and command scopes, with includes, as git would use it. |
| 58 | + cfg, err := env.Load() |
| 59 | + if err != nil { |
| 60 | + log.Fatal(err) |
| 61 | + } |
| 62 | + if e, ok := cfg.Get("user.name"); ok { |
| 63 | + fmt.Printf("user.name = %s (%s)\n", e.Value, e.Origin.File) |
| 64 | + } |
| 65 | + |
| 66 | + // Edit the repository's config. Comments and layout are kept, and the |
| 67 | + // file is not touched if the value is already set. |
| 68 | + err = env.UpdateScope(gitconfig.ScopeLocal, func(f *gitconfig.File) error { |
| 69 | + return f.Set("core.editor", "vim") |
| 70 | + }) |
| 71 | + if err != nil { |
| 72 | + log.Fatal(err) |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +## License |
| 78 | + |
| 79 | +MIT, see [LICENSE](LICENSE). This is a clean room implementation: no code is |
| 80 | +derived from git, see [CLEAN-ROOM.md](docs/CLEAN-ROOM.md). It is meant to interoperate with git. |
| 81 | + |
| 82 | +[ci/badge]: https://github.com/git-bug/gitconfig/actions/workflows/test.yml/badge.svg |
| 83 | +[ci/url]: https://github.com/git-bug/gitconfig/actions/workflows/test.yml |
| 84 | +[godoc/badge]: https://pkg.go.dev/badge/github.com/git-bug/gitconfig.svg |
| 85 | +[godoc/url]: https://pkg.go.dev/github.com/git-bug/gitconfig |
| 86 | +[license/badge]: https://img.shields.io/badge/license-MIT-blue.svg |
| 87 | +[license/url]: LICENSE |
| 88 | +[issues]: https://github.com/git-bug/gitconfig/issues |
0 commit comments