autarch/autarch_companion/gitea_module.md

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

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

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:

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:

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:

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:

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

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

[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)

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

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):

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:

# 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:

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:

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:

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:

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:

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:

git submodule update --init

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