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
andinit
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 agit rebase
instead of agit 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:
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.