Metadata-Version: 2.3
Name: git-proj
Version: 0.5.1
Summary: Discover, track, and sync Git repos across GitHub, GitLab, and Gitea
Keywords: git,github,gitlab,gitea,sync,cli,workspace-manager,multi-repo,developer-tools,git-automation,forge-discovery
Author: Jev Kuznetsov
Author-email: Jev Kuznetsov <jev.kuznetsov@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Dist: httpx>=0.28.1
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: typer>=0.12
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/sjev/git-projects
Project-URL: Repository, https://github.com/sjev/git-projects
Description-Content-Type: text/markdown

# git-proj

Discover, track, and sync Git repos across GitHub, GitLab, and Gitea from one CLI.


## Why

If you juggle between different projects and work across multiple Git foundries — GitHub, a company GitLab, a self-hosted Gitea — you may lose track of what lives where and what you've been working on recently.

`git-proj` gives you one place to discover repos via APIs, pick which ones to track, and keep them synced locally.

## Install

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
uv tool install git-proj
```

Or from source:

```bash
git clone https://github.com/sjev/git-projects.git
cd git-projects
uv sync --frozen
```

The CLI command is `gpr`.

## Quick start

```bash
# Create config with default foundries
gpr config init

# Edit ~/.local/share/git-projects/config.yaml to add your API tokens

# Fetch all repos from configured foundries
gpr fetch

# Browse what's available (tracked projects are highlighted with their path)
gpr list
gpr list myproject    # filter by name

# Track a repo by name (resolved from index) or URL
gpr track my-repo
gpr track git@github.com:user/repo.git

# Clone missing repos, pull & push existing ones
gpr sync

# Stop tracking
gpr untrack my-repo
```

## Commands

| Command | Description |
|---|---|
| `config init` | Create default config file |
| `config show` | Show config path and contents |
| `fetch [foundry]` | Fetch repos from foundry APIs, save to local index |
| `list [query]` | Browse indexed repos (tracked projects highlighted with path) |
| `track <name\|url> [--path]` | Add a project to tracking |
| `untrack <name>` | Remove a project from tracking |
| `sync [--workers N]` | Clone missing repos, pull & push existing tracked repos |
| `info` | Show version, paths, and repo counts |

## Configuration

Config lives at `$XDG_DATA_HOME/git-projects/` (typically `~/.local/share/git-projects/`):

```
config.yaml      # foundries, clone_root, credentials — never share this
projects.json    # tracked projects (portable, no secrets)
index.json       # cached repo metadata from last fetch
```

Example `config.yaml`:

```yaml
clone_root: ~/projects
clone_url_format: ssh    # or "https"
foundries:
  - name: github
    type: github
    token: ghp_...
  - name: my-gitea
    type: gitea
    url: https://gitea.example.com
    token: ""
```

### Multi-machine setup

`projects.json` is portable (relative paths, no secrets). Copy it between machines:

```bash
scp ~/.local/share/git-projects/projects.json other-machine:~/.local/share/git-projects/
gpr sync
```

## Development

```bash
uv sync --group dev
uv run invoke lint      # ruff check + ruff format --check + mypy
uv run invoke test      # pytest with coverage
uv run invoke format    # ruff format
```

### Versioning

Bump the version with [bump-my-version](https://github.com/callowayproject/bump-my-version):

```bash
uv run invoke bump           # patch: 0.1.0 → 0.1.1
uv run invoke bump --part minor  # minor: 0.1.0 → 0.2.0
uv run invoke bump --part major  # major: 0.1.0 → 1.0.0
```

Each bump updates `pyproject.toml`, creates a git commit, and tags the release.

## License

MIT
