Package org.eclipse.jgit.lib

Class Config

  • Direct Known Subclasses:
    BlobBasedConfig, StoredConfig
    public class Config
extends java.lang.Object
    Git style .config, .gitconfig, .gitmodules file.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class 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.
      private static class  Config.StringReader  

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ListenerHandle addChangeListener​(ConfigChangedListener listener)
      Adds a listener to be notified about changes.
      private void addIncludedConfig​(java.util.List<ConfigLine> newEntries, ConfigLine line, int depth)  
      private static <T> T[] allValuesOf​(T value)  
      protected void clear()
      Clear the configuration file
      private static java.util.List<ConfigLine> copy​(ConfigSnapshot src, java.util.List<java.lang.String> values)  
      (package private) static java.lang.String escapeSubsection​(java.lang.String x)  
      (package private) static java.lang.String escapeValue​(java.lang.String x)
      Escape the value before saving
      private static int findSectionEnd​(java.util.List<ConfigLine> entries, java.lang.String section, java.lang.String subsection, boolean skipIncludedLines)  
      protected void fireConfigChangedEvent()
      Notifies the listeners
      void fromText​(java.lang.String text)
      Clear this configuration and reset to the contents of the parsed string.
      private java.util.List<ConfigLine> fromTextRecurse​(java.lang.String text, int depth, java.lang.String includedFrom)  
      <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.
      private ConfigSnapshot getBaseState()  
      boolean getBoolean​(java.lang.String section, java.lang.String name, boolean defaultValue)
      Get a boolean value from the git config
      boolean getBoolean​(java.lang.String section, java.lang.String subsection, java.lang.String name, boolean defaultValue)
      Get a boolean value from the git config
      <T extends java.lang.Enum<?>>
      T      		 getEnum​(java.lang.String section, java.lang.String subsection, java.lang.String name, T defaultValue)
      Parse an enumeration from the configuration.
      <T extends java.lang.Enum<?>>
      T      		 getEnum​(T[] all, java.lang.String section, java.lang.String subsection, java.lang.String name, T defaultValue)
      Parse an enumeration from the configuration.
      int getInt​(java.lang.String section, java.lang.String name, int defaultValue)
      Obtain an integer value from the configuration.
      int getInt​(java.lang.String section, java.lang.String subsection, java.lang.String name, int defaultValue)
      Obtain an integer value from the configuration.
      long getLong​(java.lang.String section, java.lang.String name, long defaultValue)
      Obtain an integer value from the configuration.
      long getLong​(java.lang.String section, java.lang.String subsection, java.lang.String name, long defaultValue)
      Obtain an integer value from the configuration.
      java.util.Set<java.lang.String> getNames​(java.lang.String section)
      Get the list of names defined for this section
      java.util.Set<java.lang.String> getNames​(java.lang.String section, boolean recursive)
      Get the list of names defined for this section
      java.util.Set<java.lang.String> getNames​(java.lang.String section, java.lang.String subsection)
      Get the list of names defined for this subsection
      java.util.Set<java.lang.String> getNames​(java.lang.String section, java.lang.String subsection, boolean recursive)
      Get the list of names defined for this section
      java.nio.file.Path getPath​(java.lang.String section, java.lang.String subsection, java.lang.String name, FS fs, java.io.File resolveAgainst, java.nio.file.Path defaultValue)
      Parse a string value and treat it as a file path, replacing a ~/ prefix by the user's home directory.
      (package private) java.lang.String getRawString​(java.lang.String section, java.lang.String subsection, java.lang.String name)  
      private java.lang.String[] getRawStringList​(java.lang.String section, java.lang.String subsection, java.lang.String name)  
      java.util.List<RefSpec> getRefSpecs​(java.lang.String section, java.lang.String subsection, java.lang.String name)
      Parse a list of RefSpecs from the configuration.
      java.util.Set<java.lang.String> getSections()
      Get the sections defined in this Config.
      private ConfigSnapshot getState()  
      java.lang.String getString​(java.lang.String section, java.lang.String subsection, java.lang.String name)
      Get string value or null if not found.
      java.lang.String[] getStringList​(java.lang.String section, java.lang.String subsection, java.lang.String name)
      Get a list of string values
      java.util.Set<java.lang.String> getSubsections​(java.lang.String section)
      Get set of all subsections of specified section within this configuration and its base configuration
      long getTimeUnit​(java.lang.String section, java.lang.String subsection, java.lang.String name, long defaultValue, java.util.concurrent.TimeUnit wantUnit)
      Parse a numerical time unit, such as "1 minute", from the configuration.
      static boolean isMissing​(java.lang.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.
      private ConfigSnapshot newState()  
      private ConfigSnapshot newState​(java.util.List<ConfigLine> entries)  
      protected boolean notifyUponTransientChanges()
      Determine whether to issue change events for transient changes.
      protected byte[] readIncludedConfig​(java.lang.String relPath)
      Read the included config from the specified (possibly) relative path
      private static java.lang.String readKeyName​(Config.StringReader in)  
      private static java.lang.String readSectionName​(Config.StringReader in)  
      private static java.lang.String readSubsectionName​(Config.StringReader in)  
      private static java.lang.String readValue​(Config.StringReader in)  
      private ConfigSnapshot replaceStringList​(ConfigSnapshot srcState, java.lang.String section, java.lang.String subsection, java.lang.String name, java.util.List<java.lang.String> values)  
      void setBoolean​(java.lang.String section, java.lang.String subsection, java.lang.String name, boolean value)
      Add or modify a configuration value.
      <T extends java.lang.Enum<?>>
      void      		 setEnum​(java.lang.String section, java.lang.String subsection, java.lang.String name, T value)
      Add or modify a configuration value.
      void setInt​(java.lang.String section, java.lang.String subsection, java.lang.String name, int value)
      Add or modify a configuration value.
      void setLong​(java.lang.String section, java.lang.String subsection, java.lang.String name, long value)
      Add or modify a configuration value.
      void setString​(java.lang.String section, java.lang.String subsection, java.lang.String name, java.lang.String value)
      Add or modify a configuration value.
      void setStringList​(java.lang.String section, java.lang.String subsection, java.lang.String name, java.util.List<java.lang.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.
      java.lang.String toText()
      Get this configuration, formatted as a Git style text file.
      private static java.lang.String toUnicodeLiteral​(int c)  
      void uncache​(Config.SectionParser<?> parser)
      Remove a cached configuration object.
      void unset​(java.lang.String section, java.lang.String subsection, java.lang.String name)
      Remove a configuration value.
      void unsetSection​(java.lang.String section, java.lang.String subsection)
      Remove all configuration values under a single section.
      private ConfigSnapshot unsetSection​(ConfigSnapshot srcState, java.lang.String section, java.lang.String subsection)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY_STRING_ARRAY

        private static final java.lang.String[] EMPTY_STRING_ARRAY

      • listeners

        private final ListenerList listeners
        the change listeners

      • state

        private final java.util.concurrent.atomic.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 java.lang.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 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​(java.lang.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 java.lang.String escapeValue​(java.lang.String x)
        Escape the value before saving
        Parameters:
        x - the value to escape
        Returns:
        the escaped value

      • escapeSubsection

        static java.lang.String escapeSubsection​(java.lang.String x)

      • getInt

        public int getInt​(java.lang.String section,
                  java.lang.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​(java.lang.String section,
                  java.lang.String subsection,
                  java.lang.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​(java.lang.String section,
                    java.lang.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​(java.lang.String section,
                    java.lang.String subsection,
                    java.lang.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​(java.lang.String section,
                          java.lang.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​(java.lang.String section,
                          java.lang.String subsection,
                          java.lang.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 java.lang.Enum<?>> T getEnum​(java.lang.String section,
                                               java.lang.String subsection,
                                               java.lang.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 java.lang.Enum<?>> T getEnum​(T[] all,
                                               java.lang.String section,
                                               java.lang.String subsection,
                                               java.lang.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 java.lang.String getString​(java.lang.String section,
                                  java.lang.String subsection,
                                  java.lang.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 java.lang.String[] getStringList​(java.lang.String section,
                                        java.lang.String subsection,
                                        java.lang.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​(java.lang.String section,
                        java.lang.String subsection,
                        java.lang.String name,
                        long defaultValue,
                        java.util.concurrent.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 java.nio.file.Path getPath​(java.lang.String section,
                                  java.lang.String subsection,
                                  java.lang.String name,
                                  @NonNull
                                  FS fs,
                                  java.io.File resolveAgainst,
                                  java.nio.file.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 java.util.List<RefSpec> getRefSpecs​(java.lang.String section,
                                           java.lang.String subsection,
                                           java.lang.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 java.util.Set<java.lang.String> getSubsections​(java.lang.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 java.util.Set<java.lang.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 java.util.Set<java.lang.String> getNames​(java.lang.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 java.util.Set<java.lang.String> getNames​(java.lang.String section,
                                                java.lang.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 java.util.Set<java.lang.String> getNames​(java.lang.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 java.util.Set<java.lang.String> getNames​(java.lang.String section,
                                                java.lang.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

      • getRawString

        java.lang.String getRawString​(java.lang.String section,
                              java.lang.String subsection,
                              java.lang.String name)

      • getRawStringList

        private java.lang.String[] getRawStringList​(java.lang.String section,
                                            java.lang.String subsection,
                                            java.lang.String name)

      • setInt

        public void setInt​(java.lang.String section,
                   java.lang.String subsection,
                   java.lang.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​(java.lang.String section,
                    java.lang.String subsection,
                    java.lang.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​(java.lang.String section,
                       java.lang.String subsection,
                       java.lang.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 java.lang.Enum<?>> void setEnum​(java.lang.String section,
                                                  java.lang.String subsection,
                                                  java.lang.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​(java.lang.String section,
                      java.lang.String subsection,
                      java.lang.String name,
                      java.lang.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​(java.lang.String section,
                  java.lang.String subsection,
                  java.lang.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​(java.lang.String section,
                         java.lang.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​(java.lang.String section,
                          java.lang.String subsection,
                          java.lang.String name,
                          java.util.List<java.lang.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,
                                         java.lang.String section,
                                         java.lang.String subsection,
                                         java.lang.String name,
                                         java.util.List<java.lang.String> values)

      • copy

        private static java.util.List<ConfigLine> copy​(ConfigSnapshot src,
                                               java.util.List<java.lang.String> values)

      • findSectionEnd

        private static int findSectionEnd​(java.util.List<ConfigLine> entries,
                                  java.lang.String section,
                                  java.lang.String subsection,
                                  boolean skipIncludedLines)

      • toText

        public java.lang.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​(java.lang.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​(java.lang.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

      • toUnicodeLiteral

        private static java.lang.String toUnicodeLiteral​(int c)