org.eclipse.jgit.lib

Class Config

java.lang.Object

org.eclipse.jgit.lib.Config

Direct Known Subclasses:

BlobBasedConfig, StoredConfig

public class Config
extends Object

Git style .config, .gitconfig, .gitmodules file.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Config.ConfigEnum Converts enumeration values into configuration options and vice-versa, allowing to match a config option with an enum value.
static interface	Config.SectionParser<T> Parses a section of the configuration into an application model object.

Constructor Summary

Constructors

Constructor and Description
Config() Create a configuration with no default fallback.
Config(Config defaultConfig) Create an empty configuration with a fallback for missing keys.

Method Summary

Modifier and Type	Method and Description
ListenerHandle	addChangeListener(ConfigChangedListener listener) Adds a listener to be notified about changes.
protected void	clear() Clear the configuration file
protected void	fireConfigChangedEvent() Notifies the listeners
void	fromText(String text) Clear this configuration and reset to the contents of the parsed string.
<T> T	get(Config.SectionParser<T> parser) Obtain a handle to a parsed set of configuration values.
Config	getBaseConfig() Retrieves this config's base config.
boolean	getBoolean(String section, String name, boolean defaultValue) Get a boolean value from the git config
boolean	getBoolean(String section, String subsection, String name, boolean defaultValue) Get a boolean value from the git config
<T extends Enum<?>> T	getEnum(String section, String subsection, String name, T defaultValue) Parse an enumeration from the configuration.
<T extends Enum<?>> T	getEnum(T[] all, String section, String subsection, String name, T defaultValue) Parse an enumeration from the configuration.
int	getInt(String section, String name, int defaultValue) Obtain an integer value from the configuration.
int	getInt(String section, String subsection, String name, int defaultValue) Obtain an integer value from the configuration.
long	getLong(String section, String name, long defaultValue) Obtain an integer value from the configuration.
long	getLong(String section, String subsection, String name, long defaultValue) Obtain an integer value from the configuration.
Set<String>	getNames(String section) Get the list of names defined for this section
Set<String>	getNames(String section, boolean recursive) Get the list of names defined for this section
Set<String>	getNames(String section, String subsection) Get the list of names defined for this subsection
Set<String>	getNames(String section, String subsection, boolean recursive) Get the list of names defined for this section
Path	getPath(String section, String subsection, String name, FS fs, File resolveAgainst, Path defaultValue) Parse a string value and treat it as a file path, replacing a ~/ prefix by the user's home directory.
List<RefSpec>	getRefSpecs(String section, String subsection, String name) Parse a list of RefSpecs from the configuration.
Set<String>	getSections() Get the sections defined in this Config.
String	getString(String section, String subsection, String name) Get string value or null if not found.
String[]	getStringList(String section, String subsection, String name) Get a list of string values
Set<String>	getSubsections(String section) Get set of all subsections of specified section within this configuration and its base configuration
long	getTimeUnit(String section, String subsection, String name, long defaultValue, TimeUnit wantUnit) Parse a numerical time unit, such as "1 minute", from the configuration.
static boolean	isMissing(String value) Check if a given string is the "missing" value.
protected boolean	isUtf8(byte[] bytes) Check if bytes should be treated as UTF-8 or not.
protected boolean	notifyUponTransientChanges() Determine whether to issue change events for transient changes.
protected byte[]	readIncludedConfig(String relPath) Read the included config from the specified (possibly) relative path
void	setBoolean(String section, String subsection, String name, boolean value) Add or modify a configuration value.
<T extends Enum<?>> void	setEnum(String section, String subsection, String name, T value) Add or modify a configuration value.
void	setInt(String section, String subsection, String name, int value) Add or modify a configuration value.
void	setLong(String section, String subsection, String name, long value) Add or modify a configuration value.
void	setString(String section, String subsection, String name, String value) Add or modify a configuration value.
void	setStringList(String section, String subsection, String name, List<String> values) Set a configuration value.
static void	setTypedConfigGetter(TypedConfigGetter getter) Globally sets a TypedConfigGetter that is subsequently used to read typed values from all git configs.
String	toText() Get this configuration, formatted as a Git style text file.
void	uncache(Config.SectionParser<?> parser) Remove a cached configuration object.
void	unset(String section, String subsection, String name) Remove a configuration value.
void	unsetSection(String section, String subsection) Remove all configuration values under a single section.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Config

public Config()

Create a configuration with no default fallback.

Config

public Config(Config defaultConfig)

Create an empty configuration with a fallback for missing keys.

Parameters:

defaultConfig - the base configuration to be consulted when a key is missing from this configuration instance.

Method Detail

getBaseConfig

public Config getBaseConfig()

Retrieves this config's base config.

Returns:

the base configuration of this config.

Since:

5.5.2

isMissing

public static boolean isMissing(String value)

Check if a given string is the "missing" value.

Parameters:

value - string to be checked.

Returns:

true if the given string is the "missing" value.

Since:

5.4

setTypedConfigGetter

public static void setTypedConfigGetter(TypedConfigGetter getter)

Globally sets a TypedConfigGetter that is subsequently used to read typed values from all git configs.

Parameters:

getter - to use; if null use the default getter.

Since:

4.9

getInt

public int getInt(String section,
                  String name,
                  int defaultValue)

Obtain an integer value from the configuration.

Parameters:

section - section the key is grouped within.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

an integer value from the configuration, or defaultValue.

getInt

public int getInt(String section,
                  String subsection,
                  String name,
                  int defaultValue)

Obtain an integer value from the configuration.

Parameters:

section - section the key is grouped within.

subsection - subsection name, such a remote or branch name.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

an integer value from the configuration, or defaultValue.

getLong

public long getLong(String section,
                    String name,
                    long defaultValue)

Obtain an integer value from the configuration.

Parameters:

section - section the key is grouped within.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

an integer value from the configuration, or defaultValue.

getLong

public long getLong(String section,
                    String subsection,
                    String name,
                    long defaultValue)

Obtain an integer value from the configuration.

Parameters:

section - section the key is grouped within.

subsection - subsection name, such a remote or branch name.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

an integer value from the configuration, or defaultValue.

getBoolean

public boolean getBoolean(String section,
                          String name,
                          boolean defaultValue)

Get a boolean value from the git config

Parameters:

section - section the key is grouped within.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

true if any value or defaultValue is true, false for missing or explicit false

getBoolean

public boolean getBoolean(String section,
                          String subsection,
                          String name,
                          boolean defaultValue)

Get a boolean value from the git config

Parameters:

section - section the key is grouped within.

subsection - subsection name, such a remote or branch name.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

true if any value or defaultValue is true, false for missing or explicit false

getEnum

public <T extends Enum<?>> T getEnum(String section,
                                     String subsection,
                                     String name,
                                     T defaultValue)

Parse an enumeration from the configuration.

Parameters:

section - section the key is grouped within.

subsection - subsection name, such a remote or branch name.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

the selected enumeration value, or defaultValue.

getEnum

public <T extends Enum<?>> T getEnum(T[] all,
                                     String section,
                                     String subsection,
                                     String name,
                                     T defaultValue)

Parse an enumeration from the configuration.

Parameters:

all - all possible values in the enumeration which should be recognized. Typically EnumType.values().

section - section the key is grouped within.

subsection - subsection name, such a remote or branch name.

name - name of the key to get.

defaultValue - default value to return if no value was present.

Returns:

the selected enumeration value, or defaultValue.

getString

public String getString(String section,
                        String subsection,
                        String name)

Get string value or null if not found.

Parameters:

section - the section

subsection - the subsection for the value

name - the key name

Returns:

a String value from the config, null if not found

getStringList

public String[] getStringList(String section,
                              String subsection,
                              String name)

Get a list of string values

If this instance was created with a base, the base's values are returned first (if any).

Parameters:

section - the section

subsection - the subsection for the value

name - the key name

Returns:

array of zero or more values from the configuration.

getTimeUnit

public long getTimeUnit(String section,
                        String subsection,
                        String name,
                        long defaultValue,
                        TimeUnit wantUnit)

Parse a numerical time unit, such as "1 minute", from the configuration.

Parameters:

section - section the key is in.

subsection - subsection the key is in, or null if not in a subsection.

name - the key name.

defaultValue - default value to return if no value was present.

wantUnit - the units of defaultValue and the return value, as well as the units to assume if the value does not contain an indication of the units.

Returns:

the value, or defaultValue if not set, expressed in units.

Since:

4.5

getPath

public Path getPath(String section,
                    String subsection,
                    String name,
                    @NonNull
                    FS fs,
                    File resolveAgainst,
                    Path defaultValue)

Parse a string value and treat it as a file path, replacing a ~/ prefix by the user's home directory.

Note: this may throw InvalidPathException if the string is not a valid path.

Parameters:

section - section the key is in.

subsection - subsection the key is in, or null if not in a subsection.

name - the key name.

fs - to use to convert the string into a path.

resolveAgainst - directory to resolve the path against if it is a relative path; null to use the Java process's current directory.

defaultValue - to return if no value was present

Returns:

the Path, or defaultValue if not set

Since:

5.10

getRefSpecs

public List<RefSpec> getRefSpecs(String section,
                                 String subsection,
                                 String name)

Parse a list of RefSpecs from the configuration.

Parameters:

section - section the key is in.

subsection - subsection the key is in, or null if not in a subsection.

name - the key name.

Returns:

a possibly empty list of RefSpecs

Since:

4.9

getSubsections

public Set<String> getSubsections(String section)

Get set of all subsections of specified section within this configuration and its base configuration

Parameters:

section - section to search for.

Returns:

set of all subsections of specified section within this configuration and its base configuration; may be empty if no subsection exists. The set's iterator returns sections in the order they are declared by the configuration starting from this instance and progressing through the base.

getSections

public Set<String> getSections()

Get the sections defined in this Config.

Returns:

the sections defined in this Config. The set's iterator returns sections in the order they are declared by the configuration starting from this instance and progressing through the base.

getNames

public Set<String> getNames(String section)

Get the list of names defined for this section

Parameters:

section - the section

Returns:

the list of names defined for this section

getNames

public Set<String> getNames(String section,
                            String subsection)

Get the list of names defined for this subsection

Parameters:

section - the section

subsection - the subsection

Returns:

the list of names defined for this subsection

getNames

public Set<String> getNames(String section,
                            boolean recursive)

Get the list of names defined for this section

Parameters:

section - the section

recursive - if true recursively adds the names defined in all base configurations

Returns:

the list of names defined for this section

Since:

3.2

getNames

public Set<String> getNames(String section,
                            String subsection,
                            boolean recursive)

Get the list of names defined for this section

Parameters:

section - the section

subsection - the subsection

recursive - if true recursively adds the names defined in all base configurations

Returns:

the list of names defined for this subsection

Since:

3.2

get

public <T> T get(Config.SectionParser<T> parser)

Obtain a handle to a parsed set of configuration values.

Type Parameters:

T - type of configuration model to return.

Parameters:

parser - parser which can create the model if it is not already available in this configuration file. The parser is also used as the key into a cache and must obey the hashCode and equals contract in order to reuse a parsed model.

Returns:

the parsed object instance, which is cached inside this config.

uncache

public void uncache(Config.SectionParser<?> parser)

Remove a cached configuration object.

If the associated configuration object has not yet been cached, this method has no effect.

Parameters:

parser - parser used to obtain the configuration object.

See Also:

get(SectionParser)

addChangeListener

public ListenerHandle addChangeListener(ConfigChangedListener listener)

Adds a listener to be notified about changes.

Clients are supposed to remove the listeners after they are done with them using the ListenerHandle.remove() method

Parameters:

listener - the listener

Returns:

the handle to the registered listener

notifyUponTransientChanges

protected boolean notifyUponTransientChanges()

Determine whether to issue change events for transient changes.

If true is returned (which is the default behavior), fireConfigChangedEvent() will be called upon each change.

Subclasses that override this to return false are responsible for issuing fireConfigChangedEvent() calls themselves.

Returns:

fireConfigChangedEvent

protected void fireConfigChangedEvent()

Notifies the listeners

setInt

public void setInt(String section,
                   String subsection,
                   String name,
                   int value)

Add or modify a configuration value. The parameters will result in a configuration entry like this.

 [section "subsection"]
         name = value
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

value - parameter value

setLong

public void setLong(String section,
                    String subsection,
                    String name,
                    long value)

Add or modify a configuration value. The parameters will result in a configuration entry like this.

 [section "subsection"]
         name = value
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

value - parameter value

setBoolean

public void setBoolean(String section,
                       String subsection,
                       String name,
                       boolean value)

Add or modify a configuration value. The parameters will result in a configuration entry like this.

 [section "subsection"]
         name = value
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

value - parameter value

setEnum

public <T extends Enum<?>> void setEnum(String section,
                                        String subsection,
                                        String name,
                                        T value)

Add or modify a configuration value. The parameters will result in a configuration entry like this.

 [section "subsection"]
         name = value
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

value - parameter value

setString

public void setString(String section,
                      String subsection,
                      String name,
                      String value)

Add or modify a configuration value. The parameters will result in a configuration entry like this.

 [section "subsection"]
         name = value
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

value - parameter value, e.g. "true"

unset

public void unset(String section,
                  String subsection,
                  String name)

Remove a configuration value.

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

unsetSection

public void unsetSection(String section,
                         String subsection)

Remove all configuration values under a single section.

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

setStringList

public void setStringList(String section,
                          String subsection,
                          String name,
                          List<String> values)

Set a configuration value.

 [section "subsection"]
         name = value1
         name = value2
 

Parameters:

section - section name, e.g "branch"

subsection - optional subsection value, e.g. a branch name

name - parameter name, e.g. "filemode"

values - list of zero or more values for this key.

toText

public String toText()

Get this configuration, formatted as a Git style text file.

Returns:

this configuration, formatted as a Git style text file.

fromText

public void fromText(String text)
              throws ConfigInvalidException

Clear this configuration and reset to the contents of the parsed string.

Parameters:

text - Git style text file listing configuration properties.

Throws:

ConfigInvalidException - the text supplied is not formatted correctly. No changes were made to this.

readIncludedConfig

protected byte[] readIncludedConfig(String relPath)
                             throws ConfigInvalidException

Read the included config from the specified (possibly) relative path

Parameters:

relPath - possibly relative path to the included config, as specified in this config

Returns:

the read bytes, or null if the included config should be ignored

Throws:

ConfigInvalidException - if something went wrong while reading the config

Since:

4.10

clear

protected void clear()

Clear the configuration file

isUtf8

protected boolean isUtf8(byte[] bytes)

Check if bytes should be treated as UTF-8 or not.

Parameters:

bytes - the bytes to check encoding for.

Returns:

true if bytes should be treated as UTF-8, false otherwise.

Since:

4.4