# Linking Archon as a Git Submodule of AUTARCH

This guide walks through setting up Archon (the Android companion app) as a git submodule inside the AUTARCH repository, hosted on a self-hosted Gitea instance.

**Assumed URLs:**
- AUTARCH: `https://gitea.example.com/you/autarch`
- Archon: `https://gitea.example.com/you/archon`

---

## 1. Initial Setup — Create Both Repos on Gitea

### Create the repos on Gitea

Log into your Gitea instance and create two repositories:

1. Go to `https://gitea.example.com` → **+** → **New Repository**
2. Create `autarch` (do not initialize with README if you already have local files)
3. Repeat for `archon`

### Push AUTARCH

```bash
cd /path/to/autarch
git init                          # if not already a git repo
git remote add origin https://gitea.example.com/you/autarch.git
git add .
git commit -m "Initial commit"
git push -u origin main
```

### Push Archon

```bash
cd /path/to/archon
git init
git remote add origin https://gitea.example.com/you/archon.git
git add .
git commit -m "Initial commit"
git push -u origin main
```

---

## 2. Add Archon as a Submodule

From the **AUTARCH repository root**, run:

```bash
cd /path/to/autarch
git submodule add https://gitea.example.com/you/archon.git Archon
```

This does three things:
- Clones the Archon repo into `autarch/Archon/`
- Creates (or updates) `.gitmodules` in the AUTARCH root
- Stages both `.gitmodules` and the new `Archon` directory pointer

If you prefer SSH instead of HTTPS:

```bash
git submodule add git@gitea.example.com:you/archon.git Archon
```

---

## 3. Commit the Submodule Reference

After adding the submodule, two things are staged:

- `.gitmodules` — a config file mapping the submodule path to its URL
- `Archon` — not the Archon files themselves, but a **pointer** (a specific commit hash) to the Archon repo

Commit both:

```bash
git status
# On branch main
# Changes to be committed:
#   new file:   .gitmodules
#   new file:   Archon

git commit -m "Add Archon as git submodule"
git push origin main
```

AUTARCH's repo now contains a reference to a specific commit in Archon — not the Archon files directly. This is intentional: submodules are pinned to a commit, not a branch.

---

## 4. `.gitmodules` Example

After running `git submodule add`, your `.gitmodules` file will look like this:

```ini
[submodule "Archon"]
    path = Archon
    url = https://gitea.example.com/you/archon.git
```

If you want to track a specific branch (optional, see pitfalls):

```ini
[submodule "Archon"]
    path = Archon
    url = https://gitea.example.com/you/archon.git
    branch = main
```

---

## 5. Cloning AUTARCH with Archon

### Option A — Clone everything at once (recommended)

```bash
git clone --recurse-submodules https://gitea.example.com/you/autarch.git
```

This clones AUTARCH and immediately initializes and checks out Archon at the pinned commit.

### Option B — Clone AUTARCH first, pull Archon later

```bash
git clone https://gitea.example.com/you/autarch.git
cd autarch
git submodule update --init
```

`--init` is needed the first time because the submodule isn't initialized yet. After that, use `git submodule update` without `--init`.

To also pull nested submodules (if Archon ever gains its own submodules):

```bash
git submodule update --init --recursive
```

---

## 6. Updating Archon to a Newer Commit

The submodule is pinned to a specific commit. To move AUTARCH's pointer to a newer Archon commit:

```bash
# Step into the submodule
cd Archon
git checkout main
git pull origin main

# Step back out to AUTARCH
cd ..

# The submodule pointer has changed — stage and commit it
git add Archon
git commit -m "Update Archon submodule to latest"
git push origin main
```

After this, anyone who runs `git submodule update` in their AUTARCH clone will get the newer Archon commit.

---

## 7. Gitea UI — How Submodules Are Displayed

When you browse to `https://gitea.example.com/you/autarch` in the Gitea web UI, the `Archon` directory will appear in the file list with a special icon and a label like:

```
Archon @ a3f92c1
```

The `@ a3f92c1` is a clickable link that takes you directly to that commit in the `archon` repository. Gitea resolves the link automatically as long as both repos are on the same Gitea instance and the URL in `.gitmodules` matches.

If the submodule URL points to an external host (e.g., GitHub), Gitea will still show the `@ hash` label but the link will point to the external URL.

---

## 8. CI/CD — Checking Out Submodules in Gitea Actions

If you use Gitea Actions (workflow syntax is identical to GitHub Actions), the default `actions/checkout` step does **not** pull submodules. Add `submodules: true` to fix this:

```yaml
name: AUTARCH CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout AUTARCH with submodules
        uses: actions/checkout@v4
        with:
          submodules: true          # fetches Archon at the pinned commit
          # submodules: recursive   # use this if submodules have their own submodules

      - name: Build
        run: make build
```

For private submodules on the same Gitea instance, you may need to configure an SSH key or access token in the workflow secrets and set the submodule URL to use SSH.

---

## 9. Common Pitfalls

### Detached HEAD in the submodule

When you run `git submodule update`, the submodule is checked out at a specific commit — not a branch. This is called a **detached HEAD** state. If you `cd Archon` and make commits while in detached HEAD, those commits are not on any branch and can be lost.

Fix: before making changes inside the submodule, always check out a branch first:

```bash
cd Archon
git checkout main
# now make changes, commit, push
```

### Forgot to commit after updating the submodule

Running `cd Archon && git pull` updates the Archon files locally but does **not** automatically update AUTARCH's pointer to the new commit. You must come back to the AUTARCH root and commit:

```bash
cd ..
git add Archon
git commit -m "Update Archon submodule"
```

If you push AUTARCH without doing this, the pointer still points to the old Archon commit and collaborators won't get the update.

### SSH vs HTTPS

Choose one scheme and be consistent. If your team uses SSH keys for Gitea authentication, use the SSH URL in `.gitmodules`:

```ini
url = git@gitea.example.com:you/archon.git
```

If you use HTTPS with a token, use the HTTPS URL. Mixing them causes authentication failures for people whose environment only has one configured.

You can override the URL locally (without touching `.gitmodules`) using:

```bash
git config submodule.Archon.url git@gitea.example.com:you/archon.git
```

This writes to `.git/config` and is not committed, so it only affects your local clone.

### Cloning without `--recurse-submodules`

If someone clones AUTARCH normally and then tries to build, the `Archon/` directory will exist but be **empty**. They need to run:

```bash
git submodule update --init
```

Document this in your project README so contributors know to expect it.