reposort 3.1.1
Organize git repositories by their origin URL
Requires Python: >=3.13

# reposort v3.1.1

Organize git repositories by their origin URL.

## Why?

If you work with many git repositories, you've probably inflicted these problems on yourself:

- **Scattered repositories**: Repos cloned into random directories (`~/workspace`, `~/stufs`, `~/tmp/test123`)
- **Hard to find projects**: No consistent structure makes it difficult to locate specific repositories
- **Duplicate clones**: Multiple copies of the same repo in different locations
- **Mixed sources**: Repos from GitHub, GitLab, BitBucket, and private servers all jumbled together
- **Lost context**: Directory names don't reflect the organization or team that owns the repo

`reposort` fixes your shit by automatically organizing all your git repositories
based on their remote origin URL, creating a predictable, hierarchical structure
that mirrors the source hosting:

```
~/code/
├── aur.archlinux.org/
│   └── weewx/
├── bitbucket.org/
│   ├── bhptechsi/
│   └── ccgmurdoch/
├── github.com/
│   ├── apple/
│   ├── astar-ai/
│   ├── ...
│   ├── sthysel/
│   ├── sthysel-freight/
│   ├── sthyselfreight/
│   ├── sthysel-shop/
│   ├── sthyselzsh/
│   └── windwp/
├── gitlab.com/
│   ├── bhp-cloudfactory/
│   └── vasdee/
├── sdappsgit.bhp.com/
│   ├── iabs/
│   └── mag/
├── sdappsgit.ent.bhpbilliton.net/
│   ├── ddl/
│   ├── hdl/
│   ├── ...
│   ├── scm/
│   ├── toc/
│   └── wts/
└── ssh.dev.azure.com/
    └── v3/
```

This structure makes it easy to:
- Find a repository in context
- Understand where a project comes from at a glance
- Avoid duplicate clones
- Navigate related projects from the same organization
- Script operations across repositories by host or team

**Tip**: While this organization provides a clean canonical structure, you can
maintain a "linkfarm" of symbolic links to frequently used repositories or
project groups for quick access:

```bash
~/active/
├── current-project -> ~/code/github.com/mycompany/api
├── monitoring -> ~/code/github.com/mycompany/monitoring
└── dotfiles -> ~/code/github.com/me/dotfiles
```

This gives you both a well-organised source of truth and convenient shortcuts for active work.

## Installation

### For Users

`reposort` is in pypi, install as a tool using uv:

```bash
# Install globally as a tool
uv tool install reposort

# Or run directly without installation
uvx reposort --dry-run
```

``` sh
$ reposort --help
Usage: reposort [OPTIONS] COMMAND [ARGS]...

  Organize git repositories by their origin URL.

Commands:
  clone  Clone a repository and organize it by its origin URL.
  list   List all repositories in a table view.
  sort   Sort existing repositories by their origin URL.
  tree   Display repositories in a tree view organized by host.

Options:
  --help  Show this message and exit.
```


Using `uvx` is convenient for one-off runs or trying the tool without installing it. The tool will be downloaded and cached automatically.

### For Development

Clone the repository and install in editable mode:

```bash
uv sync
```

This will create a virtual environment, install the package in editable mode, and install all dependencies (including dev dependencies from the lockfile).

## Usage

### Sorting Existing Repositories

Organize existing git repositories on your filesystem:

```bash
# Dry-run to preview changes (default command)
reposort --dry-run
reposort sort --dry-run

# Execute the reorganization (default: searches current dir, targets ~/code)
reposort
reposort sort

# Custom source and target directories
reposort sort --source /path/to/repos --target ~/projects
```

### Cloning New Repositories

Clone repositories directly into the organized structure:

```bash
# Clone to the organized location (dry-run first to see where it goes)
reposort clone https://github.com/user/repo.git --dry-run

# Actually clone the repository
reposort clone https://github.com/user/repo.git

# Clone with SSH URL
reposort clone git@github.com:user/repo.git

# Clone to a custom target directory
reposort clone git@github.com:user/repo.git --target ~/projects
```

This automatically clones to `~/code/github.com/user/repo` (or your custom target), maintaining the same organizational structure as the sort command.

### Viewing Repositories

View your organized repositories with the `list` and `tree` commands:

```bash
# Table view with host, path, branch, status, and remote URL
reposort list

# Show only dirty repositories (uncommitted changes)
reposort list --dirty

# Tree view organized by host
reposort tree

# Tree view showing only dirty repositories
reposort tree --dirty

# View repositories in a custom directory
reposort list --target ~/projects
reposort tree --target ~/projects
```

**Table view (`list`)** shows a table with columns for host, path, branch, status (clean/dirty), and remote URL:

```
+--------------+----------------+---------+--------+---------------------------+
| Host         | Path           | Branch  | Status | Remote URL                |
+--------------+----------------+---------+--------+---------------------------+
| github.com   | sthysel/repo   | main    | clean  | git@github.com:sthysel/.. |
| github.com   | other/project  | develop | dirty  | git@github.com:other/...  |
| gitlab.com   | team/service   | main    | clean  | git@gitlab.com:team/se... |
+--------------+----------------+---------+--------+---------------------------+
```

**Tree view (`tree`)** shows a hierarchical view organized by host and owner:

```
~/code/
├── github.com/
│   ├── sthysel/
│   │   ├── reposort (main, clean)
│   │   └── dotfiles (master, dirty)
│   └── other/
│       └── project (develop, clean)
└── gitlab.com/
    └── team/
        └── service (main, clean)
```

## Examples

### Sorting Existing Repos

Move scattered repositories into organized structure:

```bash
# Before: repos scattered everywhere
~/workspace/my-project/
~/Downloads/temp-repo/
~/code/random-clone/

# Run reposort
reposort

# After: organized by origin URL
~/code/github.com/user/my-project/
~/code/github.com/user/temp-repo/
~/code/gitlab.com/team/random-clone/
```

### Cloning New Repos

Clone directly into organized structure:

```bash
# typical
git clone git@github.com:user/repo.git
cd repo

# With reposort: packed into ~/code/ with dvcs/user/repo
reposort clone git@github.com:user/repo.git
cd ~/code/github.com/user/repo
```

### URL Transformations

Both commands handle various git URL formats:
- `git@github.com:user/repo.git` → `~/code/github.com/user/repo`
- `ssh://git@host:7999/team/project.git` → `~/code/host/team/project`
- `https://github.com/user/repo.git` → `~/code/github.com/user/repo`

## Development

### Quick Start with just

This project includes a `justfile` for common development tasks:

```bash
# Set up dev environment (install deps + pre-commit hooks)
just setup

# Run type checking
just typecheck

# Run linting
just lint

# Auto-fix linting issues
just fix

# Format code
just format

# Run all checks
just check

# Run pre-commit hooks on all files
just pre-commit

# Clean build artifacts
just clean

# See all available commands
just --list
```