From 8df0dec7e676c1281c46834614c68fb09697bf45 Mon Sep 17 00:00:00 2001
From: Wes Morgan <wesmorgan@icloud.com>
Date: Tue, 7 Apr 2020 07:58:58 -0600
Subject: Document some things in format/config/merged.go

---
 plumbing/format/config/merged.go | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

(limited to 'plumbing/format/config/merged.go')

diff --git a/plumbing/format/config/merged.go b/plumbing/format/config/merged.go
index 52f4b68..a44f3b8 100644
--- a/plumbing/format/config/merged.go
+++ b/plumbing/format/config/merged.go
@@ -1,7 +1,13 @@
 package config
 
+// Scope defines which configuration we're reading / writing. Git uses
+// a local config file in each repo (./.git/config) which corresponds
+// with LocalScope here. It's values have the highest priority (i.e. they
+// override those in the other two scopes). Next is the global config which
+// could also be described as a user config since it lives in the
+// ~/.gitconfig file. Last and lowest priority is the system config which
+// resides in the /etc/gitconfig file.
 type Scope int
-
 const (
 	LocalScope Scope = iota
 	GlobalScope
@@ -10,14 +16,22 @@ const (
 
 type ScopedConfigs map[Scope]*Config
 
+// Merged defines a read-only view of the priority-merged config params
+// so that you can access the effective settings in the same way git does.
+// For example, if a user has defined a user.name value in ~/.gitconfig but
+// a different one in the current repo's ./.git/config file, this code:
+// config.Merged.Section("user").Option("name") will give you the value
+// from ./.git/config.
 type Merged struct {
 	scopedConfigs ScopedConfigs
 }
 
+// MergedSection is a read-only Section for merged config views.
 type MergedSection struct {
 	backingSection *Section
 }
 
+// MergedSubsection is a read-only Subsection for merged config views.
 type MergedSubsection struct {
 	backingSubsection *Subsection
 }
@@ -39,26 +53,39 @@ func (m *Merged) ResetScopedConfig(scope Scope) {
 	m.scopedConfigs[scope] = New()
 }
 
+// ScopedConfig allows accessing specific backing *Config instances.
 func (m *Merged) ScopedConfig(scope Scope) *Config {
 	return m.scopedConfigs[scope]
 }
 
+// LocalConfig allows accessing the local (i.e. ./.git/config) backing
+// *Config instance.
 func (m *Merged) LocalConfig() *Config {
 	return m.ScopedConfig(LocalScope)
 }
 
+// GlobalConfig allows accessing the global (i.e. ~/.gitconfig) backing
+// *Config instance.
 func (m *Merged) GlobalConfig() *Config {
 	return m.ScopedConfig(GlobalScope)
 }
 
+// SystemConfig allows accessing the system (i.e. /etc/gitconfig) backing
+// *Config instance.
 func (m *Merged) SystemConfig() *Config {
 	return m.ScopedConfig(SystemScope)
 }
 
+// SetLocalConfig allows updating the local (i.e. ./.git/config) config. If you
+// call config.SetConfig(...) on the containing top-level config instance after
+// this, your new local config params will be written to ./.git/config.
 func (m *Merged) SetLocalConfig(c *Config) {
 	m.scopedConfigs[LocalScope] = c
 }
 
+// SetGlobalConfig allows updating the global (i.e. ~/.gitconfig) config. If you
+// call config.SetConfig(...) on the containing top-level config instance after
+// this, your new global config params will be written to ~/.gitconfig.
 func (m *Merged) SetGlobalConfig(c *Config) {
 	m.scopedConfigs[GlobalScope] = c
 }
@@ -79,6 +106,9 @@ func (c *Config) hasSection(name string) bool {
 	return found
 }
 
+// Section returns a read-only *MergedSection view of the config in which
+// params are merged in the same order as git itself:
+// Local overrides global overrides system.
 func (m *Merged) Section(name string) *MergedSection {
 	var mergedSection *MergedSection
 
@@ -120,18 +150,26 @@ func (m *Merged) Section(name string) *MergedSection {
 	return mergedSection
 }
 
+// AddOption works just like config.AddOption except that it takes a Scope as its first argument.
+// This defines which config scope (local, global, or system) this option should be added to.
 func (m *Merged) AddOption(scope Scope, section string, subsection string, key string, value string) *Config {
 	return m.ScopedConfig(scope).AddOption(section, subsection, key, value)
 }
 
+// SetOption works just like config.SetOption except that it takes a Scope as its first argument.
+// This defines which config scope (local, global, or system) this option should be set in.
 func (m *Merged) SetOption(scope Scope, section string, subsection string, key string, value string) *Config {
 	return m.ScopedConfig(scope).SetOption(section, subsection, key, value)
 }
 
+// RemoveSection works just like config.RemoveSection except that it takes a Scope as its first argument.
+// This defines which config scope (local, global, or system) the section should be removed from.
 func (m *Merged) RemoveSection(scope Scope, name string) *Config {
 	return m.ScopedConfig(scope).RemoveSection(name)
 }
 
+// RemoveSubsection works just like config.RemoveSubsection except that it takes a Scope as its first argument.
+// This defines which config scope (local, global, or system) the subsection should be removed from.
 func (m *Merged) RemoveSubsection(scope Scope, section string, subsection string) *Config {
 	return m.ScopedConfig(scope).RemoveSubsection(section, subsection)
 }
-- 
cgit