| Name | gitsum JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | |
| Summary | Summarize the status of multiple Git repositories. |
| upload_time | 2023-02-05 23:26:13 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2022 Louis Hildebrand Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
git
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# gitsum
[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)
[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)
[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)
[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)
`gitsum` is a command-line tool that provides a summary of multiple Git repositories.
## Installation
Ensure you have Python 3.8+ and pip installed. Then run
```sh
pip install gitsum
```
## Basic Usage
Move to a directory in which there are Git repositories and then run `gitsum`.
This will print out an overview of the status of each repository within the current directory (or its subdirectories). For example:
```
Found 7 Git repositories.
! deleted master * local repo
! modified (d02092) * local repo
remote/empty (no commits) local branch
! remote/not empty/ahead behind main >1 <3
! remote/not empty/staged feature *
! unmerged main * local repo
! untracked (no commits) * local repo
```
The standard output includes:
- The flag `!` if there are local changes or if the current branch is ahead of or behind its upstream branch
- The directory path (relative to the current working directory)
- The current branch (or the current commit hash if the repo is in detached HEAD mode)
- The flag `*` if there are local changes (e.g., untracked files, modified files, deleted files)
- The remote status, which can be:
- `local repo` if the repository has no remotes
- `local branch` if the repository has at least one remote but the current branch has no upstream
- The number of commits ahead and behind the upstream branch (e.g., `>1 <3` say that the given repo is 1 commit ahead and 3 commits behind)
## General Usage
### Getting Help
Run
```sh
gitsum --help
```
### Listing Files Outside Git Repos
In some cases you might want to know if there are files or directories which are not in a Git repository (e.g., to know if you forgot to make a Git repo for any of your local projects).
To see a list of files and directories that are not inside a Git repository (in addition to the normal output), run
```sh
gitsum --outside-files
```
To see _only_ these outside files (without the normal output), run
```sh
gitsum --only-outside-files
```
### Fetching Beforehand
To fetch from each remote repository before displaying the repository statuses, run
```sh
gitsum --fetch
```
Note that this option is currently limited to public repositories. If `gitsum` is unable to fetch (e.g., because the repository is private), then a warning will simply be displayed.
## Running the Tests
Before running the tests, clone the repository and install the test dependencies using `pip install -r test-requirements.txt`. You must also build the project with `python -m build` and then install the package with `pip install --find-links=dist gitsum`.
The tests can be run by issuing the command `pytest` (or `python -m unittest`, if you prefer). This must be done from the root of the repository.
`gitsum` is verified by a few integration tests which create Git repos and check that the command's output is as expected. To avoid the `gitsum` repo itself interfering with the output, the repo is temporarily disabled by renaming the `.git/` folder to `.git.bak/`. This might not be possible if your IDE is using the `.git/` folder. If you get errors, you might need to disable your IDE's Git integration for this project. For example, in VS Code, you can add a file `.vscode/settings.json` in the root of the repo with the following contents:
```json
{
"git.enabled": false
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "gitsum",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "git",
"author": "",
"author_email": "Louis Hildebrand <louis.hildebrand@mail.mcgill.ca>",
"download_url": "https://files.pythonhosted.org/packages/c8/16/b5c1c094276582c099138bb26c94ce9a0d8a0031eaa166dd98442832015d/gitsum-1.1.0.tar.gz",
"platform": null,
"description": "# gitsum\r\n[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)\r\n[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)\r\n[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)\r\n[](https://github.com/louis-hildebrand/gitsum/actions/workflows/main-push.yml)\r\n\r\n`gitsum` is a command-line tool that provides a summary of multiple Git repositories.\r\n\r\n## Installation\r\nEnsure you have Python 3.8+ and pip installed. Then run\r\n```sh\r\npip install gitsum\r\n```\r\n\r\n## Basic Usage\r\nMove to a directory in which there are Git repositories and then run `gitsum`.\r\n\r\nThis will print out an overview of the status of each repository within the current directory (or its subdirectories). For example:\r\n```\r\nFound 7 Git repositories.\r\n! deleted master * local repo\r\n! modified (d02092) * local repo\r\n remote/empty (no commits) local branch\r\n! remote/not empty/ahead behind main >1 <3\r\n! remote/not empty/staged feature *\r\n! unmerged main * local repo\r\n! untracked (no commits) * local repo\r\n```\r\n\r\nThe standard output includes:\r\n- The flag `!` if there are local changes or if the current branch is ahead of or behind its upstream branch\r\n- The directory path (relative to the current working directory)\r\n- The current branch (or the current commit hash if the repo is in detached HEAD mode)\r\n- The flag `*` if there are local changes (e.g., untracked files, modified files, deleted files)\r\n- The remote status, which can be:\r\n - `local repo` if the repository has no remotes\r\n - `local branch` if the repository has at least one remote but the current branch has no upstream\r\n - The number of commits ahead and behind the upstream branch (e.g., `>1 <3` say that the given repo is 1 commit ahead and 3 commits behind)\r\n\r\n## General Usage\r\n### Getting Help\r\nRun\r\n```sh\r\ngitsum --help\r\n```\r\n\r\n### Listing Files Outside Git Repos\r\nIn some cases you might want to know if there are files or directories which are not in a Git repository (e.g., to know if you forgot to make a Git repo for any of your local projects).\r\n\r\nTo see a list of files and directories that are not inside a Git repository (in addition to the normal output), run\r\n```sh\r\ngitsum --outside-files\r\n```\r\n\r\nTo see _only_ these outside files (without the normal output), run\r\n```sh\r\ngitsum --only-outside-files\r\n```\r\n\r\n### Fetching Beforehand\r\nTo fetch from each remote repository before displaying the repository statuses, run\r\n```sh\r\ngitsum --fetch\r\n```\r\n\r\nNote that this option is currently limited to public repositories. If `gitsum` is unable to fetch (e.g., because the repository is private), then a warning will simply be displayed. \r\n\r\n## Running the Tests\r\nBefore running the tests, clone the repository and install the test dependencies using `pip install -r test-requirements.txt`. You must also build the project with `python -m build` and then install the package with `pip install --find-links=dist gitsum`.\r\n\r\nThe tests can be run by issuing the command `pytest` (or `python -m unittest`, if you prefer). This must be done from the root of the repository.\r\n\r\n`gitsum` is verified by a few integration tests which create Git repos and check that the command's output is as expected. To avoid the `gitsum` repo itself interfering with the output, the repo is temporarily disabled by renaming the `.git/` folder to `.git.bak/`. This might not be possible if your IDE is using the `.git/` folder. If you get errors, you might need to disable your IDE's Git integration for this project. For example, in VS Code, you can add a file `.vscode/settings.json` in the root of the repo with the following contents:\r\n```json\r\n{\r\n \"git.enabled\": false\r\n}\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Louis Hildebrand Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Summarize the status of multiple Git repositories.",
"version": "1.1.0",
"split_keywords": [
"git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5756ff962e44993dfc9112f29a43f0bdb12408911a485fa6c7e7443a008c7002",
"md5": "d1c149dbd56dbf6194007ebd4dd59983",
"sha256": "40d73a6ef74860a575f122dcf4772d43e84b53647d2311915d09021142d59d5e"
},
"downloads": -1,
"filename": "gitsum-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d1c149dbd56dbf6194007ebd4dd59983",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8096,
"upload_time": "2023-02-05T23:26:12",
"upload_time_iso_8601": "2023-02-05T23:26:12.178654Z",
"url": "https://files.pythonhosted.org/packages/57/56/ff962e44993dfc9112f29a43f0bdb12408911a485fa6c7e7443a008c7002/gitsum-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c816b5c1c094276582c099138bb26c94ce9a0d8a0031eaa166dd98442832015d",
"md5": "c1319557a079f9277a2daf026cc5f739",
"sha256": "797ae064a7e9cb6619ac100f415b4d79beca18b417fa6f7cdec29122358776fe"
},
"downloads": -1,
"filename": "gitsum-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c1319557a079f9277a2daf026cc5f739",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9937,
"upload_time": "2023-02-05T23:26:13",
"upload_time_iso_8601": "2023-02-05T23:26:13.960056Z",
"url": "https://files.pythonhosted.org/packages/c8/16/b5c1c094276582c099138bb26c94ce9a0d8a0031eaa166dd98442832015d/gitsum-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 23:26:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "gitsum"
}
