git-gx 0.2.0__tar.gz

git_gx-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Landau
+
+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.

git_gx-0.2.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.3
+Name: git-gx
+Version: 0.2.0
+Summary: A CLI that wraps common git commands with sensible defaults, safety guards, and helpful summaries.
+Author: Nate Landau
+Author-email: Nate Landau <github@natenate.org>
+License: MIT License
+         
+         Copyright (c) 2026 Nate Landau
+         
+         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.
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.13, <3.15
+Description-Content-Type: text/markdown
+
+# gx
+
+A CLI that wraps common git commands with sensible defaults, safety guards, and helpful summaries.
+
+## Features
+
+- Auto-numbered feature branches with optional worktree isolation
+- Push with dirty-tree warnings and default-branch confirmation
+- Pull with automatic stash/unstash and rebase
+- Batch cleanup of merged, gone, and empty branches
+- Rich status dashboard showing all branches at a glance
+- Dry-run mode (`-n`) on every command
+
+## Installation
+
+gx requires Python 3.13 or higher.
+
+```sh
+# install via uv
+uv tool install git-gx
+
+# or install via pip
+pip install git-gx
+```
+
+## Quick Start
+
+```sh
+gx feat                  # create feat/1 from main
+# ... make changes, commit ...
+gx push                  # push to origin with tracking
+# ... PR merged ...
+gx done                  # checkout main, pull, delete feat/1
+```
+
+## Commands
+
+Every command supports `-h` for help. All commands except `status` also support `-v`/`-vv` for verbosity and `-n` for dry-run.
+
+### `gx status`
+
+Display a two-panel dashboard: a color-coded file tree of uncommitted changes and a table of all active branches with ahead/behind counts, file metrics, and stash counts. Running `gx` with no arguments inside a repo shows this dashboard automatically.
+
+```sh
+gx status                # full dashboard
+gx status -F             # file tree only
+gx status -b             # branch table only
+gx status -a             # include inactive branches
+```
+
+### `gx feat`
+
+Create a new feature branch from the latest default branch. Without a name, branches are auto-numbered (`feat/1`, `feat/2`, ...), filling gaps in the sequence.
+
+```sh
+gx feat                  # create feat/1 (or next available)
+gx feat login            # create feat/login
+gx feat -w               # create in a git worktree at .worktrees/feat/1
+gx feat -w ui            # create worktree at .worktrees/feat/ui
+```
+
+Worktree mode (`-w`) lets you work on multiple branches simultaneously without stashing. Requires `.worktrees/` to be in `.gitignore`.
+
+### `gx push`
+
+Push the current branch to its remote tracking branch (or `origin/<branch>` on first push). Automatically sets up tracking.
+
+```sh
+gx push                  # push current branch
+gx push -f               # force push with --force-with-lease
+gx push -t               # push commits and all tags
+```
+
+Safety guards:
+
+- Warns about uncommitted or untracked files that won't be included
+- Asks for confirmation before pushing to the default branch
+- Uses `--force-with-lease` instead of `--force` to prevent overwriting others' work
+
+### `gx pull`
+
+Fetch and rebase the current branch onto its upstream. Handles uncommitted changes automatically.
+
+```sh
+gx pull                  # pull and rebase
+gx pull -v               # pull with debug output
+```
+
+The full sequence:
+
+1. stash uncommitted changes
+2. fetch
+3. rebase
+4. update submodules (if `.gitmodules` exists)
+5. restore stash
+6. print a summary
+
+If a rebase conflict occurs, gx restores your stash and prints resolution steps.
+
+### `gx clean`
+
+Remove branches and worktrees that are no longer needed. Fetches with `--prune` first, then finds branches that are:
+
+- **merged** into the default branch
+- **gone** (upstream deleted on the remote)
+- **empty** (zero commits ahead of the default branch)
+
+```sh
+gx clean                 # interactive cleanup
+gx clean -y              # skip confirmation prompt
+gx clean -f              # include dirty worktrees
+gx clean -n              # preview what would be removed
+```
+
+The current branch, `main`, `master`, and `develop` are always protected. Dirty worktrees are skipped unless you pass `--force`.
+
+### `gx done`
+
+Post-merge cleanup. Checks out the default branch, pulls latest changes, and deletes the feature branch you were on.
+
+```sh
+gx done                  # clean up after a merged PR
+gx done -n               # preview what would happen
+```
+
+If run from a worktree, gx removes the worktree first, then switches to the main working directory.
+
+## Global Options
+
+| Flag               | Description                                 |
+| ------------------ | ------------------------------------------- |
+| `-v`               | Debug output (shows git commands)           |
+| `-vv`              | Trace output (shows git stdout/stderr)      |
+| `-n` / `--dry-run` | Preview changes without executing mutations |
+| `-h` / `--help`    | Show help for any command                   |
+
+## Configuration
+
+gx works out of the box with no configuration. Optionally, create `~/.config/gx/config.toml` to customize defaults:
+
+```toml
+[branches]
+prefix = "feat"                            # branch prefix for `gx feat`
+protected = ["main", "master", "develop"]  # branches protected from cleanup
+
+[worktree]
+directory = ".worktrees"                   # worktree base directory
+
+[remote]
+name = "origin"                            # default remote name
+```
+
+All keys are optional - only specify the ones you want to change.
+
+### Worktree directory
+
+The worktree directory can be relative or absolute:
+
+- **Relative** (e.g. `.worktrees`) - resolved from the repo root. Must be in `.gitignore`.
+- **Absolute** (e.g. `~/tmp/worktrees`) - used as-is. No `.gitignore` requirement.
+
+### Environment variables
+
+Override any setting per-invocation with environment variables:
+
+| Variable                | Example                                          |
+| ----------------------- | ------------------------------------------------ |
+| `GX_BRANCH_PREFIX`      | `GX_BRANCH_PREFIX=fix gx feat`                   |
+| `GX_WORKTREE_DIRECTORY` | `GX_WORKTREE_DIRECTORY=~/wt gx feat -w`          |
+| `GX_PROTECTED_BRANCHES` | `GX_PROTECTED_BRANCHES=main,production gx clean` |
+| `GX_REMOTE_NAME`        | `GX_REMOTE_NAME=upstream gx push`                |
+
+Environment variables take priority over the config file.
+
+## License
+
+MIT

git_gx-0.2.0/README.md

@@ -0,0 +1,177 @@
+# gx
+
+A CLI that wraps common git commands with sensible defaults, safety guards, and helpful summaries.
+
+## Features
+
+- Auto-numbered feature branches with optional worktree isolation
+- Push with dirty-tree warnings and default-branch confirmation
+- Pull with automatic stash/unstash and rebase
+- Batch cleanup of merged, gone, and empty branches
+- Rich status dashboard showing all branches at a glance
+- Dry-run mode (`-n`) on every command
+
+## Installation
+
+gx requires Python 3.13 or higher.
+
+```sh
+# install via uv
+uv tool install git-gx
+
+# or install via pip
+pip install git-gx
+```
+
+## Quick Start
+
+```sh
+gx feat                  # create feat/1 from main
+# ... make changes, commit ...
+gx push                  # push to origin with tracking
+# ... PR merged ...
+gx done                  # checkout main, pull, delete feat/1
+```
+
+## Commands
+
+Every command supports `-h` for help. All commands except `status` also support `-v`/`-vv` for verbosity and `-n` for dry-run.
+
+### `gx status`
+
+Display a two-panel dashboard: a color-coded file tree of uncommitted changes and a table of all active branches with ahead/behind counts, file metrics, and stash counts. Running `gx` with no arguments inside a repo shows this dashboard automatically.
+
+```sh
+gx status                # full dashboard
+gx status -F             # file tree only
+gx status -b             # branch table only
+gx status -a             # include inactive branches
+```
+
+### `gx feat`
+
+Create a new feature branch from the latest default branch. Without a name, branches are auto-numbered (`feat/1`, `feat/2`, ...), filling gaps in the sequence.
+
+```sh
+gx feat                  # create feat/1 (or next available)
+gx feat login            # create feat/login
+gx feat -w               # create in a git worktree at .worktrees/feat/1
+gx feat -w ui            # create worktree at .worktrees/feat/ui
+```
+
+Worktree mode (`-w`) lets you work on multiple branches simultaneously without stashing. Requires `.worktrees/` to be in `.gitignore`.
+
+### `gx push`
+
+Push the current branch to its remote tracking branch (or `origin/<branch>` on first push). Automatically sets up tracking.
+
+```sh
+gx push                  # push current branch
+gx push -f               # force push with --force-with-lease
+gx push -t               # push commits and all tags
+```
+
+Safety guards:
+
+- Warns about uncommitted or untracked files that won't be included
+- Asks for confirmation before pushing to the default branch
+- Uses `--force-with-lease` instead of `--force` to prevent overwriting others' work
+
+### `gx pull`
+
+Fetch and rebase the current branch onto its upstream. Handles uncommitted changes automatically.
+
+```sh
+gx pull                  # pull and rebase
+gx pull -v               # pull with debug output
+```
+
+The full sequence:
+
+1. stash uncommitted changes
+2. fetch
+3. rebase
+4. update submodules (if `.gitmodules` exists)
+5. restore stash
+6. print a summary
+
+If a rebase conflict occurs, gx restores your stash and prints resolution steps.
+
+### `gx clean`
+
+Remove branches and worktrees that are no longer needed. Fetches with `--prune` first, then finds branches that are:
+
+- **merged** into the default branch
+- **gone** (upstream deleted on the remote)
+- **empty** (zero commits ahead of the default branch)
+
+```sh
+gx clean                 # interactive cleanup
+gx clean -y              # skip confirmation prompt
+gx clean -f              # include dirty worktrees
+gx clean -n              # preview what would be removed
+```
+
+The current branch, `main`, `master`, and `develop` are always protected. Dirty worktrees are skipped unless you pass `--force`.
+
+### `gx done`
+
+Post-merge cleanup. Checks out the default branch, pulls latest changes, and deletes the feature branch you were on.
+
+```sh
+gx done                  # clean up after a merged PR
+gx done -n               # preview what would happen
+```
+
+If run from a worktree, gx removes the worktree first, then switches to the main working directory.
+
+## Global Options
+
+| Flag               | Description                                 |
+| ------------------ | ------------------------------------------- |
+| `-v`               | Debug output (shows git commands)           |
+| `-vv`              | Trace output (shows git stdout/stderr)      |
+| `-n` / `--dry-run` | Preview changes without executing mutations |
+| `-h` / `--help`    | Show help for any command                   |
+
+## Configuration
+
+gx works out of the box with no configuration. Optionally, create `~/.config/gx/config.toml` to customize defaults:
+
+```toml
+[branches]
+prefix = "feat"                            # branch prefix for `gx feat`
+protected = ["main", "master", "develop"]  # branches protected from cleanup
+
+[worktree]
+directory = ".worktrees"                   # worktree base directory
+
+[remote]
+name = "origin"                            # default remote name
+```
+
+All keys are optional - only specify the ones you want to change.
+
+### Worktree directory
+
+The worktree directory can be relative or absolute:
+
+- **Relative** (e.g. `.worktrees`) - resolved from the repo root. Must be in `.gitignore`.
+- **Absolute** (e.g. `~/tmp/worktrees`) - used as-is. No `.gitignore` requirement.
+
+### Environment variables
+
+Override any setting per-invocation with environment variables:
+
+| Variable                | Example                                          |
+| ----------------------- | ------------------------------------------------ |
+| `GX_BRANCH_PREFIX`      | `GX_BRANCH_PREFIX=fix gx feat`                   |
+| `GX_WORKTREE_DIRECTORY` | `GX_WORKTREE_DIRECTORY=~/wt gx feat -w`          |
+| `GX_PROTECTED_BRANCHES` | `GX_PROTECTED_BRANCHES=main,production gx clean` |
+| `GX_REMOTE_NAME`        | `GX_REMOTE_NAME=upstream gx push`                |
+
+Environment variables take priority over the config file.
+
+## License
+
+MIT

git_gx-0.2.0/pyproject.toml

@@ -0,0 +1,163 @@
+[project]
+    authors = [{ name = "Nate Landau", email = "github@natenate.org" }]
+    classifiers = [
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+    ]
+    dependencies = ["rich>=14.3.3", "typer>=0.24.1"]
+    description = "A CLI that wraps common git commands with sensible defaults, safety guards, and helpful summaries."
+    license = { file = "LICENSE" }
+    name = "git-gx"
+    readme = "README.md"
+    requires-python = ">=3.13,<3.15"
+    version = "0.2.0"
+
+    [project.scripts]
+        gx = "gx.cli:main"
+
+[build-system]
+    build-backend = "uv_build"
+    requires      = ["uv_build>=0.10.12,<0.11.0"]
+
+[tool.uv.build-backend]
+    module-name = "gx"
+
+[dependency-groups]
+    dev = [
+        "commitizen>=4.13.9",
+        "coverage>=7.13.5",
+        "duty>=1.9.0",
+        "prek>=0.3.6",
+        "pytest-clarity>=1.0.1",
+        "pytest-cov>=7.1.0",
+        "pytest-devtools>=1.0.0",
+        "pytest-mock>=3.15.1",
+        "pytest-repeat>=0.9.4",
+        "pytest-sugar>=1.1.1",
+        "pytest-xdist>=3.8.0",
+        "pytest>=9.0.2",
+        "ruff>=0.15.7",
+        "shellcheck-py>=0.11.0.1",
+        "ty>=0.0.24",
+        "typos>=1.44.0",
+        "yamllint>=1.38.0",
+    ]
+
+[tool.commitizen]
+    bump_message               = "bump(release): v$current_version → v$new_version"
+    changelog_merge_prerelease = true
+    tag_format                 = "v$version"
+    update_changelog_on_bump   = true
+    version_files              = ["src/gx/__init__.py:__version__"]
+    version_provider           = "uv"
+
+[tool.coverage.report] # https://coverage.readthedocs.io/en/latest/config.html#report
+    exclude_lines = [
+        'def __repr__',
+        'except [\w\s\._]+ as .*:',
+        'if TYPE_CHECKING',
+        'pragma: no cover',
+    ]
+    fail_under = 10
+    show_missing = true
+    skip_covered = true
+    skip_empty = true
+
+[tool.coverage.run]
+    branch       = true
+    command_line = "--module pytest"
+    data_file    = ".cache/coverage"
+    omit         = ["tests/*"]
+    source       = ["src"]
+
+[tool.coverage.xml]
+    output = ".cache/coverage.xml"
+
+[tool.pytest.ini_options]
+
+    addopts        = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
+    cache_dir      = ".cache/pytest"
+    columns        = 120
+    filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
+    markers        = ["serial"]
+    set_columns    = true
+    testpaths      = ["tests"]
+    xfail_strict   = true
+
+[tool.ruff] # https://github.com/charliermarsh/ruff
+
+    exclude        = [".cache", ".git", ".venv", "build", "dist", "reference"]
+    fix            = true
+    line-length    = 100
+    output-format  = "grouped"
+    src            = ["src", "tests"]
+    target-version = "py313"
+    [tool.ruff.lint]
+        ignore = [
+            "ANN002", # Missing type annotation for `*args`
+            "ANN003", # Missing type annotation for `**kwargs`
+            "ANN204", # missing return type annotation for special method `__init__`
+            # "B006",    # mutable-argument-default
+            # "B008",    # function-call-in-default-argument
+            "COM812",  # Trailing comma missing"
+            "CPY001",  # Missing copyright notice at top of file
+            "D107",    # undocumented-public-init
+            "E501",    # line-too-long
+            "PLC0415", # Imports should be at top of file
+            # "FBT001", # Boolean-typed positional argument in function definition
+            # "FBT002", # Boolean-typed positional argument in function definition
+            "FIX002", # Line contains TODO, consider resolving the issue
+            "S311",   # suspicious-non-cryptographic-random-usage
+            "TD001",  # invalid-todo-tag
+            "TD002",  # Missing author in TODO
+            "TD003",  # Missing issue link on the line following this TODO
+        ]
+        per-file-ignores = { "tests/**/*.py" = [
+            "A002",
+            "A003",
+            "ANN001",  # Missing type annotation for function argument `cls`
+            "ANN002",  # Missing type annotation for `*args`
+            "ANN003",  # Missing type annotation for `**kwargs`
+            "ANN201",  # Missing return type annotation
+            "ARG001",  # Unused function argument
+            "ARG002",  # Unused method argument
+            "ARG005",  # Unused lambda argument
+            "D102",
+            "ERA001",  # Commented out code
+            "F403",
+            "F405",    # May be undefined from type imports
+            "FBT001",  # Boolean-typed positional argument in function definition
+            "PGH003",  # Use specific rule codes when ignoring type issues
+            "PLC0415", # Imports should be at top of file
+            "PLR0913",
+            "PLR2004",
+            "PLW0108", # Lambda may be unnecessary; consider inlining inner function
+            "S101",
+            "SLF001",  # Calling private method
+            "W292",    # No blank line at end of file - included b/c cursor struggles to add a trailing newline and burns through requests trying to fix this linting error.
+        ] }
+        select = ["ALL"]
+        unfixable = [
+            "ERA001", # Commented out code
+            "F401",   # unused-import
+            "F841",   # unused-variable
+        ]
+
+        [tool.ruff.lint.mccabe]
+            # Unlike Flake8, default to a complexity level of 10.
+            max-complexity = 10
+
+        [tool.ruff.lint.pydocstyle]
+            convention = "google"
+
+        [tool.ruff.lint.pylint]
+            max-args = 7
+
+        [tool.ruff.lint.flake8-annotations]
+            allow-star-arg-any = true
+
+    [tool.ruff.format]
+        indent-style              = "space"
+        line-ending               = "auto"
+        quote-style               = "double"
+        skip-magic-trailing-comma = false

git_gx-0.2.0/src/gx/__init__.py

@@ -0,0 +1,3 @@
+"""GX - A CLI tool for managing Git repositories."""
+
+__version__ = "0.2.0"

git_gx-0.2.0/src/gx/cli.py

@@ -0,0 +1,85 @@
+"""GX CLI - A wrapper around common git commands."""
+
+from __future__ import annotations
+
+import typer
+from typer import rich_utils
+
+from gx import __version__
+from gx.commands import clean, done, feat, pull, push, status
+from gx.lib.console import set_verbosity
+from gx.lib.git import check_git_installed, git
+from gx.lib.options import VERBOSE_OPTION
+
+rich_utils.STYLE_HELPTEXT = ""  # ty:ignore[invalid-assignment]
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+app = typer.Typer(rich_markup_mode="rich", context_settings=CONTEXT_SETTINGS)
+app.add_typer(push.app, name="push")
+app.add_typer(pull.app, name="pull")
+app.add_typer(feat.app, name="feat")
+app.add_typer(clean.app, name="clean")
+app.add_typer(done.app, name="done")
+app.add_typer(status.app, name="status")
+
+
+def _version_callback(value: bool) -> None:  # noqa: FBT001
+    """Print version and exit."""
+    if value:
+        typer.echo(f"gx {__version__}")
+        raise typer.Exit
+
+
+def _is_git_repo() -> bool:
+    """Return True if the current directory is inside a git repository."""
+    result = git("rev-parse", "--is-inside-work-tree")
+    return result.success
+
+
+@app.callback(invoke_without_command=True)
+def callback(
+    ctx: typer.Context,
+    verbose: int = VERBOSE_OPTION,
+    _version: bool | None = typer.Option(  # noqa: FBT001
+        None,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_flag=True,
+        expose_value=False,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Streamline your git workflow.
+
+    GX wraps common git operations with sensible defaults, safety guards, and helpful summaries. Every command supports --dry-run and --verbose flags.
+
+    Run [bold]gx COMMAND -h[/bold] for details on a specific command.
+
+    [bold]Common workflows:[/bold]
+
+      Start a feature branch:     gx feat
+      Push your work:             gx push
+      Pull latest changes:        gx pull
+      Clean stale branches:       gx clean
+      Finish a merged PR:         gx done
+      View status dashboard:      gx status
+
+    Configure defaults in ~/.config/gx/config.toml
+    """
+    set_verbosity(verbose)
+    check_git_installed()
+    if ctx.invoked_subcommand is None:
+        if _is_git_repo():
+            status_cmd = getattr(ctx.command, "commands", {}).get("status")
+            if status_cmd:
+                ctx.invoke(status_cmd)
+        else:
+            typer.echo(ctx.get_help())
+
+
+def main() -> None:
+    """Entry point for the gx CLI."""
+    app()

git_gx-0.2.0/src/gx/commands/__init__.py

@@ -0,0 +1 @@
+"""Subcommand modules for gx."""