examples

gitconfig Examples

This directory contains practical examples demonstrating how to use the gitconfig library.

Examples

1. Basic Read

Demonstrates reading configuration values from git config using the simple Config API.

Topics:

• Loading a config file
• Reading string values
• Handling missing keys

Run:

go run -tags=examples examples/01-basic-read.go

2. Write and Persist

Shows how to modify configuration values and persist changes back to disk.

Topics:

• Setting configuration values
• Persistence to file
• Verifying changes on disk

Run:

go run -tags=examples examples/02-write-persist.go

3. Understanding Scopes

Demonstrates the configuration scope hierarchy and how gitconfig resolves values across scopes.

Topics:

• System-wide config
• User config
• Local repository config
• Environment variables
• Scope priority/precedence

Run:

go run -tags=examples examples/03-scopes.go

4. Custom Paths

Shows how to work with custom configuration file paths instead of default Git locations.

Topics:

• Custom config paths
• Non-standard locations
• Loading from arbitrary files

Run:

go run -tags=examples examples/04-custom-paths.go

5. Error Handling

Demonstrates proper error handling patterns when working with gitconfig.

Topics:

• Parse errors
• File not found
• Permission errors
• Invalid key formats

Run:

go run -tags=examples examples/05-error-handling.go

6. Include Files

Shows how gitconfig handles include directives for modular configuration.

Topics:

• Including other config files
• Conditional includes
• External config organization

Run:

go run -tags=examples examples/06-includes.go

Prerequisites

Before running these examples, ensure you have Go 1.24 or later installed:

go version

How to Use These Examples

1. Each example is a standalone Go file
2. Run with go run -tags=examples examples/<number>-<name>.go
3. Some examples create temporary files for demonstration
4. Review the source code to understand each pattern
5. Modify and experiment to learn more

Learning Path

Recommended order for learning:

1. Start with 01-basic-read to understand basic usage
2. Move to 02-write-persist to learn mutation
3. Learn scope hierarchy with 03-scopes
4. Explore flexibility with 04-custom-paths
5. Master error handling with 05-error-handling
6. Build modular configs with 06-includes

Common Patterns

Reading a Single Value

cfg, _ := gitconfig.NewConfig("path/to/.git/config")
value, ok := cfg.Get("user.name")
if ok {
    fmt.Println("Name:", value)
}

Setting and Saving

cfg, _ := gitconfig.NewConfig("path/to/.git/config")
cfg.Set("core.editor", "vim")
_ = cfg.String()  // Persist changes

Working with All Scopes

cfg, _ := gitconfig.NewConfigs()  // Load all scopes
value := cfg.Get("user.name")      // Respects scope priority
cfg.SetLocal("core.pager", "less") // Write to local only

More Information

• README - Overview and quick start
• ARCHITECTURE - Design and structure
• CONTRIBUTING - How to contribute
• godoc - API documentation