config

README

---

stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

Add a new configuration

To add a new configuration to config.yaml.lock:

1. Add a head comment and a default value:

   # head comment
   new_key: default_value
   

2. Add any configuration that is specific to a hostname or GitLab instance to the hosts section, in the gitlab.com subsection:

   ...
   # This configuration is specifically for GitLab instances
   hosts:
     gitlab.com:
       ...
       # This is a new config
       new_key: default_value
   ...
   

3. Add general configuration changes before the hosts section:

   ...
   # Head comment
   new_key: default_value
   # Configuration specific for GitLab instances
   hosts:
     gitlab.com:
   ...
   

4. Run make gen-config or cd internal/config && go generate.

5. Most configuration keys can be overwritten by their corresponding environment variables. If the corresponding environment variable name differs from the configuration key's name, set the environment variable's name in the config_mapping.go file.

Documentation

Index

• Variables
• func CheckFileExists(filename string) bool
• func CheckPathExists(path string) bool
• func ConfigDir() string
• func ConfigFile() string
• func ConfigKeyEquivalence(key string) string
• func EnvKeyEquivalence(key string) []string
• func GetFromEnv(key string) (value string)
• func GetFromEnvWithSource(key string) (value, source string)
• func NewBlankRoot() *yaml.Node
• func ParseConfigFile(filename string) ([]byte, *yaml.Node, error)
• func Prompt(question, defaultVal string) (envVal string, err error)
• func StubConfig(main, aliases string) func()
• func StubWriteConfig(wc io.Writer, wh io.Writer) func()
• func WriteFile(filename string, data []byte, perm os.FileMode) error
• type AliasConfig
  • func (a *AliasConfig) All() map[string]string
  • func (a *AliasConfig) Delete(alias string) error
  • func (a *AliasConfig) Get(alias string) (string, bool)
  • func (a *AliasConfig) Set(alias, expansion string) error
  • func (a *AliasConfig) Write() error
• type Config
  • func Init() (Config, error)
  • func NewBlankConfig() Config
  • func NewConfig(root *yaml.Node) Config
  • func NewFromString(str string) Config
  • func ParseConfig(filename string) (Config, error)
  • func ParseDefaultConfig() (Config, error)
• type ConfigEntry
• type ConfigMap
  • func (cm *ConfigMap) Empty() bool
  • func (cm *ConfigMap) FindEntry(key string) (ce *ConfigEntry, err error)
  • func (cm *ConfigMap) GetStringValue(key string) (string, error)
  • func (cm *ConfigMap) RemoveEntry(key string)
  • func (cm *ConfigMap) SetStringValue(key, value string) error
• type HostConfig
• type LocalConfig
  • func (a *LocalConfig) All() map[string]string
  • func (a *LocalConfig) Delete(key string) error
  • func (a *LocalConfig) Get(key string) (string, bool)
  • func (a *LocalConfig) Set(key, value string) error
  • func (a *LocalConfig) Write() error
• type NotFoundError

Variables

var BackupConfigFile = func(filename string) error {
	return os.Rename(filename, filename+".bak")
}

BackupConfigFile creates a backup of the provided config file

var LocalConfigDir = func() []string {
	return []string{".git", "glab-cli"}
}

LocalConfigDir returns the local config path in map which must be joined for complete path

var LocalConfigFile = func() string {
	configFile := append(LocalConfigDir(), "config.yml")
	return path.Join(configFile...)
}

LocalConfigFile returns the config file name with full path

var ReadConfigFile = func(filename string) ([]byte, error) {
	data, err := os.ReadFile(filename)
	if err != nil {
		return nil, pathError(err)
	}

	return data, nil
}

var WriteConfigFile = func(filename string, data []byte) error {
	err := os.MkdirAll(path.Dir(filename), 0o750)
	if err != nil {
		return pathError(err)
	}
	_, err = os.ReadFile(filename)
	if err != nil && !os.IsNotExist(err) {
		return err
	}
	err = WriteFile(filename, data, 0o600)
	return err
}

Functions

func CheckFileExists

func CheckFileExists(filename string) bool

CheckFileExists : checks if a file exists and is not a directory.

func CheckPathExists

func CheckPathExists(path string) bool

CheckPathExists checks if a folder exists and is a directory

func ConfigDir

func ConfigDir() string

ConfigDir returns the config directory

func ConfigFile

func ConfigFile() string

ConfigFile returns the config file path

func ConfigKeyEquivalence

func ConfigKeyEquivalence(key string) string

ConfigKeyEquivalence returns the equivalent key that's actually used in the config file

func EnvKeyEquivalence

func EnvKeyEquivalence(key string) []string

EnvKeyEquivalence returns the equivalent key that's used for environment variables

func GetFromEnv

func GetFromEnv(key string) (value string)

GetFromEnv is just a wrapper for os.GetEnv but checks for matching names used in previous glab versions and retrieves the value of the environment if any of the matching names have been set. It returns the value, which will be empty if the variable is not present.

func GetFromEnvWithSource

func GetFromEnvWithSource(key string) (value, source string)

GetFromEnvWithSource works like GetFromEnv but also returns the name of the environment variable that was set as the source.

func NewBlankRoot

func NewBlankRoot() *yaml.Node

func ParseConfigFile

func ParseConfigFile(filename string) ([]byte, *yaml.Node, error)

func Prompt

func Prompt(question, defaultVal string) (envVal string, err error)

Prompt prompts user for value and returns default value if empty

Deprecated: only used by the `config init` command which is deprecated

func StubConfig

func StubConfig(main, aliases string) func()

func StubWriteConfig

func StubWriteConfig(wc io.Writer, wh io.Writer) func()

func WriteFile

func WriteFile(filename string, data []byte, perm os.FileMode) error

WriteFile to the path If the path is smylink it will write to the symlink

Types

type AliasConfig

type AliasConfig struct {
	ConfigMap
	Parent Config
}

func (*AliasConfig) All

func (a *AliasConfig) All() map[string]string

func (*AliasConfig) Delete

func (a *AliasConfig) Delete(alias string) error

func (*AliasConfig) Get

func (a *AliasConfig) Get(alias string) (string, bool)

func (*AliasConfig) Set

func (a *AliasConfig) Set(alias, expansion string) error

func (*AliasConfig) Write

func (a *AliasConfig) Write() error

type Config

type Config interface {
	Get(string, string) (string, error)
	GetWithSource(string, string, bool) (string, string, error)
	Set(string, string, string) error
	UnsetHost(string)
	Hosts() ([]string, error)
	Aliases() (*AliasConfig, error)
	Local() (*LocalConfig, error)
	// Write writes to the config.yml file
	Write() error
	// WriteAll saves all the available configuration file types
	WriteAll() error
}

A Config reads and writes persistent configuration for glab.

func Init

func Init() (Config, error)

Init initialises and returns the cached configuration

func NewBlankConfig

func NewBlankConfig() Config

NewBlankConfig initializes a config file pre-populated with comments and default values

func NewConfig

func NewConfig(root *yaml.Node) Config

func NewFromString

func NewFromString(str string) Config

NewFromString initializes a Config from a yaml string

func ParseConfig

func ParseConfig(filename string) (Config, error)

func ParseDefaultConfig

func ParseDefaultConfig() (Config, error)

type ConfigEntry

type ConfigEntry struct {
	KeyNode   *yaml.Node
	ValueNode *yaml.Node
	Index     int
}

type ConfigMap

type ConfigMap struct {
	Root *yaml.Node
}

ConfigMap type implements a low-level get/set config that is backed by an in-memory tree of YAML nodes. It allows us to interact with a YAML-based config programmatically, preserving any comments that were present when the YAML was parsed.

func (*ConfigMap) Empty

func (cm *ConfigMap) Empty() bool

func (*ConfigMap) FindEntry

func (cm *ConfigMap) FindEntry(key string) (ce *ConfigEntry, err error)

func (*ConfigMap) GetStringValue

func (cm *ConfigMap) GetStringValue(key string) (string, error)

func (*ConfigMap) RemoveEntry

func (cm *ConfigMap) RemoveEntry(key string)

func (*ConfigMap) SetStringValue

func (cm *ConfigMap) SetStringValue(key, value string) error

type HostConfig

type HostConfig struct {
	ConfigMap
	Host string
}

HostConfig represents the configuration for a single host.

type LocalConfig

type LocalConfig struct {
	ConfigMap
	Parent Config
}

func (*LocalConfig) All

func (a *LocalConfig) All() map[string]string

func (*LocalConfig) Delete

func (a *LocalConfig) Delete(key string) error

func (*LocalConfig) Get

func (a *LocalConfig) Get(key string) (string, bool)

func (*LocalConfig) Set

func (a *LocalConfig) Set(key, value string) error

func (*LocalConfig) Write

func (a *LocalConfig) Write() error

type NotFoundError

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

NotFoundError is returned when a config entry is not found.