# Internal API
Source: https://g.git-pull.com/api/

# Internal API

```{note}
These APIs are private and can break between versions. If you want to use them directly, file an issue on the tracker.
```

```{eval-rst}
.. automodule:: g
   :members:
   :show-inheritance:
   :undoc-members:
```

---

# CLI Reference
Source: https://g.git-pull.com/cli/

(cli)=

# CLI Reference

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} g
:link: cli-main
:link-type: ref
Proxy to your repo's VCS command.
:::

:::{grid-item-card} Supported VCS
:link: cli-supported-vcs
:link-type: ref
git, svn, and hg detection.
:::

::::

g is a minimal CLI wrapper that proxies to your current directory's VCS command.

## How it works

When you run `g`, it:

1. Walks up from your current directory looking for `.git`, `.svn`, or `.hg`
2. Invokes the corresponding VCS (`git`, `svn`, or `hg`) with your arguments
3. Exits after the command completes

**Note:** `--version`/`-V` is handled by g itself rather than passed to the VCS.

## Usage examples

```console
$ g status
```

Is equivalent to:

```console
$ git status  # if in a git repo
$ svn status  # if in an svn repo
$ hg status   # if in an hg repo
```

(cli-main)=

## Command

```{eval-rst}
.. argparse::
    :module: g
    :func: create_parser
    :prog: g
```

## Examples

```console
$ g status
$ g commit -m "Fix bug"
$ g log --oneline -10
$ g diff HEAD~1
```

(cli-supported-vcs)=

## Supported VCS

| Directory marker | VCS command |
|------------------|-------------|
| `.git`           | `git`       |
| `.svn`           | `svn`       |
| `.hg`            | `hg`        |

---

# Changelog
Source: https://g.git-pull.com/history/

(history)=

```{include} ../CHANGES

```

---

# g
Source: https://g.git-pull.com/

(index)=

# g

A tiny CLI wrapper for git, svn, and hg -- auto-detects your repo type and proxies commands.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Quickstart
:link: quickstart
:link-type: doc
Install and run your first command.
:::

:::{grid-item-card} CLI Reference
:link: cli/index
:link-type: doc
Every command, flag, and option.
:::

:::{grid-item-card} Contributing
:link: project/index
:link-type: doc
Development setup, code style, and releases.
:::

::::

## Install

```console
$ pip install --user g
```

```console
$ uv tool install g
```

See [Quickstart](quickstart.md) for all installation methods and first steps.

## At a glance

```console
$ g status
```

Inside a git repo this runs `git status`; inside an svn checkout it runs `svn status`; inside a mercurial repo it runs `hg status`.

```{toctree}
:hidden:

quickstart
cli/index
api
project/index
history
GitHub <https://github.com/vcs-python/g>
```

---

# Code Style
Source: https://g.git-pull.com/project/code-style/

# Code Style

## Formatting

g uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting.

```console
$ uv run ruff format .
```

```console
$ uv run ruff check . --fix
```

## Type Checking

[mypy](https://mypy-lang.org/) is used for static type checking.

```console
$ uv run mypy
```

---

# Development
Source: https://g.git-pull.com/project/contributing/

# Development

[uv] is a required package to develop.

## Bootstrap the project

Install and [git] and [uv]

Clone:

```console
$ git clone https://github.com/vcs-python/g.git
```

```console
$ cd g
```

Install packages:

```console
$ uv sync --all-extras --dev
```

[installation documentation]: https://docs.astral.sh/uv/getting-started/installation/
[git]: https://git-scm.com/

## Tests

`uv run py.test`

Helpers: `make test`

## Automatically run tests on file save

1. `make start` (via [pytest-watcher])
2. `make watch_test` (requires installing [entr(1)])

[pytest-watcher]: https://github.com/olzhasar/pytest-watcher

## Documentation

Default preview server: http://localhost:8034

[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.

From home directory: `make start_docs`
From inside `docs/`: `make start`

[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild

### Manual documentation (the hard way)

`cd docs/` and `make html` to build. `make serve` to start http server.

Helpers:
`make build_docs`, `make serve_docs`

Rebuild docs on file change: `make watch_docs` (requires [entr(1)])

Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a
`make(1)` with `-J` support, e.g. GNU Make)

## Formatting / Linting

### ruff

The project uses [ruff] to handle formatting, sorting imports and linting.

````{tab} Command

uv:

```console
$ uv run ruff
```

If you setup manually:

```console
$ ruff check .
```

````

````{tab} make

```console
$ make ruff
```

````

````{tab} Watch

```console
$ make watch_ruff
```

requires [`entr(1)`].

````

````{tab} Fix files

uv:

```console
$ uv run ruff check . --fix
```

If you setup manually:

```console
$ ruff check . --fix
```

````

#### ruff format

[ruff format] is used for formatting.

````{tab} Command

uv:

```console
$ uv run ruff format .
```

If you setup manually:

```console
$ ruff format .
```

````

````{tab} make

```console
$ make ruff_format
```

````

### mypy

[mypy] is used for static type checking.

````{tab} Command

uv:

```console
$ uv run mypy .
```

If you setup manually:

```console
$ mypy .
```

````

````{tab} make

```console
$ make mypy
```

````

````{tab} Watch

```console
$ make watch_mypy
```

requires [`entr(1)`].
````

## Releasing

[uv] handles virtualenv creation, package requirements, versioning,
building, and publishing. Therefore there is no setup.py or requirements files.

Update `__version__` in `__about__.py` and `pyproject.toml`::

    git commit -m 'build(g): Tag v0.1.1'
    git tag v0.1.1
    git push
    git push --tags

[uv]: https://github.com/astral-sh/uv
[entr(1)]: http://eradman.com/entrproject/
[`entr(1)`]: http://eradman.com/entrproject/
[ruff format]: https://docs.astral.sh/ruff/formatter/
[ruff]: https://ruff.rs
[mypy]: http://mypy-lang.org/

---

# Project
Source: https://g.git-pull.com/project/

(project)=

# Project

Information for contributors and maintainers.

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Contributing
:link: contributing
:link-type: doc
Development setup, running tests, submitting PRs.
:::

:::{grid-item-card} Code Style
:link: code-style
:link-type: doc
Ruff, mypy, and import conventions.
:::

::::

```{toctree}
:hidden:

contributing
code-style
releasing
```

---

# Releasing
Source: https://g.git-pull.com/project/releasing/

# Releasing

## Release Process

Releases are triggered by git tags and published to PyPI via OIDC trusted publishing.

1. Update `CHANGES` with the release notes

2. Bump version in `src/g/__about__.py` (or wherever version is defined -- check pyproject.toml)

3. Tag:

   ```console
   $ git tag v<version>
   ```

4. Push:

   ```console
   $ git push && git push --tags
   ```

5. CI builds and publishes to PyPI automatically

---

# Quickstart
Source: https://g.git-pull.com/quickstart/

(quickstart)=

# Quickstart

## Installation

For latest official version:

```console
$ pip install --user g
```

Or install with [uv](https://docs.astral.sh/uv/):

```console
$ uv tool install g
```

Add g to a uv-managed project:

```console
$ uv add g
```

Run g once without installing globally:

```console
$ uvx g
```

Upgrading:

```console
$ pip install --user --upgrade g
```

Or with uv:

```console
$ uv tool upgrade g
```

```console
$ uv add g
```

(developmental-releases)=

### Developmental releases

New versions of g are published to PyPI as alpha, beta, or release candidates.
In their versions you will see notification like `a1`, `b1`, and `rc1`, respectively.
`1.10.0b4` would mean the 4th beta release of `1.10.0` before general availability.

- [pip]\:

  ```console
  $ pip install --user --upgrade --pre g
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@next 'g' --pip-args '\--pre' --force
  // Usage: g@next --help
  ```

- [uv tool install][uv-tools]\:

  ```console
  $ uv tool install --prerelease=allow g
  ```

- [uv]\:

  ```console
  $ uv add g --prerelease allow
  ```

- [uvx]\:

  ```console
  $ uvx --from 'g' --prerelease allow g
  ```

via trunk (can break easily):

- [pip]\:

  ```console
  $ pip install --user -e git+https://github.com/vcs-python/g.git#egg=g
  ```

- [uv]\:

  ```console
  $ uv tool install git+https://github.com/vcs-python/g.git
  ```

  ```console
  $ uv add git+https://github.com/vcs-python/g.git
  ```

  ```console
  $ uvx --from git+https://github.com/vcs-python/g.git g --version
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@master 'g @ git+https://github.com/vcs-python/g.git@master' --force
  ```

[pip]: https://pip.pypa.io/en/stable/
[pipx]: https://pypa.github.io/pipx/docs/
[uv]: https://docs.astral.sh/uv/
[uv-tools]: https://docs.astral.sh/uv/concepts/tools/
[uvx]: https://docs.astral.sh/uv/guides/tools/

---