configuration file

[kevgo]

The configuration file .git-branches stores long-lived configuration information that is common to all team members. This is part of #1030.

Roadmap

• basic config file: as an alternative to the Git-based configuration
• config changes: user changes a config setting
  • a config file exists: Updating the config file #2903
  • no config file: update the Git config
• command to migrate the Git configuration into a config file
  • We get this for free with the setup assistant. Just run the setup assistant. It reads the Git metadata. Keep all chosen options. Choose "config file" as the config location. The setup assistant writes the config to the file and removes the Git metadata.
• two configs: Git Town runs with both Git config and config file
  • migrate the Git config into the config file
• config conflict: Git Town runs with both Git config and config file and the settings disagree with each other
  • Git metadata config takes precedence over the config file

Reasons to use a configuration file:

Configuration files prevents obstacles that teams adopting or using Git Town are facing.

• configuration can be set up and maintained by one Git Town expert for the entire team
• configuration is guaranteed to be the same for everybody
• configuration is visible in clear text to everybody inspecting a repo
• configuration can be changed in proposals

Git Town only uses the Git configuration because the initial Bash implementation made it hard to parse JSON files, so using the Git configuration was an easy solution. Now that Git Town is written in a proper programming language, let's adopt a more idiomatic way of configuring Git Town.

Examples

For Git Town's simple configuration data, TOML seems the most readable and ergonomic option. JSON is nice because everybody knows it, but it struggles with capitalization, and the indented format looks weird. YML would make sense if the configuration is much more complex. For the simple config data here, it feels too technical.

JSON

{
  "mainBranch": "main",
  "perennialBranches": [ "public" ],
  "codeHostingPlatform": "github",
  "codeHostingOriginHostname": "github.com",
  "pushNewBranches": true,
  "syncFeatureStrategy": "merge",
  "syncPerennialStrategy": "rebase",
  "shipDeleteRemoteBranch": false,
  "syncUpstream": true,  
}

{
  "branches": {
    "main": "main",
    "perennials": ["public"]
  },
  "code-hosting": {
    "platform": "github",
    "origin-hostname": "github.com"
  },
  "sync-strategy": {
    "feature-branches": "merge",
    "perennial-branches": "rebase"
  },
  "pushNewBranches": true,
  "shipDeleteRemoteBranch": false,
  "syncUpstream": true
}

TOML

[branches]
main = "main"
perennials = [ "public" ]

[code-hosting]
platform = "github"
origin-hostname = "github.com"

[sync-strategy]
feature-branches = "merge"
perennial-branches = "rebase"

pushNewBranches = true
shipDeleteRemoteBranch = false
syncUpstream = true

branches.main = "main"
branches.perennials = [ "public" ]
code-hosting.platform = "github"
code-hosting.origin-hostname = "github.com"
sync-strategy.feature-branches = "merge"
sync-strategy.perennial-branches = "rebase"
pushNewBranches = true
shipDeleteRemoteBranch = false
syncUpstream = true

mainBranch = "main"
perennialBranches = [ "public" ]
codeHostingPlatform = "github"
codeHostingOriginHostname = "github.com"
pushNewBranches = true
syncFeatureStrategy = "merge"
syncPerennialStrategy = "rebase"
shipDeleteRemoteBranch = false
syncUpstream = true

YML

branches:
  main: "main"
  perennials:
    - "public"

code-hosting:
  platform: "github"
  origin-hostname: "github.com"

sync-strategy:
  feature-branches: "merge"
  perennial-branches: "rebase"

pushNewBranches: true
shipDeleteRemoteBranch: false
syncUpstream: true

[kevgo]

TOML parser for Go: https://github.com/BurntSushi/toml