WorldTeacher/README.md

# GitRepoSetup

A multi-language tool to initialize and configure git repositories with licenses, .gitignore files, and Gitea CI/CD workflows.

## Features

- **Multi-language implementations**: Python, Rust, and Go with identical functionality
- **License management**: Embed MIT, GPLv3, AGPLv3, or Unlicense with automatic year and author substitution
- **Git repository setup**: Initialize repos, set remotes, create branches (main + dev)
- **Gitea workflow scaffolding**: Automatically set up CI/CD workflows for Docker, PyPI, Cargo, or Go deployments
- **Cross-platform config**: Stores defaults in `~/.config/GMS/.config.yaml` (Windows: `%USERPROFILE%\.config\GMS\.config.yaml`)
- **Force remote reset**: Removes all existing remotes and sets new `origin`
- **Network-aware**: Warns when remote push fails and configures locally

## Installation

### Python

```bash
cd python
uv sync
uv pip install -e .
```

Or build a standalone binary:
```bash
cd python
python embed_assets.py  # Embeds licenses and .gitignore
uv build
# Or use PyInstaller for single executable
```

### Rust

```bash
cd rust
cargo build --release
# Binary at: target/release/gitreposetup
```

### Go

```bash
cd go
go build -o gitreposetup .
# Or for cross-platform builds:
# CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o gitreposetup-linux-amd64
```

## Usage

### Basic Setup

```bash
gitreposetup --owner YourOrg --name YourRepo
```

This will:
1. Initialize a git repository (if not already one)
2. Set default branch to `main`
3. Remove all existing remotes and set `origin` to configured URL
4. Add LICENSE (MIT by default) with current year and git user.name
5. Add/overwrite `.gitignore` from embedded template
6. Commit changes
7. Create and switch to `dev` branch
8. Push to remote (or warn if network unavailable)

### Configuration File

Default config created at `~/.config/GMS/.config.yaml`:

```yaml
owner: ""
name: ""
license: MIT
develop_branch: dev
default_gitignore: true
default_git_url: "https://git.theprivateserver.de/{owner}/{repo}.git"
```

CLI arguments override config values.

### Advanced Options

```bash
# Use different license
gitreposetup --owner MyOrg --name MyProject --license GPLv3

# Custom dev branch name
gitreposetup --owner MyOrg --name MyProject --develop-branch-name develop

# Force overwrite existing LICENSE
gitreposetup --owner MyOrg --name MyProject --force

# Set up Gitea workflows for Python package deployment
gitreposetup --owner MyOrg --name MyProject --deploy-type pypi

# Custom git URL template
gitreposetup --owner MyOrg --name MyProject --default-git-url "https://github.com/{owner}/{repo}.git"
```

### Deploy Types

#### Docker (`--deploy-type docker`)
Creates workflows for:
- `test-python-docker-build.yml` / `test-rust-docker-build.yml` / `test-go-docker-build.yml`
- `docker-release.yml`

**Requires**: Root `Dockerfile`  
**Secrets**: `REGISTRY`, `DOCKER_USERNAME`, `TOKEN`, `GITEA_TOKEN`

#### PyPI (`--deploy-type pypi`)
Creates workflows for:
- `test-python.yml` (pytest, mypy, ruff)
- `python_package-release.yml`

**Secrets**: `TOKEN`, `GITEA_TOKEN`

#### Cargo (`--deploy-type cargo`)
Creates workflows for:
- `test-rust.yml` (cargo test, clippy, fmt)
- `cargo-release.yml`

**Secrets**: `TOKEN`, `GITEA_TOKEN`

#### Go (`--deploy-type go`)
Creates workflows for:
- `test-go.yml` (go test, vet, fmt)
- `go-release.yml`

**Secrets**: `TOKEN`, `GITEA_TOKEN`

## Gitea Workflows

All workflows are created under `.gitea/workflows/` with:
- Proper `name:` fields for `workflow_run` triggers
- Reference to `.gitea/changelog_config.json`
- Hardcoded Gitea baseURL (`http://192.168.178.20:3000` or `http://192.168.178.110:3000`)
- `workflow_dispatch` triggers for release workflows

### Required Secrets

Set these in your Gitea user or organization settings:
- `GITEA_TOKEN`: Gitea API token for changelog and releases
- `TOKEN`: Generic token for publishing and releases
- `REGISTRY`: Docker registry URL (for Docker deployments)
- `DOCKER_USERNAME`: Docker registry username (for Docker deployments)
- `GITHUB_TOKEN`: Auto-provided by Gitea Actions

## License Templates

Embedded licenses with automatic substitutions:
- **MIT**: `{year}` → current year, `{fullname}` → git user.name or `--owner`
- **GPLv3**: Full GPL 3.0 text with HTML entity decoding
- **AGPLv3**: Full AGPL 3.0 text with HTML entity decoding
- **Unlicense**: Public domain dedication

## Architecture

All three implementations (Python, Rust, Go) share:
- Identical CLI interface via argparse/clap/cobra
- Embedded license files and .gitignore (via include_str!/go:embed)
- Same git flow: init → main → remote → commit → dev → push
- Consistent config file format (YAML)
- Cross-platform path handling

### Python Implementation
- **Dependencies**: PyYAML
- **Git**: subprocess calls
- **Packaging**: PyInstaller for standalone binaries

### Rust Implementation
- **Dependencies**: clap, serde_yaml, git2, html-escape, chrono
- **Git**: libgit2 via git2 crate
- **Packaging**: Native Cargo release builds

### Go Implementation
- **Dependencies**: cobra, yaml.v3, go-git (optional, uses CLI)
- **Git**: subprocess calls to git CLI
- **Packaging**: Native Go build with CGO_ENABLED=0 for static binaries

## Development

### Testing Python
```bash
cd python
uv sync
uv run pytest
```

### Testing Rust
```bash
cd rust
cargo test
cargo clippy
cargo fmt --check
```

### Testing Go
```bash
cd go
go test ./...
go vet ./...
gofmt -l .
```

## Contributing

1. Ensure all three implementations stay behaviorally identical
2. Add workflow templates as needed for new deploy types
3. Update README when adding features
4. Test on Windows, Linux, and macOS

## License

MIT License - See [LICENSE](LICENSE) file for details.

## Warnings

- **Dockerfile**: Docker workflows require a `Dockerfile` in the repo root
- **Network**: Tool warns if remote push fails; configure locally and push manually later
- **Remotes**: All existing git remotes are removed and `origin` is reset
- **Secrets**: Must be configured in Gitea before workflows can run successfully
- **BaseURL**: Hardcoded Gitea URLs may need adjustment for your environment