Workspace Management

The following group of commands is used to create and modify workspaces.

git ws clone

Clone a Git Workspace managed project and prepare the workspace folder.

Usage: git-ws clone [OPTIONS] URL [MAIN_PATH]...

  Create a git clone from URL and initialize Git Workspace.

  MAIN_PATH is optional. If not specified `REPONAME/REPONAME/` by default.

Options:
  -w, --ws-path DIRECTORY    Workspace Path. Parent directory of main project
                             by default.
  -M, --manifest FILE        Manifest file. 'git-ws.toml' 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.
                             The setting becomes default for all successive
                             runs.
  --revision TEXT            Revision to be checked out. Tag, Branch or SHA
  --depth INTEGER            Create clones shallow of that depth.
  -U, --update               Run 'git ws update' too.
  -f, --force                Enforce operation.
  -h, --help                 Show this message and exit.

This is one of the two basic commands which can be used to initialize a workspace for an existing project. If you have a suitable project on a server and aim to create a new workspace from it, you would run something like this:

cd Projects
git ws clone https://example.com/my-project

This will:

  • Create a sub-directory called my-project.

  • Clone and checkout the specified project as a sub-folder into that one (i.e. into my-project/my-project).

Note

You will need to run git ws update to also fetch dependencies. Alternatively, you can use the --update option of the clone command to run the update right away.

The clone operation can be customized using some additional options:

  • By default, the file git-ws.toml in the main project will be used to start searching for dependencies. The --manifest option can be used to override this and point to another file (relative to main project’s root folder).

  • The --group-filter option can be used to fine tune the dependencies that are included (or excluded). Read more about this in Group Filtering.

  • The --update option can be used to run the git ws update command right away during the clone operation.

  • If desired, you can specify a path to a folder to be used as workspace folder.

Warning

The default way of operation for Git Workspace is to put all git clones side-by-side. For this reason, if, during the clone operation, any other file or folder is detected within the workspace folder, the operation will stop. You can use the --force option to still continue in this case.

git ws init

Prepare a workspace folder from an existing git clone.

Usage: git-ws init [OPTIONS] [MAIN_PATH]...

  Initialize Git Workspace *with* or *without* main project.

  *with* main project: run `git ws init` in the directory of an current git
  clone OR run `git ws init PATH_TO_MAIN_GIT_CLONE`. The git clone becomes the
  main project in both cases.

  *without* main project: run `git ws init` in the intended workspace
  directory. No main git project is needed.

  In any of these cases a manifest file (i.e. `git-ws.toml`) is required. It
  can be created via `git ws manifest create`.

Options:
  -w, --ws-path DIRECTORY    Workspace Path. Parent directory of main project
                             or current working directory by default.
  -M, --manifest FILE        Manifest file. 'git-ws.toml' 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.
                             The setting becomes default for all successive
                             runs.
  --depth INTEGER            Create clones shallow of that depth.
  -U, --update               Run 'git ws update' too.
  -f, --force                Enforce operation.
  -h, --help                 Show this message and exit.

This command is pretty similar to the git ws clone command, except that it operates on an existing git clone. Typically, it is used like this:

cd Projects
mkdir my-workspace
cd my-workspace
git clone https://example.com/my-project
cd my-project
git ws init

Typically, using git ws clone is a bit shorter and more concise. In fact, the both share most of their options (so refer to git ws clone to learn more about possible tweaks). The main use case of git ws init is when e.g. a CI/CD system already cloned the main project and the workspace needs to be initialized from that existing clone.

git ws update

Fetch dependencies and check them out at the revision specified in the manifest.

Usage: git-ws update [OPTIONS]

  Create/update all dependent git clones.

Options:
  -P, --project DIRECTORY    Project path to operate on only. All by default.
                             This option can be specified multiple times.
  -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.
  -S, --skip-main            Skip Main Repository
  --rebase                   Run 'git rebase' instead of 'git pull'
  --prune                    Remove obsolete git clones
  -f, --force                Enforce operation.
  -h, --help                 Show this message and exit.

The git ws update command is used to actually create a workspace and keep it up-to-date. After initializing a workspace using git ws init or git ws clone, use this command to clone also all dependencies and check them out at the revision specified in the project’s manifest file:

cd Projects
git ws clone https://example.com/my-project
cd my-project
git ws update

Note

Instead of using two different commands, you can also use the --update option to run the init/clone and update commands in one go.

Another use case is keeping a workspace up-to-date. For example, after getting changes for the main project, the revision for some of the included dependencies might have changed. In this case, update can be used to change to the newly specified revision:

cd Projects/my-project/my-project/
git pull
git ws update

There are also some additional options which can be used to further tweak the command:

  • You can use the --project option to specify which project to operate on. This option can be used multiple times. Unless otherwise specified, the command operates on all projects in a workspace. Using this option, the update can be limited to the given projects only.

  • As with the clone and init commands, you can specify an alternative manifest using the --manifest option. The operation can be further limited using the --group-filter filter. See Group Filtering for more information.

  • By default, the update will also pull changes from the server, including the main project. If this is not desired, pulling the main repository can be avoided by using the --skip-main option.

  • If preferred, one can use the --rebase option to run a git rebase instead of a git pull.

  • By using --prune, git clones that became obsolete (i.e. because they are no longer referenced as a dependency) will be removed from the workspace.

  • --prune checks obsolete clones to be empty. If the clone contains untracked files, uncommitted changes, unpushed commits or stashed changes, the prune operation will fail. Use --force to disable this check.

git ws deinit

De-initialize a workspace.

Usage: git-ws deinit [OPTIONS]

  Deinitialize Git Workspace.

Options:
  --prune      Remove obsolete git clones
  -f, --force  Enforce operation.
  -h, --help   Show this message and exit.

This command is used to remove any Git Workspace related information from a workspace folder. Basically this will remove the .git-ws folder and hence any kind of workspace settings. This can be useful if the workspace folder is going to be reused:

cd Projects/my-project
git ws deinit
# Note the use of the --force option:
git ws init ./another-project --force

In this example, we remove the workspace settings which were based on the former main project and then re-initialize the workspace pointing the init command to one of the former dependencies (making it the new main project). Note that we have to use the --force option as otherwise git ws would stop with a warning that there already are some folders (other than the main project) in the workspace folder.

git ws info

Retrieve information about the workspace.

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

  Git Workspace Information.

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

Commands:
  base-path       Print Path to Main Project Or Workspace.
  dep-tree        Print Dependency Tree.
  main-path       Print Path to Main Project.
  project-paths   Print Paths to all git clones.
  workspace-path  Print Path to Workspace.

This command has further sub-commands which can be used to get information about the workspace. In particular, these commands are the following:

git ws info base-path

Get the path to the main project (identical to git ws info main-path) on workspaces with a main project. The command returns the workspace path (identical to git ws info workspace-path) on workspaces without a main project.

Usage: git-ws info base-path [OPTIONS]

  Print Path to Main Project Or Workspace.

  Print path to main project on workspaces *with* main project. Print path to
  workspace on workspaces *without* main project.

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

git ws info dep-tree

Show the dependency tree of the project.

Usage: git-ws info dep-tree [OPTIONS]

  Print Dependency Tree.

  The standard output on '--dot' can be directly forwarded to `graphviz`'s
  tool `dot`.

  Example:

  $ git ws info dep-tree --dot | dot -Tpng > dep-tree.png

  $ git ws info dep-tree --dot | dot -Tsvg > dep-tree.svg

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.
  -d, --dot                  Export DOT Format to be forwarded to graphviz.
  -p, --primary              Display primary dependencies only.
  -h, --help                 Show this message and exit.

This command can be useful to show the dependency tree for an existing project. By default, the tree structure is printed out like this:

my-project
└── my-lib (revision='main')

Using the --dot option, the command generates output that can be fed into the Graphviz tools such as dot:

git ws info dep-tree --dot
## Should print something like
# digraph tree {
#     "my-project";
#     "my-lib";
#     "my-project" -> "my-lib" [label="main"];
# }

Running it through dot would generate a graph like this:

../../_images/sample-dep-tree-graph.png

git ws info main-path

Get the path to the main project within a workspace.

Usage: git-ws info main-path [OPTIONS]

  Print Path to Main Project. This command fails on workspaces without main
  project.

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

This command simply prints the path to the main project for the current workspace:

git ws info main-path
## Should print something like
# /home/User/Projects/my_workspace/my_project

git ws info project-paths

Show the paths to all projects within a workspace.

Usage: git-ws info project-paths [OPTIONS]

  Print Paths to all git clones.

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 list of paths to all projects within a workspace. For example:

git ws info project-paths
## Should print something like
# /home/User/Projects/my_workspace/my_project
# /home/User/Projects/my_workspace/my_lib1
# /home/User/Projects/my_workspace/my_lib2

Warning

If all you want is to iterate over all projects and run some actions on then, consider using git ws foreach instead.

git ws info workspace-path

Show the path to the workspace folder.

Usage: git-ws info workspace-path [OPTIONS]

  Print Path to Workspace.

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

This command simply prints the path to the workspace folder like that:

git ws info workspace-path
## Should print something like
# /home/User/Projects/my_workspace

git ws unshallow

Convert a shallow workspace into a full one.

Usage: git-ws unshallow [OPTIONS]

  Convert Shallow Clones To Complete Ones.

  Given projects are fetched and converted to complete clones with entire
  history if not already. Without any given project, all existing clones will
  be converted and any future clone will be complete too.

Options:
  -P, --project DIRECTORY    Project path to operate on only. All by default.
                             This option can be specified multiple times.
  -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.

You can run this command in a workspace that has been created using the shallow option to unshallow any repository in it. Shallow git clones have certain disadvantages (after all, they only contain part of the overall history, which can make certain operations impossible or will lead to unexpected side effects when e.g. scripts are used to extract historic information). If you started with a shallow workspace to speed up clone times but you realize you need a full workspace instead, use this command to upgrade the existing workspace.