Skip to content

Git setup - procedures

Purpose

This document defines the canonical setup and maintenance procedure for contributors using a personal fork.

Authoritative governance rules live in:

This document is procedural and scoped to the contributor workflow.

Authoritative flow (phased)

PHASE 1
  ┌───────────────────────────────┐
  │ GitHub UI                     │
  │ Create personal fork          │
  │ <user>/xymon                  │
  └───────────────┬───────────────┘
                  │
PHASE 2           │ git clone
  ┌───────────────▼───────────────┐
  │ LOCAL WORKING COPY            │
  │ developer machine             │
  └───────────────┬───────────────┘
                  │
PHASE 3           │ git remote add upstream
                  │ upstream = fetch-only
                  │
PHASE 4           │ verify remotes
                  │
PHASE 5           │ baseline verification
                  │ compare against upstream
                  │
PHASE 6           │ controlled restore (if required)
                  │
PHASE 7           │ contribution workflow
                  │ see git-contribution-flow.md

Rules

  • Upstream is the single authoritative truth source.
  • All baseline verification is performed against upstream.
  • Origin (personal fork) is a writable mirror used only as a sync and PR source.
  • Upstream is fetch-only and modified only via Pull Requests.
  • Push is allowed only to the personal fork.
  • main = stable / release
  • devel = active development baseline

Phase 0 - prerequisites

  • A GitHub account
  • Git installed locally
  • A personal fork is allowed; direct upstream pushes are not

Reference:

Phase 1 - create personal fork (GitHub UI)

On GitHub:

  • Fork xymon-monitoring/xymon
  • Result: <your-github-username>/xymon

Phase 2 - clone personal fork (local)

Using gh (recommended): 

gh repo clone <your-github-username>/xymon
cd xymon

Or using git: 

git clone https://github.com/<your-github-username>/xymon.git
cd xymon

Phase 3 - declare upstream (fetch-only)

The upstream remote represents the authoritative repository and is intentionally configured as fetch-only. 

git remote add upstream https://github.com/xymon-monitoring/xymon.git
git remote set-url --push upstream DISABLED

Phase 4 - verify remotes

git remote -v

Phase 5 - baseline verification (against upstream)

Baseline verification is always performed against upstream.

This step checks your local branches directly against upstream, so you see the authoritative state instead of your fork. 

git fetch upstream
git diff main upstream/main
git diff devel upstream/devel

Expected result:

  • No output means your branch matches upstream.
  • Differences mean your branch is ahead or behind and should be aligned before you branch.

Phase 6 - controlled restore (optional)

Non-destructive attempt (from the current local branch): 

git fetch upstream
git rebase upstream/main

Destructive restore (tracked files only): 

git stash
git reset --hard upstream/main
git stash pop

Warnings:

  • Tracked changes are discarded.
  • Untracked files are preserved.
  • git clean is intentionally not used.
  • Back up anything important before running a destructive reset.

Backup options (recommended): 

git stash -u

cp -a . ../xymon-backup

Phase 7 - contribution workflow

Day-to-day development, PR flow, and cleanup are defined in:

End of procedure

This procedure is complete for the defined scope and relies on GitHub UI actions and referenced governance documents.