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.
  • Field Details

    • EMPTY_STRING_ARRAY

      private static final String[] EMPTY_STRING_ARRAY
    • KiB

      static final long KiB
      See Also:
    • MiB

      static final long MiB
      See Also:
    • GiB

      static final long GiB
      See Also:
    • MAX_DEPTH

      private static final int MAX_DEPTH
      See Also:
    • DEFAULT_GETTER

      private static final TypedConfigGetter DEFAULT_GETTER
    • typedGetter

      private static TypedConfigGetter typedGetter
    • listeners

      private final ListenerList listeners
      the change listeners
    • state

      private final AtomicReference<ConfigSnapshot> state
      Immutable current state of the configuration data.

      This state is copy-on-write. It should always contain an immutable list of the configuration keys/values.

    • baseConfig

      private final Config baseConfig
    • MISSING_ENTRY

      private static final String MISSING_ENTRY
      Magic value indicating a missing entry.

      This value is tested for reference equality in some contexts, so we must ensure it is a special copy of the empty string. It also must be treated like the empty string.

  • Constructor Details

    • 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 Details

    • 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
    • escapeValue

      static String escapeValue(String x)
      Escape the value before saving
      Parameters:
      x - the value to escape
      Returns:
      the escaped value
    • escapeSubsection

      static String escapeSubsection(String x)
    • 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.
    • allValuesOf

      private static <T> T[] allValuesOf(T value)
    • 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:
    • 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
    • getRawString

      String getRawString(String section, String subsection, String name)
    • getRawStringList

      private String[] getRawStringList(String section, String subsection, String name)
    • getState

      private ConfigSnapshot getState()
    • getBaseState

      private ConfigSnapshot getBaseState()
    • 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
    • unsetSection

      private ConfigSnapshot unsetSection(ConfigSnapshot srcState, String section, String subsection)
    • 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.
    • replaceStringList

      private ConfigSnapshot replaceStringList(ConfigSnapshot srcState, String section, String subsection, String name, List<String> values)
    • copy

      private static List<ConfigLine> copy(ConfigSnapshot src, List<String> values)
    • findSectionEnd

      private static int findSectionEnd(List<ConfigLine> entries, String section, String subsection, boolean skipIncludedLines)
    • 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.
    • fromTextRecurse

      private List<ConfigLine> fromTextRecurse(String text, int depth, String includedFrom) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • 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
    • addIncludedConfig

      private void addIncludedConfig(List<ConfigLine> newEntries, ConfigLine line, int depth) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • newState

      private ConfigSnapshot newState()
    • newState

      private ConfigSnapshot newState(List<ConfigLine> entries)
    • 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
    • readSectionName

      private static String readSectionName(Config.StringReader in) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • readKeyName

      private static String readKeyName(Config.StringReader in) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • readSubsectionName

      private static String readSubsectionName(Config.StringReader in) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • readValue

      private static String readValue(Config.StringReader in) throws ConfigInvalidException
      Throws:
      ConfigInvalidException
    • toUnicodeLiteral

      private static String toUnicodeLiteral(int c)