Git Push Authentication#

What Was Established#

Patterns for resolving Git push authentication issues and handling divergent branches when working across multiple machines.

Key Decisions#

• Multi-machine workflow: Always git pull before starting work; commit and push when done.
• Divergent branch resolution: When local and remote have diverged, use git pull --no-rebase (merge) for safety or git fetch origin && git reset --hard origin/main to discard local commits for remote-only state.

Resolving Divergent Branches#

Symptom#

hint: You have divergent branches and need to specify how to reconcile them.
fatal: Need to specify how to reconcile divergent branches.

Option 1: Merge (preserves both histories)#

git pull --no-rebase
# Or set as default:
git config pull.rebase false

Option 2: Rebase (local commits on top of remote)#

git pull --rebase
# Or set as default:
git config pull.rebase true

Option 3: Discard local, use remote only#

git fetch origin
git reset --hard origin/main

Option 4: Fast-forward only (fails if diverged)#

git pull --ff-only

Multi-Machine Workflow#

When working from multiple machines on the same repo:

Hugo Git Submodule Extraction Pattern#

What Was Established#

Hugo themes installed as Git submodules (e.g., git submodule add <url> themes/theme-name) carry their own Git history. When you want to customize the theme beyond configuration, extracting the submodule into the main repository gives you full control over theme files without managing a separate submodule repository.

The Pattern#

1. Remove the submodule registration:

   git submodule deinit themes/theme-name
   git rm themes/theme-name

2. Re-add the theme as regular files:

   git clone <theme-url> /tmp/theme-temp
   cp -r /tmp/theme-temp/* themes/theme-name/
   git add themes/theme-name/
   git commit -m "Extract theme-name from submodule into main repo"

3. Result: Theme files are now tracked directly in the main repository.

When to Use#

• You need to modify theme templates, layouts, or partials beyond what config allows
• The upstream theme is stable and you don’t need to pull updates
• You want simpler CI/CD without recursive submodule clones

When Not to Use#

• The theme receives frequent updates you want to track
• You only need CSS overrides (use assets/ or static/ instead)

Related Pages#

Git Push Authentication, Ilmarë Website, Self-Hosted CMS Options & Landscape