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

# Internal API

Most users do not need this page. Start with {doc}`quickstart` or
{doc}`cli/index` if you only want the command-line wrapper.

```{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:
```

[tracker]: https://github.com/vcs-python/g/issues

---

# 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
Repository detection.
:::

::::

g is a minimal CLI wrapper that proxies to your current directory's VCS command.
It detects [Git], [Subversion], and [Mercurial] repositories.

## 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:** {argparse:option}`--version <g --version>`/{argparse:option}`-V <g -V>`
is handled by g itself rather than passed to the VCS.

## Usage examples

```console
$ g status
```

Is equivalent to:

In a git repo:

```console
$ git status
```

In an svn repo:

```console
$ svn status
```

In an hg repo:

```console
$ hg status
```

(cli-main)=

## Command

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

## Examples

```console
$ g status
```

```console
$ g commit -m "Fix bug"
```

```console
$ g log --oneline -10
```

```console
$ g diff HEAD~1
```

(cli-supported-vcs)=

## Supported VCS

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

[Git]: https://git-scm.com/
[Mercurial]: https://www.mercurial-scm.org/
[Subversion]: https://subversion.apache.org/

---

# 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], [Subversion], and [Mercurial] -- 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 {doc}`quickstart` for all installation methods and first steps.

## At a glance

```console
$ g status
```

Inside a git repo, that is equivalent to:

```console
$ git status
```

Inside an svn checkout:

```console
$ svn status
```

Inside a mercurial repo:

```console
$ hg status
```

[Git]: https://git-scm.com/
[Mercurial]: https://www.mercurial-scm.org/
[Subversion]: https://subversion.apache.org/

```{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

Use this page when you are changing g itself and want the same local checks CI
expects.

## Formatting

Run [ruff](https://github.com/astral-sh/ruff) before committing Python changes.

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

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

## Type Checking

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

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

---

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

# Development

Use this page when you want to change g itself. If you only want to install and
run the command, start with {doc}`/quickstart`.

## Bootstrap the project

Install [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

```console
$ uv run py.test
```

The Makefile wrapper runs the same test command.

```console
$ make test
```

## Automatically run tests on file save

Run tests once, then keep watching with [pytest-watcher]:

```console
$ make start
```

Watch through [entr(1)] if you have it installed:

```console
$ make watch_test
```

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

## Documentation

Default preview server: http://localhost:8034

[sphinx-autobuild] builds the docs, watches for file changes, and launches a
server.

From the project root:

```console
$ make start_docs
```

From inside `docs/`:

```console
$ make start
```

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

### Manual documentation

Enter the docs directory:

```console
$ cd docs
```

Build the docs:

```console
$ make html
```

Start the HTTP server:

```console
$ make serve
```

Project-root helpers run the same docs tasks:

```console
$ make build_docs
```

```console
$ make serve_docs
```

Rebuild docs on file change with [entr(1)]:

```console
$ make watch_docs
```

Rebuild docs and run the server through one terminal when your [GNU Make] has
`-J` support:

```console
$ make dev_docs
```

## Formatting / Linting

### Linting and formatting

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

````{tab} Command

uv:

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

If you set up 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 set up manually:

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

````

#### Code formatting

Use [ruff format] for formatting.

````{tab} Command

uv:

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

If you set up manually:

```console
$ ruff format .
```

````

````{tab} make

```console
$ make ruff_format
```

````

### Type checking

Use [mypy] for static type checking.

````{tab} Command

uv:

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

If you set up 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. There is no `setup.py` or requirements file.

See {doc}`/project/releasing` before preparing a release.

[uv]: https://github.com/astral-sh/uv
[entr(1)]: http://eradman.com/entrproject/
[`entr(1)`]: http://eradman.com/entrproject/
[GNU Make]: https://www.gnu.org/software/make/
[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

Use this section when you want to change g itself: set up a checkout, run the
project checks, or prepare a release.

::::{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
Formatting, type checks, and import conventions.
:::

::::

```{toctree}
:hidden:

contributing
code-style
releasing
```

---

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

# Releasing

## Release Process

Use this page when you are preparing a g release. Tags trigger publishing to
[PyPI] via [OIDC] trusted publishing, so create and push them only when you
intend to publish.

1. Update `CHANGES` with the release notes

2. Bump the version in `src/g/__about__.py` and `pyproject.toml`

3. Commit the release files with the subject `Tag v<version>`

4. Tag:

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

5. Push the branch:

   ```console
   $ git push
   ```

6. Push the tag:

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

7. CI builds and publishes to PyPI automatically

For AI agents: do not create or push tags unless the user explicitly asks.
Prepare the release files and commit only.

[OIDC]: https://openid.net/developers/how-connect-works/
[PyPI]: https://pypi.org/

---

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

(quickstart)=

# Quickstart

## Installation

Install g once, then run `g` where you already run [Git], [Subversion], or
[Mercurial].
Use one of these commands for the latest official version.

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

Or install it as a [uv] tool:

```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
```

Upgrade an existing install the same way.

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

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
  ```

  Then use the suffixed command:

  ```console
  $ 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
  ```

For unreleased trunk builds, expect breakage:

- [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/
[PyPI]: https://pypi.org/
[uv]: https://docs.astral.sh/uv/
[uv-tools]: https://docs.astral.sh/uv/concepts/tools/
[uvx]: https://docs.astral.sh/uv/guides/tools/
[Git]: https://git-scm.com/
[Mercurial]: https://www.mercurial-scm.org/
[Subversion]: https://subversion.apache.org/

---