🔧 git-nest configuration (`nestmodules.toml`)

[jeftadlvw]

In order for git-nest to work, a configuration file is needed. Technically .gitmodules from git submodule offers an already existing configuration file, but in the near future other configurations may be needed. This is why this issue proposes a configuration format: nestmodules.toml.

[config]
  # future configuration here

[[submodule]]
  path = "path-to-submodule"
  url = "https://url/to/repository"
  ref = "branch, tag or commit"

Using the toml configuration language (https://toml.io) offers a well-known and well-supported syntax that leaves enough room for future changes.

The nestmodules.toml-file should be located at the project's root directory or within a .config subdirectory. If it does not exist, git-nest creates it at the root directory.

Submodules are declared as an array of tables with three values:

• path: path to local subdirectory where module is located
• url: remote repository url of module
• ref: version of repository to check out

Both pathand url are required keys, wheras ref is optional.

This specification will most likely go through some iterations. It will be stable with version 1.0.0.

[jeftadlvw]

For the first 0.0.1 release, only one url should be supported (http(s) OR ssh). In later releases, multiple methods for cloning a repository should be made possibe by making url an array of strings. This is a hard requirement and will cause some restructuring in the codebase. But until 0.0.1, this is enough to keep the release-fingerprint "small"

[config]
  # future configuration here

[[submodule]]
  path = "path-to-submodule"
  url = [
    "https://url/to/repository",
    "ssh://user@host:another/url/to/same/repository"
  ]
  ref = "branch, tag or commit"

Further releases should also include some form of auto-guessing an https or git-url, based on the clone-method of the root project.

[jeftadlvw]

It may be better to have a generic representation of a url that can be converted into multiple supported protocols (the obvious being http/https and ssh). The problem is that they both share the same structure (hostname and path), but everything behind that is specific for that protocol.

Take port numbers for example. Http uses 80, Https 443. Ssh by default 22. All these ports can be changed by the hosting solution and the protocol specifications allow custom ports. Custom port numbers need to be stored for every supported url type.

A possible solution would be to use a basic structure like hostname$path and add every other customization as tags behind it: hostname$path[tag-1:foo | tag-2:bar | tag-3:baz].

Some practical tags could be:

• http-port: int
• http-secure: boolean
• ssh-port: int
• ssh-user: string

Each tag has a documented default value. The final configuration could look like this:

[config]
  # future configuration here

[[submodule]]
  path = "path-to-submodule"
  url = "hostname$path[http-secure: true | ssh-port:5000]"
  ref = "branch, tag or commit"

[jeftadlvw]

It may be better to have a generic representation of a url that can be converted into multiple supported protocols (the obvious being http/https and ssh). The problem is that they both share the same structure (hostname and path), but everything behind that is specific for that protocol.

Take port numbers for example. Http uses 80, Https 443. Ssh by default 22. All these ports can be changed by the hosting solution and the protocol specifications allow custom ports. Custom port numbers need to be stored for every supported url type.

A possible solution would be to use a basic structure like hostname$path and add every other customization as tags behind it: hostname$path[tag-1:foo | tag-2:bar | tag-3:baz].

Some practical tags could be:

* `http-port`: `int`

* `http-secure`: `boolean`

* `ssh-port`: `int`

* `ssh-user`: `string`

Each tag has a documented default value. The final configuration could look like this:

[config]
  # future configuration here

[[submodule]]
  path = "path-to-submodule"
  url = "hostname$path[http-secure: true | ssh-port:5000]"
  ref = "branch, tag or commit"

This comment has been converted to an issue: #10

[jeftadlvw]

9 adds names for each submodule for easier referencing.

[jeftadlvw]

This discussion will be closed, as v0.0.1 was released and any further additions to the configuration will most likely extend the current configuration structure.