Working With `git` Clones

Workspaces consist of one or more git clones. git ws provides several commands that can be used to conveniently work with these clones in the scope of the overall project.

`git ws foreach`

Run a command once for every git clone in a workspace.

Usage: git-ws foreach [OPTIONS] [COMMAND]...

  Run COMMAND on projects.

  Please use '--' to separate 'git ws' command line options from options
  forwarded to the COMMAND (i.e. `git ws foreach -- ls -l`)

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.
  -R, --reverse              Operate in Reverse Order. Start with last
                             dependency instead of main repository.
  -b, --on-branch            Limit operation to clones on branches only.
                             Detached HEAD clones (on tag or SHA) are ignored.
  -h, --help                 Show this message and exit.

This command is useful to run a shell command once for each git clone in a workspace. For example, the following would run a git status in all clones:

git ws foreach git status

The command can be fine tuned similarly to the git ws update command using the --project, --manifest and --group-filter options.
By default, the projects are traversed from the main project down to its dependencies. By using the --reverse option, the order in which the projects are visited are inverted.

`git ws git`

Run a git command for all clones within a workspace.

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

  Run git COMMAND on projects.

  This command is identical to `git ws foreach -- git COMMAND`.

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.
  -R, --reverse              Operate in Reverse Order. Start with last
                             dependency instead of main repository.
  -b, --on-branch            Limit operation to clones on branches only.
                             Detached HEAD clones (on tag or SHA) are ignored.
  -h, --help                 Show this message and exit.

This is similar to the git ws foreach, but automatically calls git. It is basically a shorthand for git ws foreach git.

# Run a git status in all projects:
git ws git status

# This is the equivalent for:
git ws foreach git status

`git ws pull`

Run a git pull in all clones within a workspace.

Usage: git-ws pull [OPTIONS] [COMMAND_OPTIONS]...

  Run 'git pull' on projects.

  This command is identical to `git ws foreach --on-branch -- git pull
  COMMAND_OPTIONS`.

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.

`git ws push`

Run a git push in all clones within a workspace.

Usage: git-ws push [OPTIONS] [COMMAND_OPTIONS]...

  Run 'git push' on projects (in reverse order).

  This command is identical to `git ws foreach --reverse --on-branch -- git
  push COMMAND_OPTIONS`.

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.

`git ws rebase`

Run a git rebase in all clones within a workspace.

Usage: git-ws rebase [OPTIONS] [COMMAND_OPTIONS]...

  Run 'git rebase' on projects.

  This command is identical to `git ws foreach --on-branch -- git rebase
  COMMAND_OPTIONS`.

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.

`git ws fetch`

Run a git fetch in all clones within a workspace.

Usage: git-ws fetch [OPTIONS] [COMMAND_OPTIONS]...

  Run 'git fetch' on projects.

  This command is identical to `git ws foreach -- git fetch COMMAND_OPTIONS`.

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.
  --unshallow                convert to a complete repository
  -h, --help                 Show this message and exit.

`git ws diff`

Run a git diff in all clones within a workspace.

Usage: git-ws diff [OPTIONS] [PATHS]...

  Run 'git diff' on PATHS or all files (displayed paths include the current
  clone path).

Options:
  --stat                     show diffstat instead of patch.
  -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 can be used to show the differences in clones in all clones within a workspace. Note that this command is not equivalent to calling git ws git diff: The command will show paths relative to the workspace folder. This is useful if you want to e.g. create a patch for an entire workspace:

cd Projects/my-workspace
git ws diff > changes.patch

cd ../another-workspace-version
patch -p1 < ../my-workspace/changes.diff

`git ws checkout`

Check out all projects to the revision specified in the manifest.

Usage: git-ws checkout [OPTIONS] [PATHS]...

  Run 'git checkout' on PATHS and choose the right git clone and manifest
  revision automatically.

  Checkout all clones to their manifest revision, if no paths are given.

Options:
  -f, --force                Enforce operation.
  -b TEXT                    create and checkout a new branch
  -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 can be used to check out all dependencies to the revision which has been specified in the manifest file. This can be useful if some repositories have been manually checked out to other revisions, as the command will ensure all repositories are on their well defined version.

cd Projects/my-workspace

# Switch some repository to a new branch:
cd some-dependency
git switch -c my-branch

# Now restore the state of the workspace:
git ws checkout

Warning

If no revision has been specified for some dependencies, this command will not change these dependencies, even if they are checked out on a revision other than the default branch.

`git ws status`

Show repository status of all projects within a workspace.

Usage: git-ws status [OPTIONS] [PATHS]...

  Run 'git status' on PATHS or all files (displayed paths include the current
  clone path).

Options:
  -b, --branch               show branch information
  -B, --banner               show banner of each project
  -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 is similar to running git ws git status, but the file paths shown will be modified such that they can be used with commands such as git ws add, git ws reset and git ws commit.

`git ws add`

Run a git add on the specified paths.

Usage: git-ws add [OPTIONS] [PATHS]...

  Run 'git add' on PATHS and choose the right git clone automatically.

Options:
  -f, --force                allow adding otherwise ignored files
  -A, --all                  add changes from all tracked and untracked files
  -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 can be used to conveniently add files to the index for later commit. It is mostly useful if there are modifications in multiple repositories. So instead of the following:

cd Projects/my-workspace

# Change into one project first:
cd some-project
git add ./some-file.txt

# Change into another project and stage more files:
cd ../another-project
git add ./another-file.txt

The following can be used:

cd Projects/my-workspace

git ws add ./some-project/some-file.txt ./another-project/another-file.txt

Use git ws status to display all changes using paths suitable for use with this command.

`git ws rm`

Run git rm on specified files within the workspace.

Usage: git-ws rm [OPTIONS] [PATHS]...

  Run 'git rm' on PATHS and choose the right git clone automatically.

Options:
  -f, --force                Enforce operation.
  --cached                   only remove from index
  -r                         allow recursive removal
  -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 can be used to conveniently run a git rm on file spread across several git clones within a workspace. So instead of the following:

cd Projects/my-workspace/some-project
git rm ./some-file.txt

cd ../another-project
git rm ./another-file.txt

You can use this:

cd Projects/my-workspace
git ws rm ./some-project/some-file.txt ./another-project/another-file.txt

`git ws reset`

Run a git reset on the given paths.

Usage: git-ws reset [OPTIONS] [PATHS]...

  Run 'git reset' on PATHS and choose the right git clone automatically.

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.

Similarly to the git ws add command, this allows conveniently running a git reset on files spread across repositories in a workspace. So instead of this:

cd Projects/my-workspace

# Change into one project first:
cd some-project
git reset ./some-file.txt

# Change into another project and stage more files:
cd ../another-project
git reset ./another-file.txt

This can be used:

cd Projects/my-workspace

git ws reset ./some-project/some-file.txt ./another-project/another-file.txt

Use git ws status to display all changes using paths suitable for use with this command.

`git ws commit`

Runs a git commit in the projects within a workspace.

Usage: git-ws commit [OPTIONS] [PATHS]...

  Run 'git commit' on PATHS and choose the right git clone automatically.

Options:
  -m, --message TEXT         commit message
  -a, --all                  commit all changed files
  -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 can be used in two ways (similar to the use of git commit itself). In the first form, when no file paths are specified, the command runs a commit in all repositories which have staged changes:

git ws commit -m "A commit in all repos with staged changes"

For staging, use either git add or git ws add.

In the second form, a git commit will be run in the repositories where the given files are stored:

cd Projects/my-workspace

git ws commit \
    ./some-project/some-file.txt ./another-project/another-file.txt \
    -m "A commit in two projects"

In this form, only the files given on the command line will be included in the commits.

`git ws submodule`

Run a git submodule in all clones within a workspace.

Usage: git-ws submodule [OPTIONS] [COMMAND]...

  Run git submodule COMMAND on projects.

  This command is identical to `git ws foreach -- git submodule COMMAND`.

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.
  -R, --reverse              Operate in Reverse Order. Start with last
                             dependency instead of main repository.
  -b, --on-branch            Limit operation to clones on branches only.
                             Detached HEAD clones (on tag or SHA) are ignored.
  -h, --help                 Show this message and exit.

This command can be used to conveniently work with git submodules that are included by some of the projects within a workspace. For example, to initialize and checkout submodules in all of the projects in a workspace, the following can be used:

git ws submodule -- update --init --recursive

`git ws tag`

Create a tag in the main project including a connected, frozen manifest.

Usage: git-ws tag [OPTIONS] NAME

  Create git tag NAME on main repository.

  This includes freezing all dependencies.

Options:
  -m, --message TEXT         tag message
  -f, --force                replace the tag if exists
  -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 can be used to create a (named) tag in the workspace by:

Creating a frozen manifest of the project’s current state in the main project.
Committing that manifest.
And finally creating a git tag in the main repository.

The details of the tagging process are described in Tagging.

Note

This command solely applies changes in the main project. This is enough to be able to reproduce a given state of the project later on. In particular, this command will not create tags on any of the other projects. If this is what you intent, you can use something like that instead:

git ws git tag -m "Releasing v1.2.3.4" v1.2.3.4

Working With git Clones

git ws foreach

git ws git

git ws pull

git ws push

git ws rebase

git ws fetch

git ws diff

git ws checkout

git ws status

git ws add

git ws rm

git ws reset

git ws commit

git ws submodule

git ws tag