Configuration

Caution

Since HuPKit v1.4 using global configuration for repositories is deprecated.

The examples in this chapter expect you are using HuPKit v1.4, any older versions are no longer supported.

If you are still using a version prior to v1.4 see Upgrade HuPKit how to to update your configuration.

Schema Version

The schema_version defines the configuration schema version.

At this moment only 1 and 2 are accepted, note that version 1 is deprecated and will no longer work in HuPKit v2.0+.

As some advanced features require local configuration it's best to use schema_version=2.

Authentication

Before HuPKit can be used to manage your repositories you first need to configure the GitHub authentication credentials.

Get a new token at: https://github.com/settings/tokens/new

Use a unique and distinct name like: hupkit on computer-1 at 2016-11-01 14:54 CET with scopes: repo, user:email, read:gpg_key.

HuPKit supports GitHub Enterprise, and therefor you can add multiple hub configurations by there hostname; The default host is github.com.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
// config.php

return [
    // ...
    'github' => [
        'github.com' => [ // hostname of the hub
            'username' => '', // fill-in your github username
            'api_token' => '', // fill-in the new GitHub authentication token (NOT YOUR PASSWORD!)
        ],
//        'hub.my-corp.com' => [ // hostname of your GitHub Enterprise installation
//            'username' => '', // fill-in your github username
//            'api_token' => '', // fill-in the new GitHub authentication token (NOT YOUR PASSWORD!)
//            'api_url' => 'https://api.hub.mycorp.com/' // schema + hostname to API endpoint (excluding API version)
//        ],
    ],
];

Repository Configuration

Specific features like repository splitting, or disabling upmerge for some branches only work when the configuration for a repository is set-up.

The configuration (and hook-scripts) are kept in a 'orphaned' branch "_hubkit".

Caution

For historical reasons the branch is named _hubkit, not _hupkit, in HuPKit v2.0 this will change.

An orphan branch has no relation to any other branch, it's fully separate, and thus has no common parent. This same technique is also used by GitHub for pages stored separate from the main branch.

Important

No authentication credentials must be stored in the _hupkit branch!

Initialize Configuration For a Repository

To create the HuPKit configuration branch run the init-config command.

The command will automatically import any existing global configuration for the repository from the HuPKit main config.php file, and all files stored in the ".hubkit" directory (of the current branch).

Note

The root .gitignore file is automatically copied from your current branch to ensure no unrelated files are accidentally added when working on the _hubkit branch.

The _hubkit branch sits separate from your normal Git workflow and shares no parenting to any existing branch.

The config.php file contains the configuration _only_ for the current repository.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
<?php
// config.php (in the `_hubkit` branch)

return [
    'schema_version' => 2,

    // Adapter configuration (optional, when cannot be resolved automatically)
    // 'adapter' => 'github', //Defaults to github, currently no other adapters supported
    // 'host' => 'github.com',
    // 'repository' => 'organization/repository-name',

    // Which branch is considered the main branch. Either: 'main', 'master', '2.0', or 'trunk'
    // This configuration is used (among) for upmerging as the last last branch in the list.
    //
    // If not set this is automatically guessed at application boot, in v2.0 this will default to 'main'.
    //'main_branch' => null,

    // See Branches section below for supported configuration
    'branches' => [],

    // Branches-alias for 'named' branches
    //
    // This only applies to branches that are not explicitly versioned (like 1.0, 1.5)
    // The value should be a stable major.minor version (not: 0.5, master, 1.5-dev, 1.2-beta1) but 1.0, 1.5, 23.4
    // 'branches_alias' => [
    //     // 'main' => '1.0',
    //     // 'dev/main' => '1.0',
    //     // '1.x' => '1.5',
    // ],

    //'pull_request' => [
           // Either:
           //  * 'all' (default)
           //  * 'changed-only' (only split changed files matched in prefixes)
           //  * 'none' (don't split, same as using the `--no-split` command option)
    //    'split' => 'all',
    //],

    //'release' => [
          // Either:
          // 'all' (default)
          // 'changed-only' (only create split releases for prefixes that have changed since the last release)
    //    'split' => 'all',

          // Either: true (default; enabled), false (explicitly disabled), or null (use Git config 'tag.gpgSign')
    //    'signed' => true,
    //],
];

Caution

It's best not to disable signing of Git tags.

Branches

A branch name can be either any valid branch-name, a minor-version pattern 2.x`/`v2.*, or a regexp (without anchors or options) like /[1-2]\.\d+/.

There is one special branch-name :default which allows to set-up the defaults all branches (see below).

Note

When an actual branch can be confused for a pattern (1.x) use #1.x instead.

Using the #branch-name works for all branches and considers the branch-name as a literal instead of a pattern or regexp.

The :default branch defines the default configuration for _all_ branches, and is later merged with the configuration of a specific branch. Use 'ignore-default' => true for a specific branch configuration to ignore inherited defaults.

When no specific branch is found like 'main' or '2.1' the correct configuration is resolved by traversing all (in order of listing) the patterns and regexp until a matching version is found.

If no configuration was found the :default configuration is used.

Use false as value for a branch to mark that branch as unmaintained. An unmaintained branch skips upmerging to and from this branch.

Using this option will give a warning whenever this branch is used for either merging, releasing, taking an issue, etc.

Tip

Use regexes like /[12]\.\d+/ or /main|dev/trunk|(12\.0)/ to use multiple versions or names at once (no anchors or head grouping, /main|master/ not /(main|12\.0)/).

As the configuration file is still Php it's also possible use variables for sharing configuration between branches.

Each branch has the following options:

Name Type Default Description
sync-tags Boolean true _Only when 'split' targets are configured; whether new tags should be synchronized when creating a release
ignore-default Boolean false Whether the ':default' configuration should be ignored
upmerge Boolean true Set to false to disable upmerge for this branch configuration, and continue with next possible version
split array [] See [Repository splitting](#splitting) for details.
maintained Boolean true true when maintained, use false as config value shorthand 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
// config.php

return [

    // ...

    'branches' => [
        ':default' => [
            'sync-tags' => true,
            'split' => [
                // A path (relative to root, no patterns) and the url to split to (with additional options)
                // See below for all options.
                'src/Module/CoreModule' => 'git@github.com:hubkit-sandbox/core-module.git',
                'src/Module/WebhostingModule' => 'git@github.com:hubkit-sandbox/webhosting-module.git',
                'docs' => ['url' => 'git@github.com:park-manager/doc.git', 'sync-tags' => false],
            ],
        ],
        'main' => [ // Can be any valid branch-name: dev/trunk, master, development
            'src/Module/CustomerModule' => 'git@github.com:hubkit-sandbox/customer-module.git',
        ],
        '1.0' => false, // Mark branch as unmaintained
        '2.x' => [ // '2.x' is a pattern equivalent to '/2\.\d+/'
            'upmerge' => false, // Disable upmerge for this branch, effectively all of the '2.x' range are skipped
            // Split's is inherited and merged from ':default'
            'split' => [
                'src/Module/DomainRegModule' => 'git@github.com:hubkit-sandbox/webhosting-module.git',
            ],
        ],
        '#3.x' => [ // The actual branch name is 3.x would be confused for a pattern
            'sync-tags' => null, // Inherit from the root configuration.
            'split' => [
                'src/Module/WebhostingModule' => false,
                'src/Module/DomainRegModule' => 'git@github.com:hubkit-sandbox/webhosting-module.git',
            ],
        ],
        '/4\.\d+/' => [ // Same as 4.x
            'ignore-default' => true, // Nothing is inherited from ':default'
            'sync-tags' => false,
            'src/Bundle/CoreBundle' => 'git@github.com:hubkit-sandbox/core-module.git',
            'src/Bundle/WebhostingBundle' => 'git@github.com:hubkit-sandbox/webhosting-module.git',
            'docs' => ['url' => 'git@github.com:park-manager/doc.git', 'sync-tags' => false],
        ],
    ],
];

Note

A branch cannot start with Git refs {heads, tags, remotes, notes}/, or be HEAD.

Repository splitting (`split` config)

A list of paths (relative to repository root, no patterns) and the value, either a 'push url' or an array with following options: ['url' => 'push url', 'sync-tags' => false].

Note

Missing directories are ignored with a warning. In HuPKit v2.0 this behavior is bound to change, use the branches configuration to ensure to paths aren't missing.

Splits are expected to exist, see also Managing Split Repositories.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
return [
    // ...

    'branches' => [
        ':default' => [
            // ...

            'split' => [
                'src/Module/CoreModule' => 'git@github.com:hubkit-sandbox/core-module.git',
                'src/Module/WebhostingModule' => 'git@github.com:hubkit-sandbox/webhosting-module.git',
                'docs' => ['url' => 'git@github.com:park-manager/doc.git', 'sync-tags' => false],
            ],
       ],
    ],
];

See also Managing Split Repositories

Editing Repository Configuration

Caution

Always run the self-diagnose command to check your configuration, and see if there any configuration violations before switching back to the main branch or synchronizing with the remote (see below).

If the application fails start due to a configuration error run HuPKit with the env HUBKIT_NO_LOCAL=true like HUBKIT_NO_LOCAL=true hupkit self-diagnose.

To change the contents of the _hubkit branch run the edit-config command.

In practice this checksout the _hubkit branch, but also ensures no files would be overwritten by this checkout (like a git-ignored config.php file.)

Synchronize Configuration

To update the configuration by either pushing your changes or pulling-in the latest version from "upstream" simply run the sync-config command.

Only if your branches have diverged to much you need to resolve any conflicts manually. Once done run the command again.

Use the self-diagnose command to check your configuration and see if any update (push or pull) is needed.

Remote names

By default HuPKit uses "upstream" as the remote-name for the main-repository. If for any reason you need to change this, either because you use a different convention or only use "origin" without a fork, you can use a local configuration file to change this.

Add a ".hk_remotes" file at the root-level of your repository with the following contents:

1
2
3
4
 
; Commented line

main = upstream
fork = origin

The config "main" is the main repository which all team-members pull and push from, "fork" is your own fork (if any).

Note

This is about remote names not actual repository url's.

The file format is similar to an ini-file, a line can contain either a comment (; Comment) or a variable ("main" or "fork"), no overwrites, no different names (than shown), and comments can only be used on their own line (not at the end of a variable declaration).

Important

This file should be ignored by Git as it only applies to your own local .git/config file and remote names.

Use the -v flag with any command to see which value is used.

Whats Next?

Run the self-diagnose command to ensure everything is configured correctly.

Tip

This command is best run from a Git repository.