# Git Workspace
This script is intended to ease the development in multirepo environment. By defining a workspace file
that contains all the repositories one can easily share the environment setup without the need for manual
git clones. With git configuration user and host can also be set for the repositories. This allows one
to use e.g. multiple bitbucket repositories with different SSH keys easily without altering the host in
each git clone command.
This script also provides a command to check the overall state of the workspace (branches, untracked files etc.).
Few commands are overridden, but most are plain passthroughs to git and are run in all of the workspace
repositories.
### Installation:
```shell
pip install --user git-workspace
```
or
```shell
pip3 install git-workspace
```
### Usage
At first, create a new directory where the workspace will be initialized. There, run `git ws init` which creates a blank configuration. Fill in at least the remote configuration (examples later in this README).
For the repositories, fill those either by hand or if using Gitlab, you can use `git ws gitlab-sync` to automatically create a repository list either for a single group (and its subgroups) or for all that you have access to. `gitlab-sync` requires you to create a personal access token with Gitlab REST API access rights and supports only v4 API. The token can be saved to the systems secret storage (for details see Keyring python package documentation, but at least KWallet in KDE and Keychain in MacOS are supported). If stored, then the API TOKEN does not need to be filled in later on.
> NOTICE: Right now, only a single token can be used. Support for multiple different tokens coming soon-ish.
#### Command helps
```
Usage: git-ws [OPTIONS] COMMAND [ARGS]...
Git Workspace
Copyright 2021 Aki Mäkinen
https://gitlab.com/blissfulreboot/python/git-workspace
Licensed under MIT license
Options:
--help Show this message and exit.
Commands:
autocomplete Show the autocomplete line
cleanup Move repositories not included in the workspace...
clone Clone the repositories listed in the workspace...
command Run a command in each workspace git directory
default-and-update Stash potential changes, switch to the default...
gitlab
gitlab-sync Sync the workspace to match the state of the gitlab...
init Initialize a new blank workspace
state Print the state of the repositories in the workspace
```
```
Usage: git-ws gitlab [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
sync Sync the workspace to match the state of the gitlab group
```
#### Configuration
In contrast to the first version of this tool, the configuration resides now in a single YAML file. The format is:
```yaml
repositories: []
remote:
gituser: ''
githost: ''
api_url: ''
insecure: false
gitlab-integration:
fetch-archived: <boolean, by default the sync no longer fetches archived repositories>
suppress-insecure-warning: <boolean, suppresses the urllib3 insecure warnings if set to true>
```
where the repository entries are
```yaml
- path: some/repository/path.git
directory: some/repository/path
default_branch: main
```
If the directory is defined for the repository entry, then the repository will be cloned there, otherwise the structure will be flattened. The default branch is used for the `git ws state` currently and defaults to `main` if not defined.
Example:
```yaml
# The remote configuration for gitlab.com using ssh (which is the only officially supported right now)
repositories: []
remote:
gituser: git
githost: gitlab.com
api_url: https://gitlab.com/api/v4/
insecure: false
```
### New features in 2.3.1
* Retry git clone
* `git ws clone` now has retries for each git clone operation as well as a retry interval. These are hard coded for now, but will be configurable in the future
* Defaults are:
* retry count: 5
* retry interval: 5 seconds
* Support for multiple gitlab personal access tokens
* API URL is used as an identifier.
* EXPERIMENTAL: Support custom certificates
* new field in the configuration under `remote`: `custom_certificate`. This is the absolute path to the file used for verification.
* The `custom_certificate` field overrides the `insecure` field
* EXPERIMENTAL: autocompletion for `git-ws` command
* Does not work with `git ws`. See help (`git-ws` or `git ws`) for details.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/blissfulreboot/python/git-workspace",
"name": "git-workspace",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Git,Workspace",
"author": "Aki M\u00e4kinen",
"author_email": "nenshou.sora@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f6/1f/7c770dc08057aacc79475a4151d38543e92d4a9d8570e4d52b528ae4b298/git-workspace-2.6.2.tar.gz",
"platform": null,
"description": "# Git Workspace\n\nThis script is intended to ease the development in multirepo environment. By defining a workspace file\nthat contains all the repositories one can easily share the environment setup without the need for manual\ngit clones. With git configuration user and host can also be set for the repositories. This allows one\nto use e.g. multiple bitbucket repositories with different SSH keys easily without altering the host in\neach git clone command.\n\nThis script also provides a command to check the overall state of the workspace (branches, untracked files etc.).\nFew commands are overridden, but most are plain passthroughs to git and are run in all of the workspace\nrepositories.\n\n### Installation:\n\n```shell\npip install --user git-workspace\n```\nor\n```shell\npip3 install git-workspace\n```\n\n### Usage\n\nAt first, create a new directory where the workspace will be initialized. There, run `git ws init` which creates a blank configuration. Fill in at least the remote configuration (examples later in this README).\n\nFor the repositories, fill those either by hand or if using Gitlab, you can use `git ws gitlab-sync` to automatically create a repository list either for a single group (and its subgroups) or for all that you have access to. `gitlab-sync` requires you to create a personal access token with Gitlab REST API access rights and supports only v4 API. The token can be saved to the systems secret storage (for details see Keyring python package documentation, but at least KWallet in KDE and Keychain in MacOS are supported). If stored, then the API TOKEN does not need to be filled in later on.\n\n> NOTICE: Right now, only a single token can be used. Support for multiple different tokens coming soon-ish.\n\n#### Command helps\n```\nUsage: git-ws [OPTIONS] COMMAND [ARGS]...\n\n Git Workspace\n\n Copyright 2021 Aki M\u00e4kinen\n https://gitlab.com/blissfulreboot/python/git-workspace\n Licensed under MIT license\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n autocomplete Show the autocomplete line\n cleanup Move repositories not included in the workspace...\n clone Clone the repositories listed in the workspace...\n command Run a command in each workspace git directory\n default-and-update Stash potential changes, switch to the default...\n gitlab\n gitlab-sync Sync the workspace to match the state of the gitlab...\n init Initialize a new blank workspace\n state Print the state of the repositories in the workspace\n\n```\n```\nUsage: git-ws gitlab [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n sync Sync the workspace to match the state of the gitlab group\n```\n\n#### Configuration\n\nIn contrast to the first version of this tool, the configuration resides now in a single YAML file. The format is:\n\n```yaml\nrepositories: []\nremote:\n gituser: ''\n githost: ''\n api_url: ''\n insecure: false\ngitlab-integration:\n fetch-archived: <boolean, by default the sync no longer fetches archived repositories>\n suppress-insecure-warning: <boolean, suppresses the urllib3 insecure warnings if set to true>\n```\n\nwhere the repository entries are\n\n```yaml\n- path: some/repository/path.git \n directory: some/repository/path\n default_branch: main\n```\n\nIf the directory is defined for the repository entry, then the repository will be cloned there, otherwise the structure will be flattened. The default branch is used for the `git ws state` currently and defaults to `main` if not defined.\n\nExample:\n\n```yaml\n# The remote configuration for gitlab.com using ssh (which is the only officially supported right now)\nrepositories: []\nremote:\n gituser: git\n githost: gitlab.com\n api_url: https://gitlab.com/api/v4/\n insecure: false\n```\n\n### New features in 2.3.1\n* Retry git clone\n * `git ws clone` now has retries for each git clone operation as well as a retry interval. These are hard coded for now, but will be configurable in the future\n * Defaults are:\n * retry count: 5\n * retry interval: 5 seconds\n* Support for multiple gitlab personal access tokens\n * API URL is used as an identifier.\n* EXPERIMENTAL: Support custom certificates\n * new field in the configuration under `remote`: `custom_certificate`. This is the absolute path to the file used for verification.\n * The `custom_certificate` field overrides the `insecure` field\n* EXPERIMENTAL: autocompletion for `git-ws` command\n * Does not work with `git ws`. See help (`git-ws` or `git ws`) for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Git 'extension' for managing multirepo workspaces",
"version": "2.6.2",
"split_keywords": [
"git",
"workspace"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d43a13fc2fa3680713f585bd1b3f69bd",
"sha256": "370a58c23272fd57f54716125c745221dd7d0af092948a73d3867ae353e8644e"
},
"downloads": -1,
"filename": "git-workspace-2.6.2.tar.gz",
"has_sig": false,
"md5_digest": "d43a13fc2fa3680713f585bd1b3f69bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16198,
"upload_time": "2022-12-09T09:24:13",
"upload_time_iso_8601": "2022-12-09T09:24:13.591236Z",
"url": "https://files.pythonhosted.org/packages/f6/1f/7c770dc08057aacc79475a4151d38543e92d4a9d8570e4d52b528ae4b298/git-workspace-2.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-09 09:24:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "git-workspace"
}
JSON