gitconfig

Documentation

Overview

Package gitconfig implements a pure Go parser of Git SCM config files. The support is currently not matching git exactly, e.g. includes, urlmatches and multivars are currently not supported. And while we try to preserve the original file a much as possible when writing we currently don't exactly retain (insignificant) whitespaces.

The reference for this implementation is https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-config.html

Usage

Use gitconfig.LoadAll with an optional workspace argument to process configuration input from these locations in order (i.e. the later ones take precedence):

• `system` - /etc/gitconfig
• `global` - `$XDG_CONFIG_HOME/git/config` or `~/.gitconfig`
• `local` - `<workdir>/config`
• `worktree` - `<workdir>/config.worktree`
• `command` - GIT_CONFIG_{COUNT,KEY,VALUE} environment variables

Note: We do not support parsing command line flags directly, but one can use the SetEnv method to set flags from the command line in the config.

Customization

`gopass` and other users of this package can easily customize file and environment names by utilizing the exported variables from the Configs struct:

• SystemConfig
• GlobalConfig (can be set to the empty string to disable)
• LocalConfig
• WorktreeConfig
• EnvPrefix

Note: For tests users will want to set `NoWrites = true` to avoid overwriting their real configs.

Example

import "github.com/gopasspw/gopass/pkg/gitconfig"

func main() {
	cfg := gitconfig.New()
	cfg.SystemConfig = "/etc/gopass/config"
	cfg.GlobalConfig = ""
	cfg.EnvPrefix = "GOPASS_CONFIG"
	cfg.LoadAll(".")
	_ = cfg.Get("core.notifications")
}

Versioning and Compatibility

We aim to support the latest stable release of Git only. Currently we do not provide any backwards compatibility and semantic versioning. Once this package has become mostly feature complete and if there is interest from other projects in using it we may choose to move it to it's own repository and start proper versioning.

Known limitations

* Worktree support is only partial

Index

• type Config
  • func LoadConfig(fn string) (*Config, error)
  • func LoadConfigFromEnv(envPrefix string) *Config
  • func NewFromMap(data map[string]string) *Config
  • func ParseConfig(r io.Reader) *Config
  • func (c *Config) Get(key string) (string, bool)
  • func (c *Config) GetAll(key string) ([]string, bool)
  • func (c *Config) IsEmpty() bool
  • func (c *Config) IsSet(key string) bool
  • func (c *Config) Set(key, value string) error
  • func (c *Config) Unset(key string) error
• type Configs
  • func New() *Configs
  • func (cs *Configs) Get(key string) string
  • func (cs *Configs) GetAll(key string) []string
  • func (cs *Configs) GetGlobal(key string) string
  • func (cs *Configs) GetLocal(key string) string
  • func (cs *Configs) HasGlobalConfig() bool
  • func (cs *Configs) IsSet(key string) bool
  • func (cs *Configs) Keys() []string
  • func (cs *Configs) List(prefix string) []string
  • func (cs *Configs) ListSections() []string
  • func (cs *Configs) ListSubsections(wantSection string) []string
  • func (cs *Configs) LoadAll(workdir string) *Configs
  • func (cs *Configs) Reload()
  • func (cs *Configs) SetEnv(key, value string) error
  • func (cs *Configs) SetGlobal(key, value string) error
  • func (cs *Configs) SetLocal(key, value string) error
  • func (cs *Configs) String() string
  • func (cs *Configs) UnsetGlobal(key string) error
  • func (cs *Configs) UnsetLocal(key string) error

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config is a single parsed config file. It contains a reference of the input file, if any. It can only be populated only by reading the environment variables.

func LoadConfig

func LoadConfig(fn string) (*Config, error)

LoadConfig tries to load a gitconfig from the given path.

func LoadConfigFromEnv

func LoadConfigFromEnv(envPrefix string) *Config

LoadConfigFromEnv will try to parse an overlay config from the environment variables. If no environment variables are set the resulting config will be valid but empty. Either way it will not be writeable.

func NewFromMap

func NewFromMap(data map[string]string) *Config

NewFromMap allows creating a new preset config from a map.

func ParseConfig

func ParseConfig(r io.Reader) *Config

ParseConfig will try to parse a gitconfig from the given io.Reader. It never fails. Invalid configs will be silently rejected.

func (*Config) Get

func (c *Config) Get(key string) (string, bool)

Get returns the first value of the key.

func (*Config) GetAll

func (c *Config) GetAll(key string) ([]string, bool)

GetAll returns all values of the key.

func (*Config) IsEmpty

func (c *Config) IsEmpty() bool

IsEmpty returns true if the config is empty (typically a newly initialized config, but still unused). Since gitconfig.New() already sets the global path to the globalConfigFile() one, we cannot rely on the path being set to checki this. We need to check the raw length to be sure it wasn't just the default empty config struct.

func (*Config) IsSet

func (c *Config) IsSet(key string) bool

IsSet returns true if the key was set in this config.

func (*Config) Set

func (c *Config) Set(key, value string) error

Set updates or adds a key in the config. If possible it will also update the underlying config file on disk.

func (*Config) Unset

func (c *Config) Unset(key string) error

Unset deletes a key.

type Configs

type Configs struct {
	Preset *Config

	Name           string
	SystemConfig   string
	GlobalConfig   string
	LocalConfig    string
	WorktreeConfig string
	EnvPrefix      string
	NoWrites       bool
	// contains filtered or unexported fields
}

Configs is a container for a config "view" that is composed of several different config objects. The intention is for the ones with a wider scope to provide defaults so those with a more narrow scope then only have to override what they are interested in.

func New

func New() *Configs

func (*Configs) Get

func (cs *Configs) Get(key string) string

Get returns the value for the given key from the first location that is found. Lookup order: env, worktree, local, global, system and presets.

func (*Configs) GetAll

func (cs *Configs) GetAll(key string) []string

GetAll returns all values for the given key from the first location that is found. See the description of Get for more details.

func (*Configs) GetGlobal

func (cs *Configs) GetGlobal(key string) string

GetGlobal specifically ask the per-user (global) config for a key.

func (*Configs) GetLocal

func (cs *Configs) GetLocal(key string) string

GetLocal specifically asks the per-directory (local) config for a key.

func (*Configs) HasGlobalConfig

func (cs *Configs) HasGlobalConfig() bool

HasGlobalConfig indicates if a per-user config can be found.

func (*Configs) IsSet

func (cs *Configs) IsSet(key string) bool

IsSet returns true if this key is set in any of our configs.

func (*Configs) Keys

func (cs *Configs) Keys() []string

Keys returns a list of all keys from all available scopes. Every key has section and possibly a subsection. They are separated by dots. The subsection itself may contain dots. The final key name and the section MUST NOT contain dots.

Examples

• remote.gist.gopass.pw.path -> section: remote, subsection: gist.gopass.pw, key: path
• core.timeout -> section: core, key: timeout

func (*Configs) List

func (cs *Configs) List(prefix string) []string

List returns all keys matching the given prefix. The prefix can be empty, then this is identical to Keys().

func (*Configs) ListSections

func (cs *Configs) ListSections() []string

ListSections returns a sorted list of all sections.

func (*Configs) ListSubsections

func (cs *Configs) ListSubsections(wantSection string) []string

ListSubsections returns a sorted list of all subsections in the given section.

func (*Configs) LoadAll

func (cs *Configs) LoadAll(workdir string) *Configs

LoadAll tries to load all known config files. Missing or invalid files are silently ignored. It never fails. The workdir is optional. If non-empty this method will try to load a local config from this location.

func (*Configs) Reload

func (cs *Configs) Reload()

Reload will reload the config(s) from disk.

func (*Configs) SetEnv

func (cs *Configs) SetEnv(key, value string) error

SetEnv sets (or adds) a key in the per-process (env) config. Useful for persisting flags during the invocation.

func (*Configs) SetGlobal

func (cs *Configs) SetGlobal(key, value string) error

SetGlobal sets (or adds) a key only in the per-user (global) config.

func (*Configs) SetLocal

func (cs *Configs) SetLocal(key, value string) error

SetLocal sets (or adds) a key only in the per-directory (local) config.

func (*Configs) String

func (cs *Configs) String() string

String implements fmt.Stringer.

func (*Configs) UnsetGlobal

func (cs *Configs) UnsetGlobal(key string) error

UnsetGlobal deletes a key from the global config.

func (*Configs) UnsetLocal

func (cs *Configs) UnsetLocal(key string) error

UnsetLocal deletes a key from the local config.