# Installation & Setup

## The setup path

```mermaid
flowchart TD
    I[INSTALL] --> V[VERIFY ENVIRONMENT]
    V --> A[AUTHENTICATE GITHUB]
    A --> R[REGISTER URGITHUB]
    R --> B[CHOOSE REPOSITORY BASE]
    B --> D[DISCOVER REPOSITORIES]
    D --> S[SCAN]
    S --> L[VALIDATE]
    L --> SY[SYNC / COMMIT / PUSH]
    SY --> VF[VERIFY]
    VF --> G[GENERATE REPORT]
```

Installation ≠ registration ≠ scanning ≠ synchronization — a newly installed tool never makes uncontrolled repository changes.

## 1. Install the tools

| Tool | Windows | Linux / macOS |
|---|---|---|
| Python 3.10+ | `winget install Python.Python.3.12` | Distro package / `brew install python` |
| Git | `winget install Git.Git` | `apt install git` / `brew install git` |
| GitHub CLI | `winget install GitHub.cli` | `apt install gh` / `brew install gh` |

> **Note:** Restart your terminal after installing Git / `gh` so `PATH` updates.

## 2. Verify the environment

```bash
python --version
git --version
gh --version
gh auth status
git config --global user.name
git config --global user.email
```

A healthy environment looks like:

```text
Python       ✓
Git          ✓
Git identity ✓
GitHub CLI   ✓
GitHub auth  ✓
```

If one of these checks fails, fix it before continuing.

If the `git` identity is empty, set it before committing works:

```bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```

> Git identity is the **author identity for commits** — it is *not* your GitHub authentication credential. URGithub authenticates through the GitHub CLI session and expects the `repo` scope on the token (`gh auth status`). Never place tokens into URGithub config files manually.

## 3. Clone the repository

```bash
gh repo clone learnerforge/push-to-github
cd push-to-github
python urgithub.py --version   # or python3 urgithub.py --version
```

## 4. Run the setup wizard

```bash
# Linux / macOS
python3 urgithub.py --setup

# Windows (PowerShell / CMD)
python urgithub.py --setup
```

The wizard checks, in order:

1. Python
2. Git
3. GitHub CLI
4. GitHub authentication
5. Repository permissions
6. The selected workspace
7. Creates the URGithub directory structure
8. Registers the installation
9. Creates the initial configuration
10. Prepares URGithub for its first run

### Everything in one command (Windows)

```bash
python urgithub.py --setup-all
```

Registers (if needed), installs the scheduled tasks (UAC prompt for the shutdown task), runs the first sync and shows status.

## 5. First run

Recommended sequence for a new installation:

```bash
python urgithub.py --scan      # discover repos
python urgithub.py --repos     # list what was found
python urgithub.py --verify    # health check
python urgithub.py --sync      # synchronize
```

Open the report with `python urgithub.py --report` or find it at `<base>\urgithub\.urgithub\reports\report.html`.

The full recommended first-run procedure (12 steps):

```text
1.  Verify Python            python --version
2.  Verify Git               git --version
3.  Verify Git identity      git config --global user.name / user.email
4.  Verify GitHub CLI        gh --version
5.  Verify GitHub auth       gh auth status
6.  Register                 python urgithub.py --setup
7.  Scan                     python urgithub.py --scan
8.  Inspect repositories     python urgithub.py --repos
9.  Verify                   python urgithub.py --verify
10. Synchronize              python urgithub.py --sync
11. Inspect the report       report.html
12. Configure automation     --schedule install (Windows) or cron/systemd/launchd
```

## 6. Minimal setup

```bash
gh repo clone learnerforge/push-to-github
cd push-to-github
python3 urgithub.py --setup
python3 urgithub.py
```

That is enough to be registered, synchronized and reporting.

## Useful commands

| Command | What it does |
|---|---|
| `--setup` | One-time registration wizard |
| `--setup-all` | Register + schedule + first run + status (Windows) |
| `--startup` | Run the startup trigger — full pipeline |
| `--shutdown` | Shutdown quick-push (30 s hard timeout, never opens report) |
| `--scan` / `--sync` | Run discovery / synchronization now |
| `--repos` / `--verify` | List repositories / verify the environment |
| `--run manual` | Run the manual trigger |
| `--watch` | Start the file watcher |
| `--tray` / (no args) | Open the Control Center GUI |
| `--schedule install` | Install scheduling (Windows Task Scheduler) |
| `--forget NAME` / `--prune` | Registry cleanup |
| `--config` | Show / read / set configuration |
| `--version` / `--help` | Version / help |

Run `python urgithub.py --help` for the full command list supported by your installed version.

Next: [Configuration](configuration.md) — every config key and how to change it.