| Name | gitbolt JSON |
| Version |
0.0.0.dev7
JSON |
| download |
| home_page | None |
| Summary | Fast, flexible and type-safe Git commands in Python. |
| upload_time | 2025-07-12 15:41:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
git
vcs
library
version control
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🚀 Gitbolt
[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/test.yml)
[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/typecheck.yml)
[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/lint.yml)
[](https://codecov.io/gh/Vaastav-Technologies/py-gitbolt)
[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/python-publish.yml)
**Fast, flexible and type-safe Git command execution in Python using subprocess.**
---
## ✨ Features
* 🧠 **Typed:** All commands and options are statically type-checked.
* ⚡ **Fast:** Minimal abstractions over subprocess, runs directly on your system Git.
* 🧩 **Composable:** Git commands and options can be passed around as objects.
* 🔁 **Overridable:** Easily override environment variables and options in a chainable, readable manner.
* 📦 **Lightweight:** No dependencies on heavy Git libraries or C extensions.
* 🧰 **Extensible:** Future support for output transformers and other plugins.
* 🚨 **Exception Handling:** Raises any error as a Python-recognisable exception.
* 📤 **Debuggable:** Exceptions capture `stdout`, `stderr`, and the return code of the run command.
* 💤 **Lazy Execution:** Inherently lazily processed.
* 📄 **Transparent Output:** Returns a Git command's `stdout` as-is.
* 🧪 **Terminal Functions:** Git subcommands are terminal functions.
* 🧼 **Idiomatic Python:** Write commands in idiomatic Python at compile-time and be confident they’ll execute smoothly at runtime.
---
## 📦 Installation
```bash
pip install gitbolt
```
---
## 💡 Motivation
Running system commands in Python can be tricky for the following reasons:
1. Arguments sent to `subprocess` may not be typed correctly and result in runtime errors.
2. Argument groups may be mutually exclusive or required conditionally — again causing runtime issues.
3. Errors from subprocess are often unhelpful and difficult to debug.
Also, using subprocess effectively means you must:
* Understand and manage process setup, piping, and teardown.
* Know your CLI command intricacies in depth.
> This project exists to fix all that — with ergonomics, speed, and type-safety.
---
## 🎯 Project Goals
### ✅ Predictable Compile-Time Behavior
Type-checking ensures runtime safety.
### ✅ Ergonomic APIs
<details>
<summary>Make git command interfaces as ergonomic to the user as possible.</summary>
#### Provide versions of most used command combinations
`git hash-object` supports taking multiple files and outputs a hash per file. But in practice, it's most often used to write a single file to the Git object database and return its hash. To match this real-world usage, Gitbolt offers a more ergonomic method that accepts one file and returns one hash — while still giving you the flexibility to access the full range of `git hash-object` capabilities when needed.
#### Let subcommands be passed around as objects
Gitbolt lets you pass subcommands around as typed objects. This enables highly focused, minimal APIs — you can write functions that accept only the subcommands they truly need. This leads to cleaner logic, better separation of concerns, and compile-time guarantees that help prevent misuse.
```python
import gitbolt
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
version_subcmd = git.version_subcmd
add_subcmd = git.add_subcmd
def method_which_only_adds_a_file(add_subcmd: gitbolt.base.Add):
"""
This method only requires the `add` subcommand.
"""
...
method_which_only_adds_a_file(add_subcmd)
```
</details>
### ✅ Subcommands as Objects
git subcommands are modeled as terminal functions that return stdout.
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
status_out = git.status_subcmd.status()
print(status_out)
```
---
## 🧠 Strong Typing Everywhere
Extensive use of type-hints ensures that invalid usages fail early — at *compile-time*. Write at compile-time and be sure that commands run error-free at runtime.
---
<details>
<summary>Allow users to set/unset/reset Git environment variables and main command options using typed, chainable, Pythonic methods — just before a subcommand is executed.</summary>
### 🧬 Git Environment Variables
#### 🔁 Override a single Git env (e.g., `GIT_TRACE`)
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
git = git.git_envs_override(GIT_TRACE=True)
```
#### 🌐 Override multiple Git envs (e.g., `GIT_TRACE`, `GIT_DIR`, `GIT_EDITOR`)
```python
from pathlib import Path
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')
```
#### 🪢 Chain multiple overrides fluently
```python
from pathlib import Path
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
overridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(
GIT_TERMINAL_PROMPT=1,
GIT_NO_REPLACE_OBJECTS=True
)
re_overridden_git = overridden_git.git_envs_override(GIT_TRACE=True)
```
#### ❌ Unset Git envs using a special `UNSET` marker
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
from vt.utils.commons.commons.core_py import UNSET
git = SimpleGitCommand()
overridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)
no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
```
#### 🔄 Reset Git envs by setting new values
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
overridden_git = git.git_envs_override(GIT_TRACE=True)
git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
```
</details>
---
<details>
<summary>Allow users to set/unset/reset git main command options in typed and pythonic manner just before subcommand run to provide maximal flexibility.</summary>
### ⚙️ Git Main Command Options
#### 🔁 Override a single Git opt (e.g., `--no-replace-objects`)
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
git = git.git_opts_override(no_replace_objects=True)
```
#### 🌐 Override multiple options (e.g., `--git-dir`, `--paginate`)
```python
from pathlib import Path
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)
```
#### 🪢 Chain multiple option overrides fluently
```python
from pathlib import Path
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
overridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(
noglob_pathspecs=True,
no_advice=True
).git_opts_override(
config_env={'auth': 'suhas', 'comm': 'suyog'}
)
re_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)
```
#### ❌ Unset Git opts using a special `UNSET` marker
```python
from pathlib import Path
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
from vt.utils.commons.commons.core_py import UNSET
git = SimpleGitCommand()
overridden_git = git.git_opts_override(exec_path=Path('tmp'), no_advice=True)
no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
```
#### 🔄 Reset Git opts by setting new values
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
overridden_git = git.git_opts_override(no_advice=True)
no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
```
</details>
### 🔄 Run unchecked commands
At last, run unchecked commands in git.
Introduced in `0.0.0dev4` to
- experiment.
- have consistent interfaced commands run until all subcommands are provided by the library.
```python
from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
git = SimpleGitCommand()
git = git.git_opts_override(no_advice=True)
git.subcmd_unchecked.run(['--version']) # run the version option for git.
git.subcmd_unchecked.run(['version']) # run the version subcommand.
```
---
## 🔍 Transparent by Default
Output of git commands is returned as-is. No transformations unless explicitly requested.
Transformers for formatting/parsing can be added later.
---
## ✅ Benefits Out-of-the-Box
* 🔄 Composable Git commands.
* 📤 Returns raw stdout.
* 🚨 Exceptions with full context.
* 💤 Lazy execution.
* 🧠 Strong typing and compile-time guarantees.
* 🧼 Idiomatic Python.
* 🧪 Terminal subcommands.
* 💣 Fail-fast on invalid usage.
---
## 📄 More Information
- 📜 [License (Apache-2.0)](./LICENSE)
- 🤝 [Contributing Guide](./CONTRIBUTING.md)
---
## 🚧 Future Goals
* Support `pygit2` for direct, fast Git access.
* Enable `porcelain` support using `pygit2` where required.
Raw data
{
"_id": null,
"home_page": null,
"name": "gitbolt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>",
"keywords": "git, vcs, library, version control",
"author": null,
"author_email": "Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>",
"download_url": "https://files.pythonhosted.org/packages/30/c0/ca9cd184b7435ada6c01d1c15617d8639bc0c277059db931ef624701cbbb/gitbolt-0.0.0.dev7.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Gitbolt\n\n\n\n[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/test.yml)\n[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/typecheck.yml)\n[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/lint.yml)\n[](https://codecov.io/gh/Vaastav-Technologies/py-gitbolt)\n[](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/python-publish.yml)\n\n\n**Fast, flexible and type-safe Git command execution in Python using subprocess.**\n\n---\n\n## \u2728 Features\n\n* \ud83e\udde0 **Typed:** All commands and options are statically type-checked.\n* \u26a1 **Fast:** Minimal abstractions over subprocess, runs directly on your system Git.\n* \ud83e\udde9 **Composable:** Git commands and options can be passed around as objects.\n* \ud83d\udd01 **Overridable:** Easily override environment variables and options in a chainable, readable manner.\n* \ud83d\udce6 **Lightweight:** No dependencies on heavy Git libraries or C extensions.\n* \ud83e\uddf0 **Extensible:** Future support for output transformers and other plugins.\n* \ud83d\udea8 **Exception Handling:** Raises any error as a Python-recognisable exception.\n* \ud83d\udce4 **Debuggable:** Exceptions capture `stdout`, `stderr`, and the return code of the run command.\n* \ud83d\udca4 **Lazy Execution:** Inherently lazily processed.\n* \ud83d\udcc4 **Transparent Output:** Returns a Git command's `stdout` as-is.\n* \ud83e\uddea **Terminal Functions:** Git subcommands are terminal functions.\n* \ud83e\uddfc **Idiomatic Python:** Write commands in idiomatic Python at compile-time and be confident they\u2019ll execute smoothly at runtime.\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install gitbolt\n```\n\n---\n\n## \ud83d\udca1 Motivation\n\nRunning system commands in Python can be tricky for the following reasons:\n\n1. Arguments sent to `subprocess` may not be typed correctly and result in runtime errors.\n2. Argument groups may be mutually exclusive or required conditionally \u2014 again causing runtime issues.\n3. Errors from subprocess are often unhelpful and difficult to debug.\n\nAlso, using subprocess effectively means you must:\n\n* Understand and manage process setup, piping, and teardown.\n* Know your CLI command intricacies in depth.\n\n> This project exists to fix all that \u2014 with ergonomics, speed, and type-safety.\n\n---\n\n## \ud83c\udfaf Project Goals\n\n### \u2705 Predictable Compile-Time Behavior\n\nType-checking ensures runtime safety.\n\n### \u2705 Ergonomic APIs\n\n<details>\n<summary>Make git command interfaces as ergonomic to the user as possible.</summary>\n\n#### Provide versions of most used command combinations\n\n`git hash-object` supports taking multiple files and outputs a hash per file. But in practice, it's most often used to write a single file to the Git object database and return its hash. To match this real-world usage, Gitbolt offers a more ergonomic method that accepts one file and returns one hash \u2014 while still giving you the flexibility to access the full range of `git hash-object` capabilities when needed.\n\n#### Let subcommands be passed around as objects\n\nGitbolt lets you pass subcommands around as typed objects. This enables highly focused, minimal APIs \u2014 you can write functions that accept only the subcommands they truly need. This leads to cleaner logic, better separation of concerns, and compile-time guarantees that help prevent misuse.\n\n```python\nimport gitbolt\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\nversion_subcmd = git.version_subcmd\nadd_subcmd = git.add_subcmd\n\ndef method_which_only_adds_a_file(add_subcmd: gitbolt.base.Add):\n \"\"\"\n This method only requires the `add` subcommand.\n \"\"\"\n ...\n\nmethod_which_only_adds_a_file(add_subcmd)\n```\n\n</details>\n\n### \u2705 Subcommands as Objects\n\ngit subcommands are modeled as terminal functions that return stdout.\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\nstatus_out = git.status_subcmd.status()\nprint(status_out)\n```\n\n---\n\n## \ud83e\udde0 Strong Typing Everywhere\n\nExtensive use of type-hints ensures that invalid usages fail early \u2014 at *compile-time*. Write at compile-time and be sure that commands run error-free at runtime.\n\n---\n\n<details>\n<summary>Allow users to set/unset/reset Git environment variables and main command options using typed, chainable, Pythonic methods \u2014 just before a subcommand is executed.</summary>\n\n### \ud83e\uddec Git Environment Variables\n\n#### \ud83d\udd01 Override a single Git env (e.g., `GIT_TRACE`)\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\ngit = git.git_envs_override(GIT_TRACE=True)\n```\n\n#### \ud83c\udf10 Override multiple Git envs (e.g., `GIT_TRACE`, `GIT_DIR`, `GIT_EDITOR`)\n\n```python\nfrom pathlib import Path\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\ngit = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')\n```\n\n#### \ud83e\udea2 Chain multiple overrides fluently\n\n```python\nfrom pathlib import Path\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\noverridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(\n GIT_TERMINAL_PROMPT=1,\n GIT_NO_REPLACE_OBJECTS=True\n)\nre_overridden_git = overridden_git.git_envs_override(GIT_TRACE=True)\n```\n\n#### \u274c Unset Git envs using a special `UNSET` marker\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\nfrom vt.utils.commons.commons.core_py import UNSET\n\ngit = SimpleGitCommand()\noverridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)\nno_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)\n```\n\n#### \ud83d\udd04 Reset Git envs by setting new values\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\noverridden_git = git.git_envs_override(GIT_TRACE=True)\ngit_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)\n```\n</details>\n\n---\n\n<details>\n<summary>Allow users to set/unset/reset git main command options in typed and pythonic manner just before subcommand run to provide maximal flexibility.</summary>\n\n### \u2699\ufe0f Git Main Command Options\n\n#### \ud83d\udd01 Override a single Git opt (e.g., `--no-replace-objects`)\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\ngit = git.git_opts_override(no_replace_objects=True)\n```\n\n#### \ud83c\udf10 Override multiple options (e.g., `--git-dir`, `--paginate`)\n\n```python\nfrom pathlib import Path\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\ngit = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)\n```\n\n#### \ud83e\udea2 Chain multiple option overrides fluently\n\n```python\nfrom pathlib import Path\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\noverridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(\n noglob_pathspecs=True,\n no_advice=True\n).git_opts_override(\n config_env={'auth': 'suhas', 'comm': 'suyog'}\n)\nre_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)\n```\n\n#### \u274c Unset Git opts using a special `UNSET` marker\n\n```python\nfrom pathlib import Path\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\nfrom vt.utils.commons.commons.core_py import UNSET\n\ngit = SimpleGitCommand()\noverridden_git = git.git_opts_override(exec_path=Path('tmp'), no_advice=True)\nno_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)\n```\n\n#### \ud83d\udd04 Reset Git opts by setting new values\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\noverridden_git = git.git_opts_override(no_advice=True)\nno_advice_reset_git = overridden_git.git_opts_override(no_advice=False)\n```\n\n</details>\n\n### \ud83d\udd04 Run unchecked commands\n\nAt last, run unchecked commands in git.\n\nIntroduced in `0.0.0dev4` to \n- experiment.\n- have consistent interfaced commands run until all subcommands are provided by the library.\n\n```python\nfrom gitbolt.git_subprocess.impl.simple import SimpleGitCommand\n\ngit = SimpleGitCommand()\ngit = git.git_opts_override(no_advice=True)\ngit.subcmd_unchecked.run(['--version']) # run the version option for git.\ngit.subcmd_unchecked.run(['version']) # run the version subcommand.\n```\n\n\n---\n\n## \ud83d\udd0d Transparent by Default\n\nOutput of git commands is returned as-is. No transformations unless explicitly requested.\nTransformers for formatting/parsing can be added later.\n\n---\n\n## \u2705 Benefits Out-of-the-Box\n\n* \ud83d\udd04 Composable Git commands.\n* \ud83d\udce4 Returns raw stdout.\n* \ud83d\udea8 Exceptions with full context.\n* \ud83d\udca4 Lazy execution.\n* \ud83e\udde0 Strong typing and compile-time guarantees.\n* \ud83e\uddfc Idiomatic Python.\n* \ud83e\uddea Terminal subcommands.\n* \ud83d\udca3 Fail-fast on invalid usage.\n\n---\n\n## \ud83d\udcc4 More Information\n\n- \ud83d\udcdc [License (Apache-2.0)](./LICENSE)\n- \ud83e\udd1d [Contributing Guide](./CONTRIBUTING.md)\n\n---\n\n## \ud83d\udea7 Future Goals\n\n* Support `pygit2` for direct, fast Git access.\n* Enable `porcelain` support using `pygit2` where required.\n",
"bugtrack_url": null,
"license": null,
"summary": "Fast, flexible and type-safe Git commands in Python.",
"version": "0.0.0.dev7",
"project_urls": {
"homepage": "https://github.com/Vaastav-Technologies/py-gitbolt",
"issues": "https://github.com/Vaastav-Technologies/py-gitbolt/issues",
"source": "https://github.com/Vaastav-Technologies/py-gitbolt"
},
"split_keywords": [
"git",
" vcs",
" library",
" version control"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "35b5f338a2afef941c616aedf7b82b2755c088364135f4fec69755ef93ee15d4",
"md5": "6c453ab60a0727b60b9e12372abb9289",
"sha256": "81656bb785599274499012e1a3d4c40f737b675c0f7a5bf3994f5c981ede66b7"
},
"downloads": -1,
"filename": "gitbolt-0.0.0.dev7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c453ab60a0727b60b9e12372abb9289",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 44813,
"upload_time": "2025-07-12T15:41:13",
"upload_time_iso_8601": "2025-07-12T15:41:13.523478Z",
"url": "https://files.pythonhosted.org/packages/35/b5/f338a2afef941c616aedf7b82b2755c088364135f4fec69755ef93ee15d4/gitbolt-0.0.0.dev7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "30c0ca9cd184b7435ada6c01d1c15617d8639bc0c277059db931ef624701cbbb",
"md5": "8c6655306f16d6969f1b38938c9a9751",
"sha256": "a5a49916b3aade25539971b91f3ab4dd163fe9104861929d42a93d6ee1b4cc63"
},
"downloads": -1,
"filename": "gitbolt-0.0.0.dev7.tar.gz",
"has_sig": false,
"md5_digest": "8c6655306f16d6969f1b38938c9a9751",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 40280,
"upload_time": "2025-07-12T15:41:15",
"upload_time_iso_8601": "2025-07-12T15:41:15.066424Z",
"url": "https://files.pythonhosted.org/packages/30/c0/ca9cd184b7435ada6c01d1c15617d8639bc0c277059db931ef624701cbbb/gitbolt-0.0.0.dev7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 15:41:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Vaastav-Technologies",
"github_project": "py-gitbolt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gitbolt"
}
