(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/