Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CONFIG::GITLIKE (3)

.ds Aq ’


Config::GitLike - git-compatible config file parsing



This module parses git-style config files, which look like this:

        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
    [remote "origin"]
        url =
        fetch = +refs/heads/*:refs/remotes/origin/*
    [another-section "subsection"]
        key = test
        key = multiple values are OK
        emptyvalue =

Code that uses this config module might look like:

    use Config::GitLike;

    # just load a specific file
    my $data = Config::GitLike->load_file("~/.fooconf");

    # or use the object interface to load /etc/config, ~/.config, and
    # `pwd`/.config
    my $c = Config::GitLike->new(confname => config);

    $c->get( key => );
    # make the return value a Perl true/false value
    $c->get( key => core.filemode, as => bool );

    # replace the old value
        key =>,
        value => val1,
        filename => /home/user/.config,

    # make this key have multiple values rather than replacing the
    # old value
        key =>,
        value => val2,
        filename => /home/user/.config,
        multiple => 1,

    # replace all occurrences of the old value for with a new one
        key =>,
        value => val3,
        filename => /home/user/.config,
        multiple => 1,
        replace_all => 1,

    # make sure to reload the config files before reading if youve set
    # any variables!

    # get only the value of that matches 2
    $c->get( key =>, filter => 2 );
    $c->get_all( key => );
    # prefixing a search regexp with a ! negates it
    $c->get_regexp( key => !na );

        from => section,
        to => new-section,
        filename => /home/user/.config

        section => section,
        filename => /home/user/.config

    # unsets all instances of the given key
    $c->set( key =>, filename => /home/user/.config );

    my %config_vals = $config->dump;
    # string representation of config data
    my $str = $config->dump;
    # prints rather than returning


This module handles interaction with configuration files of the style used by the version control system Git. It can both parse and modify these files, as well as create entirely new ones.

You only need to know a few things about the configuration format in order to use this module. First, a configuration file is made up of key/value pairs. Every key must be contained in a section. Sections can have subsections, but they don’t have to. For the purposes of setting and getting configuration variables, we join the section name, subsection name, and variable name together with dots to get a key name that looks like section.subsection.variable. These are the strings that you’ll be passing in to key arguments.

Configuration files inherit from each other. By default, Config::GitLike loads data from a system-wide configuration file, a per-user configuration file, and a per-directory configuration file, but by subclassing and overriding methods you can obtain any combination of configuration files. By default, configuration files that don’t exist are just skipped.

See <> for details on the syntax of git configuration files. We won’t waste pixels on the nitty gritty here.

While the behavior of a couple of this module’s methods differ slightly from the git config equivalents, this module can read any config file written by git. The converse is usually true, but only if you don’t take advantage of this module’s increased permissiveness when it comes to key names. (See DIFFERENCES FROM GIT-CONFIG for details.)

This is an object-oriented module using Moo. All subroutines are object method calls.

A few methods have parameters that are always used for the same purpose:


All methods that change things in a configuration file require a filename to write to, via the filename parameter. Since a Config::GitLike object can be working with multiple config files that inherit from each other, we don’t try to figure out which one to write to automatically and let you specify instead.


All get and set methods can make sure the values they’re returning or setting are valid values of a certain type: bool, int, num, or bool-or-int (or at least as close as Perl can get to having these types). Do this by passing one of these types in via the as parameter. The set method, if told to write bools, will always write true or false (not anything else that cast considers a valid bool).

Methods that are told to cast values will throw exceptions if the values they’re trying to cast aren’t valid values of the given type.

See the cast method documentation for more on what is considered valid for each type.


All get and set methods can filter what values they return via their filter parameter, which is expected to be a string that is a valid regex. If you want to filter items OUT instead of IN, you can prefix your regex with a ! and that will do the trick.

Now, on the the methods!


There are the methods you’re likely to use the most.

    new( confname => ’config’, encoding => ’UTF-8’ )

Create a new configuration object with the base config name confname. If you are interested simply in loading one specific file, and not in automatically loading a global file, a per-user file, and a per-directory file, see load_file, below.

confname is used to construct the filenames that will be loaded; by default, these are /etc/confname (global configuration file), ~/.confname (user configuration file), and <Cwd/.confname> (directory configuration file).

You can override these defaults by subclassing Config::GitLike and overriding the methods global_file, user_file, and dir_file. (See METHODS YOU MAY WISH TO OVERRIDE for details.)

If you wish to enforce only being able to read/write config files that git can read or write, pass in compatible => 1 to this constructor. The default rules for some components of the config file are more permissive than git’s (see DIFFERENCES FROM GIT-CONFIG).

If you know that your Git config files are encoded with a known character encoding, pass in encoding => $encoding to specify the name of the encoding. Config::GitLike will then properly serialize and deserialize the files with that encoding. Note that configutation files written with git config are usually, but are not required to be, in UTF-8.


The configuration filename that you passed in when you created the Config::GitLike object. You can change it if you want by passing in a new name (and then reloading via load).


This method is usually called implicitly on the first get, get_all, get_regex, or dump call used, and is only necessary if you want to explicitly reload the data.

Load the global, local, and directory configuration file with the filename confname(if they exist). Configuration variables loaded later override those loaded earlier, so variables from the directory configuration file have the highest precedence.

Pass in an optional path, and it will be passed on to load_dirs (which loads the directory configuration file(s)).

Returns a hash copy of all loaded configuration data stored in the module after the files have been loaded, or a hashref to this hash in scalar context.


An array reference containing the absolute filenames of all config files that are currently loaded, in the order they were loaded.



    key => sect.subsect.key
    as => int
    human => 1
    filter => !foo

Return the config value associated with key cast as an as.

The key option is required (will return undef if unspecified); the as amd human options are not (see cast for their meaning). Sections and subsections are specified in the key by separating them from the key name with a . character. Sections, subsections, and keys may all be quoted (double or single quotes).

If key doesn’t exist in the config, or has no values which match the filter, undef is returned. Dies with the exception Multiple values if the given key has more than one value associated with it which match the filter. (Use get_all to retrieve multiple values.)

Calls load if it hasn’t been done already. Note that if you’ve run any set calls to the loaded configuration files since the last time they were loaded, you MUST call load again before getting, or the returned configuration data may not match the configuration variables on-disk.



    key => section.sub
    as => int
    human => 1
    filter => regex

Like get but does not fail if the number of values for the key is not exactly one.

Returns a list of values (or an arrayref in scalar context).



    key => regex
    as => bool
    human => 1
    filter => regex

Similar to get_all but searches for values based on a key regex.

Returns a hash of name/value pairs (or a hashref in scalar context).


In scalar context, return a string containing all configuration data, sorted in ASCII order, in the form:


If called in void context, this string is printed instead.

In list context, returns a hash containing all the configuration data.



    key =>
    value => bar
    filename => File::Spec->catfile(qw/home user/, ..$config->confname)
    filter => regex
    as => bool
    multiple => 1
    replace_all => 1

Set the key foo in the configuration section section to the value bar in the given filename.

Replace key’s value if key already exists.

To unset a key, pass in key but not value.

Returns true on success.

If you need to have a . character in your variable name, you can surround the name with quotes (single or double): key => section."" Don’t do this unless you really have to.

multiple values

By default, set will replace the old value rather than giving a key multiple values. To override this, pass in multiple => 1. If you want to replace all instances of a multiple-valued key with a new value, you need to pass in replace_all => 1 as well.

group_set( CW$filename, CW$array_ref )

Same as set, but set a group of variables at the same time without writing to disk separately for each.

$array_ref contains a list of hash references which are essentially hashes of arguments to set, excluding the $filename argument since that is specified separately and the same file is used for all variables to be set at once.



    from => name.subname
    to => new.subname
    filename => /file/to/edit

Rename the section existing in filename given by from to the section given by to.

Throws an exception No such section if the section in from doesn’t exist in filename.

If no value is given for to, the section is removed instead of renamed.

Returns true on success, false if filename didn’t exist and thus the rename did nothing.



    section => section.subsection
    filename => /file/to/edit

Just a convenience wrapper around rename_section for readability’s sake. Removes the given section (which you can do by renaming to nothing as well).



     comment   => "Begin editing here\n and then stop",
     filename  => /file/to/edit
     indented  => 1,
     semicolon => 0,

Add a comment to the specified configuration file. The comment and filename parameters are required. Comments will be added to the file with # at the begnning of each line of the comment. Pass a true value to semicolon if you’d rather they start with ; . If your comments are indented with leading white space, and you want that white space to appear in front of the comment character, rather than after, pass a true value to indented.

cascade( CW$bool )

Gets or sets if only the <B>deepestB> configuration file in a directory tree is loaded, or if all of them are loaded, shallowest to deepest. Alternately, cascade => 1 can be passed to new.


Returns a hash mapping each config key with the file it was loaded from.


If your application’s configuration layout is different from the default, e.g. if its home directory config files are in a directory within the home directory (like ~/.git/config) instead of just dot-prefixed, override these methods to return the right directory names. For fancier things like altering precedence, you’ll need to override load as well.


Return a string containing the path to a configuration file with the name confname in a directory. The directory isn’t specified here.


Return the string /etc/confname, the absolute name of the system-wide configuration file with name confname.


Return a string containing the path to a configuration file in the current user’s home directory with filename confname.




Load the configuration file with the filename dir_file in the current working directory into the memory or, if there is no config matching dir_file in the current working directory, walk up the directory tree until one is found. (No error is thrown if none is found.) If an optional path is passed in, that directory will be used as the base directory instead of the working directory.

You’ll want to use load_file to load config files from your overridden version of this subroutine.

Returns nothing of note.


These are mostly used internally in other methods, but could be useful anyway.


If a global configuration file with the absolute name given by global_file exists, load its configuration variables into memory.

Returns the current contents of all the loaded configuration variables after the file has been loaded, or undef if no global config file is found.


If a configuration file with the absolute name given by user_file exists, load its config variables into memory.

Returns the current contents of all the loaded configuration variables after the file has been loaded, or undef if no user config file is found.

load_file( CW$filename )

Takes a string containing the path to a file, opens it if it exists, loads its config variables into memory, and returns the currently loaded config variables (a hashref).

This method can also be called as a class method, which will die if the file cannot be read. If called as an instance method, returns undef on failure.

This method may also be passed additional key-value parameters which control how the file is loaded:
silent Defaults to off; if set, merely returns instead of die’ing if the file cannot be found or read.
includes Defaults to on; if passed a false value, ignores the include directive.
force Defaults to off; if set, will re-load a file even if it was previously loaded.



    content => str
    callback => sub {}
    error => sub {}

Parses the given content and runs callbacks as it finds valid information.

Returns undef on success and error($content) (the original content) on failure.

callback is called like:

    callback(section => $str, offset => $num, length => $num, name => $str, value => $str)

name and value may be omitted if the callback is not being called on a key/value pair, or if it is being called on a key with no value.

error is called like:

    error( content => $content, offset => $offset )

Where offset is the point in the content where the parse error occurred.

If you need to use this method, you might be interested in error_callback as well.



    content => str
    offset => 45
    filename => /foo/bar/.baz

Made especially for passing to parse_content, passed through the error parameter like this:

    error => sub {
        error_callback( @_, filename => /file/you/were/parsing )

It’s used internally wherever parse_content is used and will throw an exception with a useful message detailing the line number, position on the line, and contents of the bad line; if you find the need to use parse_content elsewhere, you may find it useful as well.

include ( CW$name )

When reading configuration files, Git versions 1.7.10 and later parse the include.path key as a directive to include an additional configuration file. This option controls the equivalent behavior; setting it to a false value will disable inclusion, and any true value will be taken as the name of the configuration parameter which controls inclusion. Defaults to include.path, as Git does.

set_multiple( CW$name )

Mark the key string $name as containing multiple values.

Returns nothing.

is_multiple( CW$name )

Return a true value if the key string $name contains multiple values; false otherwise.



    section => str
    name => str
    value => str

Given a section, a key name, and a value, store this information in memory in the config object.

Returns the value that was just defined on success, or undef if no name and section were given and thus the key cannot be defined.



    value => foo
    as => int
    human => 1

Return value cast into the type specified by as.

Valid values for as are bool, int, num, or bool-or-num. For bool, true, yes, on, 1, and undef are translated into a true value (for Perl); anything else is false. Specifying a true value for the human argument will get you a human-readable ’true’ or ’false’ rather than a value that plays along with Perl’s definition of truthiness (0 or 1).

For ints and nums, if value ends in k, m, or g, it will be multiplied by 1024, 1048576, and 1073741824, respectively, before being returned. ints are truncated after being multiplied, if they have a decimal portion.

bool-or-int, as you might have guessed, gives you either a bool or an int depending on which one applies.

If as is unspecified, value is returned unchanged.



    section => section.subsection
    base => 1

Return a string containing the section/subsection header, formatted as it should appear in a config file. If bare is true, the returned value is not followed be a newline.



    key => str
    value => str
    bare => 1

Return a string containing the key/value pair as they should be printed in the config file. If bare is true, the returned value is not tab-indented nor followed by a newline.

canonical_case( CW$name )

Given a full key name, returns the canonical name of the key; this is the key with the section and name lower-cased; the subsection is left as-is.

original_key( CW$name )

Given a full key name, returns the key as it was last loaded from the file, retaining what ever upper/lower case was used. Note that for multiple-valued keys, this returns an array reference of key names, as each definition may have been provided in a different choice of case.


This module does the following things differently from git-config:

We are much more permissive about valid key names and section names. For variables, instead of limiting variable names to alphanumeric characters and -, we allow any characters except for = and newlines, including spaces as long as they are not leading or trailing, and . as long as the key name is quoted. For sections, any characters but whitespace, [], and " are allowed. You can enforce reading/writing only git-compatible variable names and section headers by passing compatible => 1 to the constructor.

When replacing variable values and renaming sections, we merely use a substring replacement rather than writing out new lines formatted in the default manner for new lines. Git’s replacement/renaming (as of is currently buggy and loses trailing comments and variables that are defined on the same line as a section being renamed. Our method preserves original formatting and surrounding information.

We also allow the ’num’ type for casting, since in many cases we might want to be more lenient on numbers.

We truncate decimal numbers that are cast to ints, whereas Git just rejects them.

We don’t support NUL-terminating output (the --null flag to git-config). Who needs it?


If you find any bugs in this module, report them at:

Include the version of the module you’re using and any relevant problematic configuration files or code snippets.


<>, Config::GitLike::Git, <> (Config::GitLike is used in Prophet/SD and provides a working example)


This program is free software; you may modify and/or redistribute it under the same terms as Perl itself.


Copyright 2010 Best Practical Solutions, LLC


Alex Vandiver <>, Christine Spang <>
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 CONFIG::GITLIKE (3) 2015-02-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.