| Name | multigit JSON |
| Version |
0.11.8
JSON |
| download |
| home_page | None |
| Summary | Manages git repos within git repos. |
| upload_time | 2024-05-25 13:47:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | GPL-3.0 |
| keywords |
python
git-utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python Multigit<a name="top"></a>
A Python version of the [multigit Bash script](https://github.com/jmnavarrol/simplest-git-subrepos).
While the multigit Bash script at [simplest-git-subrepos](https://github.com/jmnavarrol/simplest-git-subrepos) was created for illustration purposes, this one is intended to be a full-fledged implementation.
The general idea is to offer a simple way of managing *"workspaces"* integrating multiple git repos starting from a top one, and without the need of difficult *"arcanes"* like *git submodules*, *git-subtree*, etc.: you only need to declare your intended *layout* in a YAML file, and let this script (**multigit**) do its job. See the [simplest-git-subrepos README](https://github.com/jmnavarrol/simplest-git-subrepos#readme) for a long-wired explanation.
**Contents:**<a name="contents"></a>
1. [usage](#usage)
1. [subrepos' file format](#subrepos-format)
1. [development](#development)
1. [code documentation](#sphinx)
1. [build](#build)
1. [publish](#publish)
1. [CHANGELOG](./CHANGELOG.md)
1. [license](#license)
----
## usage<a name="usage"></a>
This project [is published to the PyPI index](https://pypi.org/project/multigit/) so, in order to install it you just need to run `pip install multigit`.
*multigit* expects a YAML file named **subrepos** in the current dir (see [example](./example/subrepos)). Optionally, if there's no *subrepos* file in the current dir **and** the current directory is within a git sandbox, *multigit* will try to find a *subrepos* file at the git sandbox's root.
For each defined *subrepo* within the *subrepos* file, it will clone/checkout it to the defined relative path. Optionally, it will *checkout* the given *gitref* (either *commit*, *branch* or *tag*), provided the repo's local sandbox is *"clean"* (i.e. no pending modifications).
**NOTE:** pay attention to the fact that if the *gitref* you record is a specific *commit* or *tag*, the related sandbox will be in disconnected state.
*multigit* will also recursively look for new *subrepos* files on the root directory of the repositories it manages.
When working within a git repository, **you should make sure** your [*.gitignore* file](./.gitignore) ignores all your *subrepos*.
This way you just need to manage your repos with `git` in the standard way, just as if they were individually checked out in isolation.
Run `multigit` with no options or `multigit --help` for usage.
<sub>[back to top](#top).</sub>
### subrepos' file format<a name="subrepos-format"></a>
The *'subrepos'* file holds a yaml dictionary describing the desired lay-out.
It starts with a **subrepos** key with a list of entries underneath, each of them describing a repository entry point (see ['subrepos' example](./example/subrepos) for further details). Some detailed explanations follow:
* **general description:**
```yml
---
# High-level structure
subrepos: # main key
- [first entry] # first repository description
- [second entry] # second repository description
- [third entry] # third repository description
- [...] # (more repositories)
```
* **each repository entry:** Each repository definition requires two mandatory keys and an optional one:
* **repository:** (mandatory) the [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier "Uniform Resource Identifier") to operate the remote repository.
Its format is just the one you'd use to `git clone` the repository with same effect, i.e. if you need to pass a username/password for an https site, or a password to decrypt you ssh key, etc. here you'll be requested to do it too.
* **path:** (mandatory) the path the repository sandbox will the deployed to, relative to the subrepos file itself.
* **[commit|branch|tag]:** (optional) the *gitref* you want your sandbox to be *pinned* to.
* You can provide **one** of either *'commit'*, *'branch'* or *'tag'*.
* Note that if you provide either a *commit* or a *tag* the resulting sandbox will be in a [*detached head state*](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefdetachedHEADadetachedHEAD).
* If you don't provide this key, your sandbox will track the remote's default branch.
**A full (conceptual) example:**
```yml
---
# Don't forget including your subrepos' roots to .gitignore!
subrepos:
- repo: 'git@github.com:jmnavarrol/python-multigit.git' # the remote using git+ssh protocol. It may request your ssh key's password
path: 'a-subdir' # it will be cloned to 'subdir/' relative to 'subrepos' file
# no gitref, so this will track the remote's default branch
- repo: 'https://github.com/jmnavarrol/python-multigit.git' # the remote using https protocol. It may request user/password
path: 'a-subdir/another-subdir' # it will be cloned to 'a-subdir/subdir/' relative to 'subrepos' file
branch: 'a-branch' # the sandbox will track the 'a-branch' branch.
```
**NOTE:** Since repositories are listed in an array, order matters: first repository is processed before the second one and so on. This means that you can declare first a repository to be deployed to a subdirectory and then another repository to be deployed to a subdirectory of that first subdirectory and things will behave as expected.
It's usually better that you declare the *"deeper"* subdirectory within its own 'subrepos' file in the intermediate repository, though.
<sub>[back to top](#top).</sub>
## development<a name="development"></a>
This project uses the help of [Bash Magic Enviro](https://github.com/jmnavarrol/bash-magic-enviro) to configure its development environment.
It creates a Python 3 *virtualenv* using [the companion requirements file](./python-virtualenvs/multigit-development.requirements).
Once the *virtualenv* is (automatically) activated, you can run this code just invoking its main script, i.e.: `multigit`.
<sub>[back to top](#top).</sub>
### code documentation<a name="sphinx"></a>
Code documentation is produced with the help of [Sphinx](https://www.sphinx-doc.org), with configurations at [src/sphinx/](./src/sphinx/). While sphinx includes [its own Makefile](./src/sphinx/Makefile), HTML doc can be generated from [the Makefile at src/](./src/Makefile), starting at the local `src/build/html/index.html` file.
You can browse it on-line at https://jmnavarrol.github.io/python-multigit.
<sub>[back to top](#top).</sub>
### build<a name="build"></a>
The [included Makefile](./src/Makefile) will use Python's [Hatch](https://hatch.pypa.io) to build both *source* and *binary-based* Python *eggs*. Provided everything went OK, look for packages under the *dist/* directory.
Run `make` to see available *make targets*.
<sub>[back to top](#top).</sub>
### publish<a name="publish"></a>
Provided *Makefile* includes publication targets to both testing and live PyPi services by means of *twine*. Make sure your ~/.pypi.rc file includes proper entries named *[testpypi]* and *[pypi]* respectively. Remember, also, that you can't publish the same version twice to these services, so make sure you udpate the package's version before attempting an upload.
<sub>[back to top](#top).</sub>
------
## License<a name="license"></a>
Python Multigit is made available under the terms of the **GPLv3**.
See the [license file](./LICENSE) that accompanies this distribution for the full text of the license.
<sub>[back to top](#top).</sub>
Raw data
{
"_id": null,
"home_page": null,
"name": "multigit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Python, git-utilities",
"author": null,
"author_email": "\"Jes\u00fas M. Navarro\" <jesusmnavarrolopez@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dc/0d/9076a1e60f400035749c3720e99fcff4e4cf85d2f51628d4fe41b66aef5d/multigit-0.11.8.tar.gz",
"platform": null,
"description": "# Python Multigit<a name=\"top\"></a>\n\nA Python version of the [multigit Bash script](https://github.com/jmnavarrol/simplest-git-subrepos).\n\nWhile the multigit Bash script at [simplest-git-subrepos](https://github.com/jmnavarrol/simplest-git-subrepos) was created for illustration purposes, this one is intended to be a full-fledged implementation.\n\nThe general idea is to offer a simple way of managing *\"workspaces\"* integrating multiple git repos starting from a top one, and without the need of difficult *\"arcanes\"* like *git submodules*, *git-subtree*, etc.: you only need to declare your intended *layout* in a YAML file, and let this script (**multigit**) do its job. See the [simplest-git-subrepos README](https://github.com/jmnavarrol/simplest-git-subrepos#readme) for a long-wired explanation.\n\n**Contents:**<a name=\"contents\"></a>\n1. [usage](#usage)\n 1. [subrepos' file format](#subrepos-format)\n1. [development](#development)\n 1. [code documentation](#sphinx)\n 1. [build](#build)\n 1. [publish](#publish)\n 1. [CHANGELOG](./CHANGELOG.md)\n1. [license](#license)\n\n----\n\n## usage<a name=\"usage\"></a>\nThis project [is published to the PyPI index](https://pypi.org/project/multigit/) so, in order to install it you just need to run `pip install multigit`.\n\n*multigit* expects a YAML file named **subrepos** in the current dir (see [example](./example/subrepos)). Optionally, if there's no *subrepos* file in the current dir **and** the current directory is within a git sandbox, *multigit* will try to find a *subrepos* file at the git sandbox's root.\n\nFor each defined *subrepo* within the *subrepos* file, it will clone/checkout it to the defined relative path. Optionally, it will *checkout* the given *gitref* (either *commit*, *branch* or *tag*), provided the repo's local sandbox is *\"clean\"* (i.e. no pending modifications). \n **NOTE:** pay attention to the fact that if the *gitref* you record is a specific *commit* or *tag*, the related sandbox will be in disconnected state.\n\n*multigit* will also recursively look for new *subrepos* files on the root directory of the repositories it manages.\n\nWhen working within a git repository, **you should make sure** your [*.gitignore* file](./.gitignore) ignores all your *subrepos*.\n\nThis way you just need to manage your repos with `git` in the standard way, just as if they were individually checked out in isolation.\n\nRun `multigit` with no options or `multigit --help` for usage.\n\n<sub>[back to top](#top).</sub>\n\n### subrepos' file format<a name=\"subrepos-format\"></a>\nThe *'subrepos'* file holds a yaml dictionary describing the desired lay-out.\n\nIt starts with a **subrepos** key with a list of entries underneath, each of them describing a repository entry point (see ['subrepos' example](./example/subrepos) for further details). Some detailed explanations follow:\n* **general description:**\n ```yml\n ---\n # High-level structure\n subrepos: # main key\n - [first entry] # first repository description\n - [second entry] # second repository description\n - [third entry] # third repository description\n - [...] # (more repositories)\n ```\n* **each repository entry:** Each repository definition requires two mandatory keys and an optional one:\n * **repository:** (mandatory) the [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier \"Uniform Resource Identifier\") to operate the remote repository. \n Its format is just the one you'd use to `git clone` the repository with same effect, i.e. if you need to pass a username/password for an https site, or a password to decrypt you ssh key, etc. here you'll be requested to do it too.\n * **path:** (mandatory) the path the repository sandbox will the deployed to, relative to the subrepos file itself.\n * **[commit|branch|tag]:** (optional) the *gitref* you want your sandbox to be *pinned* to. \n * You can provide **one** of either *'commit'*, *'branch'* or *'tag'*.\n * Note that if you provide either a *commit* or a *tag* the resulting sandbox will be in a [*detached head state*](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefdetachedHEADadetachedHEAD).\n * If you don't provide this key, your sandbox will track the remote's default branch.\n \n**A full (conceptual) example:**\n```yml\n---\n# Don't forget including your subrepos' roots to .gitignore!\nsubrepos:\n- repo: 'git@github.com:jmnavarrol/python-multigit.git' # the remote using git+ssh protocol. It may request your ssh key's password\n path: 'a-subdir' # it will be cloned to 'subdir/' relative to 'subrepos' file\n # no gitref, so this will track the remote's default branch\n- repo: 'https://github.com/jmnavarrol/python-multigit.git' # the remote using https protocol. It may request user/password\n path: 'a-subdir/another-subdir' # it will be cloned to 'a-subdir/subdir/' relative to 'subrepos' file\n branch: 'a-branch' # the sandbox will track the 'a-branch' branch.\n```\n\n**NOTE:** Since repositories are listed in an array, order matters: first repository is processed before the second one and so on. This means that you can declare first a repository to be deployed to a subdirectory and then another repository to be deployed to a subdirectory of that first subdirectory and things will behave as expected. \nIt's usually better that you declare the *\"deeper\"* subdirectory within its own 'subrepos' file in the intermediate repository, though.\n\n<sub>[back to top](#top).</sub>\n\n## development<a name=\"development\"></a>\nThis project uses the help of [Bash Magic Enviro](https://github.com/jmnavarrol/bash-magic-enviro) to configure its development environment.\n\nIt creates a Python 3 *virtualenv* using [the companion requirements file](./python-virtualenvs/multigit-development.requirements).\n\nOnce the *virtualenv* is (automatically) activated, you can run this code just invoking its main script, i.e.: `multigit`.\n\n<sub>[back to top](#top).</sub>\n\n### code documentation<a name=\"sphinx\"></a>\nCode documentation is produced with the help of [Sphinx](https://www.sphinx-doc.org), with configurations at [src/sphinx/](./src/sphinx/). While sphinx includes [its own Makefile](./src/sphinx/Makefile), HTML doc can be generated from [the Makefile at src/](./src/Makefile), starting at the local `src/build/html/index.html` file.\n\nYou can browse it on-line at https://jmnavarrol.github.io/python-multigit.\n\n<sub>[back to top](#top).</sub>\n\n### build<a name=\"build\"></a>\nThe [included Makefile](./src/Makefile) will use Python's [Hatch](https://hatch.pypa.io) to build both *source* and *binary-based* Python *eggs*. Provided everything went OK, look for packages under the *dist/* directory.\n\nRun `make` to see available *make targets*.\n\n<sub>[back to top](#top).</sub>\n\n### publish<a name=\"publish\"></a>\nProvided *Makefile* includes publication targets to both testing and live PyPi services by means of *twine*. Make sure your ~/.pypi.rc file includes proper entries named *[testpypi]* and *[pypi]* respectively. Remember, also, that you can't publish the same version twice to these services, so make sure you udpate the package's version before attempting an upload.\n\n<sub>[back to top](#top).</sub>\n\n------\n\n## License<a name=\"license\"></a>\nPython Multigit is made available under the terms of the **GPLv3**.\n\nSee the [license file](./LICENSE) that accompanies this distribution for the full text of the license.\n\n<sub>[back to top](#top).</sub>\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Manages git repos within git repos.",
"version": "0.11.8",
"project_urls": {
"Bug Tracker": "https://github.com/jmnavarrol/python-multigit/issues",
"Documentation": "https://jmnavarrol.github.io/python-multigit/",
"Source": "https://github.com/jmnavarrol/python-multigit"
},
"split_keywords": [
"python",
" git-utilities"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "afa9c8ede99eacff3af35be3bb5149145e0549c07941ca0c27a360c8f212fa54",
"md5": "307574fea890ee6341a93db99f336e59",
"sha256": "c3c33377ae8b549192ca67839e37a4bbc4290fbbc128bce81f9aa33ebb1d3000"
},
"downloads": -1,
"filename": "multigit-0.11.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "307574fea890ee6341a93db99f336e59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24912,
"upload_time": "2024-05-25T13:47:44",
"upload_time_iso_8601": "2024-05-25T13:47:44.575623Z",
"url": "https://files.pythonhosted.org/packages/af/a9/c8ede99eacff3af35be3bb5149145e0549c07941ca0c27a360c8f212fa54/multigit-0.11.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc0d9076a1e60f400035749c3720e99fcff4e4cf85d2f51628d4fe41b66aef5d",
"md5": "ddc34b0d1edf552b984d1e312ee2a6b2",
"sha256": "50a97c0c89f85e7836b6c195a4c10f8486a7e180570d3ee27e18d98b0f67f41b"
},
"downloads": -1,
"filename": "multigit-0.11.8.tar.gz",
"has_sig": false,
"md5_digest": "ddc34b0d1edf552b984d1e312ee2a6b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22326,
"upload_time": "2024-05-25T13:47:46",
"upload_time_iso_8601": "2024-05-25T13:47:46.668860Z",
"url": "https://files.pythonhosted.org/packages/dc/0d/9076a1e60f400035749c3720e99fcff4e4cf85d2f51628d4fe41b66aef5d/multigit-0.11.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-25 13:47:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jmnavarrol",
"github_project": "python-multigit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "multigit"
}
