Manifest

The main purpose of Git Workspace is to be able to compose a workspace consisting of one or more git repositories. For this, a single repository can define meta information including a list of dependencies to other git repositories. These information are stored in a file called git-ws.toml. To generate that file, all you need to do is running the following command inside your project:

git ws manifest create

This will create a template for the manifest file that you can edit to fit your needs. It contains:

The standard file created is self-documenting, so it should be relatively easy to get started with it:

version = "1.0"
##
## Git Workspace's Manifest. Please see the documentation at:
##
## https://git-ws.readthedocs.io/en/stable/manual/manifest.html
##


# group-filters = ["-doc", "-feature@path"]
group-filters = []


# [[remotes]]
# name = "myremote"
# url-base = "https://github.com/myuser"


[defaults]

# remote = "myserver"
# revision = "main"
# groups = ["test"]
# with-groups = ["doc"]


## A minimal dependency:
# [[dependencies]]
# name = "my"

## A full flavored dependency using a 'remote':
# [[dependencies]]
# name = "myname"
# remote = "remote"
# sub-url = "my.git"
# revision = "main"
# path = "mydir"
# groups = ["group"]
#
# [[dependencies.linkfiles]]
# src = "file0-in-mydir.txt"
# dest = "link0-in-workspace.txt"
#
# [[dependencies.linkfiles]]
# src = "file1-in-mydir.txt"
# dest = "link1-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file0-in-mydir.txt"
# dest = "file0-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file1-in-mydir.txt"
# dest = "file1-in-workspace.txt"

## A full flavored dependency using a 'url':
# [[dependencies]]
# name = "myname"
# url = "https://github.com/myuser/my.git"
# revision = "main"
# path = "mydir"
# groups = ["group"]
#
# [[dependencies.linkfiles]]
# src = "file0-in-mydir.txt"
# dest = "link0-in-workspace.txt"
#
# [[dependencies.linkfiles]]
# src = "file1-in-mydir.txt"
# dest = "link1-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file0-in-mydir.txt"
# dest = "file0-in-workspace.txt"
#
# [[dependencies.copyfiles]]
# src = "file1-in-mydir.txt"
# dest = "file1-in-workspace.txt"



# [[linkfiles]]
# src = "file-in-main-clone.txt"
# dest = "link-in-workspace.txt"


# [[copyfiles]]
# src = "file-in-main-clone.txt"
# dest = "file-in-workspace.txt"

In the following, the various parts of a manifest file are described.

The group-filters section

Dependencies might get categorized by groups. All groups in the main project are selected by default. The group-filters list manipulates this default behaviour. The last matching entry wins.

Statement

Effect

-group

deselect group

-group@path

deselect group but only at path

+group

reselect group

+group@path

reselect group but only at path

See Group Filtering for more information about group filtering.

The command git ws group-filters manipulates this section.

The remotes section

Remotes are simply aliases to git servers. A remote refers to a directory with git repositories. A remote has the following attributes:

Attribute

Type

Description

name

string

Mandatory. Name of the Alias. Used by [defaults] and [[dependencies]]

url-base

string

Mandatory. URL to a group of repositories. Not the repository itself!

Note

Local filesystem URLs must be prefixed by file://.

Multiple remotes look like this:

[[remotes]]
name = "company"
url-base = "https://git.company.com"

[[remotes]]
name = "github"
url-base = "https://github.com/user"

The command git ws remote manipulates this section.

The defaults section

The defaults section defines default values for all dependencies within the current manifest. If a dependency specifies the attribute explicitly the given value takes precedence and the default value is ignored. The following attributes are taken as default values in the [[dependencies]] section.

Attribute

Type

Description

remote

string

Optional. Name of a remote from the [[remotes]] section.

revision

string

Optional. Git branch or tag to be checked out.

groups

list of strings

Optional. Categorization of the dependency.

with-groups

list of strings

Optional. Group selection of the dependency.

Example defaults section:

[defaults]
remote = "myserver"
revision = "main"
groups = ["test"]
# with-groups = ["doc"]

The command git ws default manipulates this section.

Note

It is strongly recommended to specify a default revision:

[defaults]
revision = "main"

The dependencies section

The dependencies section is the one, the one this is all about — the listing of all other git clones you need, next to the current git clone. The following attributes provide all the freedom:

Attribute

Type

Description
name
string
Mandatory. The name of it.
remote
string
Optional. Name of a remote from the [[remotes]] section.
sub-url
string
Optional. URL relative to remote.url_base.
url
string
Optional. URL. Absolute or Relative.
Relative URLs are relative to repo containing the manifest.
Default is ../name if remote and sub-url are empty.
revision
string
Optional. Git branch, tag or SHA to be checked out.
path
string
Optional. Filesystem Path.
Relative to Workspace Root Directory.
name by default.
manifest-path
string
Optional. Path to the manifest file.
Relative to path.
git-ws.toml by default.
groups
list of strings
Optional. Categorization of the dependency.
with-groups
list of strings
Optional. Group selection of the dependency.
submodules
bool
Optional. Initialize git submodule s.
True by default.
linkfiles
list of src/dest
Optional. List of links to be created.
src is relative to path.
dest is relative to workspace.
See File Linking and Copying for more information
copyfiles
list of src/dest
Optional. List of files to be copied.
src is relative to path.
dest is relative to workspace.
See File Linking and Copying for more information

Please note:

  • remote and url are mutually exclusive. Do not specify both.

  • sub-url requires a remote and is always relative to remote.url_base.

  • url can be absolute or relative.

  • A relative url is relative to the remote which contains the current manifest file. More precise: it is relative to the url returned by git remote get-url origin in the git clone containing the manifest file

  • If the dependency is located on the same server in the same directory, name is the only required attribute. remote, sub-url and url can be simply left blank.

  • A manifest file located outside a git clone does not support relative url s.

  • Local filesystem URLs must be prefixed by file://.

  • linkfiles and copyfiles are only applied for dependencies in the main manifest. linkfiles and copyfiles in manifests referenced in the dependencies section are ignored.

A minimal dependency to a repo on the same server:

[[dependencies]]
name = "my"

A full flavored dependency using a remote:

[[dependencies]]
name = "myname"
remote = "remote"
sub-url = "my.git"
revision = "main"
path = "mydir"
groups = ["group"]

[[dependencies.linkfiles]]
src = "file0-in-mydir.txt"
dest = "link0-in-workspace.txt"

[[dependencies.copyfiles]]
src = "file1-in-mydir.txt"
dest = "file1-in-workspace.txt"

A full flavored dependency using a url:

[[dependencies]]
name = "myname"
url = "https://github.com/myuser/my.git"
revision = "main"
path = "mydir"
groups = ["group"]

[[dependencies.linkfiles]]
src = "file0-in-mydir.txt"
dest = "link0-in-workspace.txt"

[[dependencies.copyfiles]]
src = "file1-in-mydir.txt"
dest = "file1-in-workspace.txt"

The command git ws dep manipulates this section.

The linkfiles and copyfiles sections

The linkfiles section lists files to be linked over from the main project - the project which contains the manifest file. copyfiles are copied and not symbolic linked. Everything else is the same.

linkfiles and copyfiles entries have two mandatory attributes:

Attribute

Type

Description

src

string

Mandatory. Source file path, relative to the main project root directory

dest

string

Mandatory. Destination file path, relative to the workspace directory

groups

list of strings

Optional. Categorization. Just create if the group is selected.

Multiple entries look like that:

[[linkfiles]]
src = "file-in-main-clone0.txt"
dest = "link-in-workspace0.txt"

[[linkfiles]]
src = "file-in-main-clone1.txt"
dest = "link-in-workspace1.txt"
groups = ['test']

Note

linkfiles and copyfiles are also supported on standalone manifest files. src is relative to the workspace directory then.