config

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2023 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package config implements encoding and decoding of git config files. 

Configuration File
------------------

The Git configuration file contains a number of variables that affect
the Git commands' behavior. The `.git/config` file in each repository
is used to store the configuration for that repository, and
`$HOME/.gitconfig` is used to store a per-user configuration as
fallback values for the `.git/config` file. The file `/etc/gitconfig`
can be used to store a system-wide default configuration.

The configuration variables are used by both the Git plumbing
and the porcelains. The variables are divided into sections, wherein
the fully qualified variable name of the variable itself is the last
dot-separated segment and the section name is everything before the last
dot. The variable names are case-insensitive, allow only alphanumeric
characters and `-`, and must start with an alphabetic character.  Some
variables may appear multiple times; we say then that the variable is
multivalued.

Syntax
~~~~~~

The syntax is fairly flexible and permissive; whitespaces are mostly
ignored.  The '#' and ';' characters begin comments to the end of line,
blank lines are ignored.

The file consists of sections and variables.  A section begins with
the name of the section in square brackets and continues until the next
section begins.  Section names are case-insensitive.  Only alphanumeric
characters, `-` and `.` are allowed in section names.  Each variable
must belong to some section, which means that there must be a section
header before the first setting of a variable.

Sections can be further divided into subsections.  To begin a subsection
put its name in double quotes, separated by space from the section name,
in the section header, like in the example below:

--------
	[section "subsection"]

--------

Subsection names are case sensitive and can contain any characters except
newline (doublequote `"` and backslash can be included by escaping them
as `\"` and `\\`, respectively).  Section headers cannot span multiple
lines.  Variables may belong directly to a section or to a given subsection.
You can have `[section]` if you have `[section "subsection"]`, but you
don't need to.

There is also a deprecated `[section.subsection]` syntax. With this
syntax, the subsection name is converted to lower-case and is also
compared case sensitively. These subsection names follow the same
restrictions as section names.

All the other lines (and the remainder of the line after the section
header) are recognized as setting variables, in the form
'name = value' (or just 'name', which is a short-hand to say that
the variable is the boolean "true").
The variable names are case-insensitive, allow only alphanumeric characters
and `-`, and must start with an alphabetic character.

A line that defines a value can be continued to the next line by
ending it with a `\`; the backquote and the end-of-line are
stripped.  Leading whitespaces after 'name =', the remainder of the
line after the first comment character '#' or ';', and trailing
whitespaces of the line are discarded unless they are enclosed in
double quotes.  Internal whitespaces within the value are retained
verbatim.

Inside double quotes, double quote `"` and backslash `\` characters
must be escaped: use `\"` for `"` and `\\` for `\`.

The following escape sequences (beside `\"` and `\\`) are recognized:
`\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
and `\b` for backspace (BS).  Other char escape sequences (including octal
escape sequences) are invalid.

Includes
~~~~~~~~

You can include one config file from another by setting the special
`include.path` variable to the name of the file to be included. The
variable takes a pathname as its value, and is subject to tilde
expansion.

The included file is expanded immediately, as if its contents had been
found at the location of the include directive. If the value of the
`include.path` variable is a relative path, the path is considered to be
relative to the configuration file in which the include directive was
found.  See below for examples.

Example
~~~~~~~

	# Core variables
	[core]
		; Don't trust file modes
		filemode = false

	# Our diff algorithm
	[diff]
		external = /usr/local/bin/diff-wrapper
		renames = true

	[branch "devel"]
		remote = origin
		merge = refs/heads/devel

	# Proxy settings
	[core]
		gitProxy="ssh" for "kernel.org"
		gitProxy=default-proxy ; for the rest

	[include]
		path = /path/to/foo.inc ; include by absolute path
		path = foo ; expand "foo" relative to the current file
		path = ~/foo ; expand "foo" in your `$HOME` directory

Index

Constants

View Source 
const (
	// Version_0 is the format defined by the initial version of git,
	// including but not limited to the format of the repository
	// directory, the repository configuration file, and the object
	// and ref storage.
	//
	// Specifying the complete behavior of git is beyond the scope
	// of this document.
	Version_0 = "0"

	// Version_1 is identical to version 0, with the following exceptions:
	//
	//   1. When reading the core.repositoryformatversion variable, a git
	//		implementation which supports version 1 MUST also read any
	//		configuration keys found in the extensions section of the
	//		configuration file.
	//
	//	 2. If a version-1 repository specifies any extensions.* keys that
	//		the running git has not implemented, the operation MUST NOT proceed.
	//		Similarly, if the value of any known key is not understood by the
	//		implementation, the operation MUST NOT proceed.
	//
	// Note that if no extensions are specified in the config file, then
	// core.repositoryformatversion SHOULD be set to 0 (setting it to 1 provides
	// no benefit, and makes the repository incompatible with older
	// implementations of git).
	Version_1 = "1"

	// DefaultRepositoryFormatVersion holds the default repository format version.
	DefaultRepositoryFormatVersion = Version_0
)
View Source 
const (
	// NoSubsection token is passed to Config.Section and Config.SetSection to
	// represent the absence of a section.
	NoSubsection = ""
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Comment 

type Comment string

Comment string without the prefix '#' or ';'.

type Config 

type Config struct {
	Comment  *Comment
	Sections Sections
	Includes Includes
}

Config contains all the sections, comments and includes from a config file.

func New 

func New() *Config

New creates a new config instance.

func (*Config) AddOption 

func (c *Config) AddOption(section string, subsection string, key string, value string) *Config

AddOption adds an option to a given section and subsection. Use the NoSubsection constant for the subsection argument if no subsection is wanted.

func (*Config) HasSection 

func (c *Config) HasSection(name string) bool

HasSection checks if the Config has a section with the specified name.

func (*Config) RemoveSection 

func (c *Config) RemoveSection(name string) *Config

RemoveSection removes a section from a config file.

func (*Config) RemoveSubsection 

func (c *Config) RemoveSubsection(section string, subsection string) *Config

RemoveSubsection remove a subsection from a config file.

func (*Config) Section 

func (c *Config) Section(name string) *Section

Section returns a existing section with the given name or creates a new one.

func (*Config) SetOption 

func (c *Config) SetOption(section string, subsection string, key string, value string) *Config

SetOption sets an option to a given section and subsection. Use the NoSubsection constant for the subsection argument if no subsection is wanted.

type Decoder 

type Decoder struct {
	io.Reader
}

A Decoder reads and decodes config files from an input stream.

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode 

func (d *Decoder) Decode(config *Config) error

Decode reads the whole config from its input and stores it in the value pointed to by config.

type Encoder 

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

An Encoder writes config files to an output stream.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode 

func (e *Encoder) Encode(cfg *Config) error

Encode writes the config in git config format to the stream of the encoder.

type Include 

type Include struct {
	Path   string
	Config *Config
}

Include is a reference to an included config file.

type Includes 

type Includes []*Include

Includes is a list of Includes in a config file.

type ObjectFormat 

type ObjectFormat string

ObjectFormat defines the object format. 

const (
	// SHA1 represents the object format used for SHA1.
	SHA1 ObjectFormat = "sha1"

	// SHA256 represents the object format used for SHA256.
	SHA256 ObjectFormat = "sha256"

	// DefaultObjectFormat holds the default object format.
	DefaultObjectFormat = SHA1
)

type Option 

type Option struct {
	// Key preserving original caseness.
	// Use IsKey instead to compare key regardless of caseness.
	Key string
	// Original value as string, could be not normalized.
	Value string
}

Option defines a key/value entity in a config file.

func (*Option) IsKey 

func (o *Option) IsKey(key string) bool

IsKey returns true if the given key matches this option's key in a case-insensitive comparison.

type Options 

type Options []*Option

func (Options) Get 

func (opts Options) Get(key string) string

Get gets the value for the given key if set, otherwise it returns the empty string.

Note that there is no difference

This matches git behaviour since git v1.8.1-rc1, if there are multiple definitions of a key, the last one wins.

See: http://article.gmane.org/gmane.linux.kernel/1407184

In order to get all possible values for the same key, use GetAll.

func (Options) GetAll 

func (opts Options) GetAll(key string) []string

GetAll returns all possible values for the same key.

func (Options) GoString 

func (opts Options) GoString() string

func (Options) Has 

func (opts Options) Has(key string) bool

Has checks if an Option exist with the given key.

type RepositoryFormatVersion 

type RepositoryFormatVersion string

RepositoryFormatVersion represents the repository format version, as per defined at: 

https://git-scm.com/docs/repository-version

type Section 

type Section struct {
	Name        string
	Options     Options
	Subsections Subsections
}

Section is the representation of a section inside git configuration files. Each Section contains Options that are used by both the Git plumbing and the porcelains. Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, in the section header, like in the example below: 

[section "subsection"]

All the other lines (and the remainder of the line after the section header) are recognized as option variables, in the form "name = value" (or just name, which is a short-hand to say that the variable is the boolean "true"). The variable names are case-insensitive, allow only alphanumeric characters and -, and must start with an alphabetic character: 

[section "subsection1"]
    option1 = value1
    option2
[section "subsection2"]
    option3 = value2

func (*Section) AddOption 

func (s *Section) AddOption(key string, value string) *Section

AddOption adds a new Option to the Section. The updated Section is returned.

func (*Section) HasOption 

func (s *Section) HasOption(key string) bool

HasOption checks if the Section has an Option with the given key.

func (*Section) HasSubsection 

func (s *Section) HasSubsection(name string) bool

HasSubsection checks if the Section has a Subsection with the specified name.

func (*Section) IsName 

func (s *Section) IsName(name string) bool

IsName checks if the name provided is equals to the Section name, case insensitive.

func (*Section) Option 

func (s *Section) Option(key string) string

Option returns the value for the specified key. Empty string is returned if key does not exists.

func (*Section) OptionAll 

func (s *Section) OptionAll(key string) []string

OptionAll returns all possible values for an option with the specified key. If the option does not exists, an empty slice will be returned.

func (*Section) RemoveOption 

func (s *Section) RemoveOption(key string) *Section

Remove an option with the specified key. The updated Section is returned.

func (*Section) RemoveSubsection 

func (s *Section) RemoveSubsection(name string) *Section

RemoveSubsection removes a subsection from a Section.

func (*Section) SetOption 

func (s *Section) SetOption(key string, value string) *Section

SetOption adds a new Option to the Section. If the option already exists, is replaced. The updated Section is returned.

func (*Section) Subsection 

func (s *Section) Subsection(name string) *Subsection

Subsection returns a Subsection from the specified Section. If the Subsection does not exists, new one is created and added to Section.

type Sections 

type Sections []*Section

func (Sections) GoString 

func (s Sections) GoString() string

type Subsection 

type Subsection struct {
	Name    string
	Options Options
}

func (*Subsection) AddOption 

func (s *Subsection) AddOption(key string, value string) *Subsection

AddOption adds a new Option to the Subsection. The updated Subsection is returned.

func (*Subsection) HasOption 

func (s *Subsection) HasOption(key string) bool

HasOption checks if the Subsection has an Option with the given key.

func (*Subsection) IsName 

func (s *Subsection) IsName(name string) bool

IsName checks if the name of the subsection is exactly the specified name.

func (*Subsection) Option 

func (s *Subsection) Option(key string) string

Option returns an option with the specified key. If the option does not exists, empty spring will be returned.

func (*Subsection) OptionAll 

func (s *Subsection) OptionAll(key string) []string

OptionAll returns all possible values for an option with the specified key. If the option does not exists, an empty slice will be returned.

func (*Subsection) RemoveOption 

func (s *Subsection) RemoveOption(key string) *Subsection

RemoveOption removes the option with the specified key. The updated Subsection is returned.

func (*Subsection) SetOption 

func (s *Subsection) SetOption(key string, value ...string) *Subsection

SetOption adds a new Option to the Subsection. If the option already exists, is replaced. The updated Subsection is returned.

type Subsections 

type Subsections []*Subsection

func (Subsections) GoString 

func (s Subsections) GoString() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.