Manifest

The manifest is one of the core aspects of git ws: It contains the needed meta information of a project about its dependencies as well as other configurations. git ws provides several commands that allow to work with manifest files, create them as well as alter them.

git ws manifest

Work with manifest files.

Usage: git-ws manifest [OPTIONS] COMMAND [ARGS]...

  Manifest Information.

Options:
  -h, --help  Show this message and exit.

Commands:
  convert   Convert Any Supported Manifest Format To Git Workspace Manifest.
  create    Create Manifest.
  freeze    Print The Resolved Manifest With SHAs For All Project Revisions.
  path      Print Path to Main Manifest File.
  paths     Print Paths to ALL Manifest Files.
  resolve   Print The Manifest With All Projects And All Their Dependencies.
  upgrade   Update Manifest To Latest Version.
  validate  Validate The Current Manifest, Exiting With An Error On Issues.

Git Workspace extensively uses manifest files to store meta information and manage dependencies. The git ws manifest command allows working with these manifest files, creating them and play other tricks needed in the daily workflow.

git ws manifest create

Create a new manifest.

Usage: git-ws manifest create [OPTIONS]

  Create Manifest.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command generates a new manifest file. The generated file comes with some built-in documentation, hence, editing the file should be quite easy. Refer to Manifest to learn more about the general structure of the manifest file.

# Generate a new manifest and write it to file git-ws.toml
git ws manifest create

# Create a new manifest, writing it to my-custom-manifest.toml
git ws manifest create --manifest my-custom-manifest.toml

git ws manifest freeze

Freeze a project.

Usage: git-ws manifest freeze [OPTIONS]

  Print The Resolved Manifest With SHAs For All Project Revisions.

  The output is identical to resolve, a single manifest file with all
  dependencies and their dependencies. Revisions are replaced by the current
  SHAs.

Options:
  -M, --manifest FILE        Manifest file. Initial/Configuration settings by
                             default.
  -G, --group-filter FILTER  Group Filtering. All groups from the main
                             manifest are enabled by default, unless
                             deactivated by the `[group-filters]` section or
                             this option. This option has the highest
                             precedence and can be specified multiple times.
                             Initial clone/init filter settings are used by
                             default.
  -O, --output FILE          Write Manifest to file instead of STDOUT.
  -h, --help                 Show this message and exit.

This command is useful to create a frozen state of a project. Often, projects will pull in dependencies on branches or tags. This means that - depending on when the workspace is created, the concrete content might differ. However, there are use cases where a particular state of a workspace needs to be conserved, e.g. when running a CI/CD pipeline for a particular snapshot of the project. This is exactly what the freeze command does. It creates a new manifest from the current one but fixes each dependency on its specific git commit hash. Also transitive dependencies are recorded.

# Create a frozen manifest and write it to standard output:
git ws manifest freeze

# Create a frozen manifest but write it to a file:
git ws manifest freeze --output git-ws-v2.3.4.toml

The freezing mechanism is internally used by the git ws tag command as well.

To recreate a historic state of the project, one can use the --manifest option of the various git ws commands to use the alternative, frozen manifest, e.g.:

# Example 1: Clone a project and build a workspace using a frozen manifest:
git ws clone https://example.com/my-project --manifest git-ws-v1.2.3.toml

# Example 2: Freeze the project state in a CI/CD pipeline and use it throughout the jobs.
#
# Typically, we would have a pipeline which in the very beginning creates a frozen manifest
# which is then uploaded as artifact:
git ws manifest freeze --output git-ws-current-version.toml

# Any later job in the pipeline would then first update the workspace to the frozen state:
git ws update --manifest git-ws-current-version.toml

git ws manifest path

Print the path to the main manifest:

Usage: git-ws manifest path [OPTIONS]

  Print Path to Main Manifest File.

Options:
  -M, --manifest FILE        Manifest file. Initial/Configuration settings by
                             default.
  -G, --group-filter FILTER  Group Filtering. All groups from the main
                             manifest are enabled by default, unless
                             deactivated by the `[group-filters]` section or
                             this option. This option has the highest
                             precedence and can be specified multiple times.
                             Initial clone/init filter settings are used by
                             default.
  -h, --help                 Show this message and exit.

This command prints the path to the manifest of the main project.

git ws manifest path
## Should print something like:
# /home/User/Projects/my_workspace/my_project/git-ws.toml

git ws manifest paths

Print the paths of all manifest files (i.e. the main project and all, also transitive, dependencies).

Usage: git-ws manifest paths [OPTIONS]

  Print Paths to ALL Manifest Files.

Options:
  -M, --manifest FILE        Manifest file. Initial/Configuration settings by
                             default.
  -G, --group-filter FILTER  Group Filtering. All groups from the main
                             manifest are enabled by default, unless
                             deactivated by the `[group-filters]` section or
                             this option. This option has the highest
                             precedence and can be specified multiple times.
                             Initial clone/init filter settings are used by
                             default.
  -h, --help                 Show this message and exit.

This commands prints the paths to the main manifest file as well as any manifest files of dependencies:

git ws manifest paths
## Should print something like
# /home/User/Projects/my_workspace/my_project/git-ws.toml
# /home/User/Projects/my_workspace/my_lib1/git-ws.toml
# /home/User/Projects/my_workspace/my_lib2/git-ws.toml

git ws manifest resolve

Create a merged manifest.

Usage: git-ws manifest resolve [OPTIONS]

  Print The Manifest With All Projects And All Their Dependencies.

  The output is a single manifest file with all dependencies and their
  dependencies.

Options:
  -M, --manifest FILE        Manifest file. Initial/Configuration settings by
                             default.
  -G, --group-filter FILTER  Group Filtering. All groups from the main
                             manifest are enabled by default, unless
                             deactivated by the `[group-filters]` section or
                             this option. This option has the highest
                             precedence and can be specified multiple times.
                             Initial clone/init filter settings are used by
                             default.
  -O, --output FILE          Write Manifest to file instead of STDOUT.
  -h, --help                 Show this message and exit.

This command creates a new manifest from the current one, merging all the dependencies such that everything is contained stand-alone in one file.

# Create a resolved manifest, writing it to standard output:
git ws manifest resolve

# Same, but write to a file:
git ws manifest resolve --output git-ws-resolved.toml

Such a resolved manifest can be useful to understand the layout of the created workspace. In addition, it can be used to quickly create a tweaked workspace as it allows to easily point (transitive) dependencies to another revision.

git ws manifest upgrade

Upgrade an existing manifest.

Usage: git-ws manifest upgrade [OPTIONS]

  Update Manifest To Latest Version.

  User data is kept. User comments are removed. Comments are updated to the
  latest documentation.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

The intention of this command is to update existing manifest files when new versions of git ws introduce new options. In addition, the comments in the file will be updated to the current version.

git ws manifest upgrade

Any user specific values are kept as-is, however, comments are stripped from the file.

git ws manifest validate

Validate a manifest file.

Usage: git-ws manifest validate [OPTIONS]

  Validate The Current Manifest, Exiting With An Error On Issues.

Options:
  -M, --manifest FILE  Manifest file. Initial/Configuration settings by
                       default.
  -h, --help           Show this message and exit.

This command reads and validates a manifest file. If the file is valid, the command exits with an exit code of 0. In case the file is not valid, the error is printed and the command exits with an error code.

# Validate a file:
git ws manifest validate

## In case an error occurs, something like this might get printed:
# Error: Manifest 'my_project/git-ws.toml' is broken: 1 validation error for ManifestSpec
# dependencies -> 0 -> groups
#   value is not a valid tuple (type=type_error.tuple)

git ws default

Update the defaults in a manifest.

Usage: git-ws default [OPTIONS] {remote|revision|groups|with-
                      groups|submodules} VALUE

  Set DEFAULT in Manifest to VALUE.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command can be used to update values in the defaults section of a manifest. For example, if one wants to use a branch called stable in all projects in their environment as default one, this could be done like this:

git ws default revision stable

git ws dep

Programmatically edit dependencies of a project.

Usage: git-ws dep [OPTIONS] COMMAND [ARGS]...

  Manage Dependencies.

Options:
  -h, --help  Show this message and exit.

Commands:
  add     Add Dependency NAME.
  delete  Delete Dependency NAME.
  list    List Dependencies.
  set     Set ATTRIBUTE For Dependency DEP to VALUE.
  update  Automatically Update Revision and URL of Dependencies.

This is a complex command with - via its sub-commands - allows to edit the dependencies of a project on the command line.

git ws dep add

Add a new dependency to the project.

Usage: git-ws dep add [OPTIONS] NAME

  Add Dependency NAME.

Options:
  --remote TEXT             Remote
  --sub-url TEXT            Sub-URL
  --url TEXT                URL
  --revision TEXT           Revision
  --path TEXT               Path
  --dep-manifest-path TEXT  Dependency Manifest Path
  --groups TEXT             Groups
  --with-groups TEXT        With Groups
  --submodules TEXT         Submodules
  -M, --manifest FILE       Manifest file. 'git-ws.toml' by default.
  -h, --help                Show this message and exit.

This command can be used to add new dependencies to a project. At least, the name of the dependency is required - other information is - if not explicitly specified - derived from the name.

# Add a new dependency
git ws dep add some-library

# Add a new dependency which is located on a different server,
# hence, specify its clone URL as well:
git ws dep add another-library --url https://example.com/another-library.git

# Add yet another dependency, on the same server but include it with a
# specific revision:
git ws dep add yet-another-library --revision v1.2.3

git ws dep delete

Remove a dependency.

Usage: git-ws dep delete [OPTIONS] NAME

  Delete Dependency NAME.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This removes a dependency from the manifest:

git ws dep delete some-library

git ws dep list

List dependencies specified in the manifest.

Usage: git-ws dep list [OPTIONS]

  List Dependencies.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This prints the list of dependencies as specified in the manifest file.

git ws dep set

Update properties of a dependency.

Usage: git-ws dep set [OPTIONS] DEP {name|remote|sub-
                      url|url|revision|path|manifest-path|groups|with-
                      groups|submodules|recursive} VALUE

  Set ATTRIBUTE For Dependency DEP to VALUE.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command can be used to update the properties of a property. It takes the name of a dependency, the name of a property and a new value for it.

# Update the URL of a dependency:
git ws dep set some-library url https://new-server.org/some-library.git

# Update the revision of a dependency:
git ws dep set another-library revision v2.3.4

git ws dep update

Automatically update revision and url of dependencies.

Usage: git-ws dep update [OPTIONS] COMMAND [ARGS]...

  Automatically Update Revision and URL of Dependencies.

Options:
  -r, --recursive  Update all manifests, not just the main manifest
  -h, --help       Show this message and exit.

Commands:
  revision  Update Dependency Revisions.
  url       Update Dependency URLs.

Assume you have workspace and changed the checkout version of one or more dependencies. The following commands automatically updates the revision and/or url in the main manifest file and optionally in all dependencies.

# Update url and revision of main manifest dependencies
git ws dep update

# Update url and revision in *all* manifests
git ws dep update -r

# Update revision in *all* manifests
git ws dep update revision -r

# Update url in *all* manifests
git ws dep update url -r

git ws group-filters

Edit group filters specified in a manifest.

Usage: git-ws group-filters [OPTIONS] VALUE

  Set Group Filter to VALUE.

  The group filter selects/deselects dependencies based on their path and/or
  groups.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command allows setting the groups filters in the manifest:

git ws group-filters +some-group,-another-group

git ws remote

Edit remotes in a manifest.

Usage: git-ws remote [OPTIONS] COMMAND [ARGS]...

  Manage Remotes.

Options:
  -h, --help  Show this message and exit.

Commands:
  add     Add Remote NAME with URL_BASE.
  delete  Delete Remote NAME.
  list    List Remotes.

This complex command allows editing values in the remotes section of a manifest.

git ws remote add

Add a new remote.

Usage: git-ws remote add [OPTIONS] NAME URL_BASE

  Add Remote NAME with URL_BASE.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command adds a new remote to the manifest:

# Add a remote "my-remote" pointing to the given base URL:
git ws remote add my-remote https://some.server.com/

git ws remote delete

Remove a remote.

Usage: git-ws remote delete [OPTIONS] NAME

  Delete Remote NAME.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This removes the named remote from the manifest:

git ws remote delete my-remote

git ws remote list

List defined remotes.

Usage: git-ws remote list [OPTIONS]

  List Remotes.

Options:
  -M, --manifest FILE  Manifest file. 'git-ws.toml' by default.
  -h, --help           Show this message and exit.

This command simply lists the remotes that are defined in the manifest file.