From: Danilo M. Date: Wed, 22 Apr 2026 11:41:59 +0000 (+0200) Subject: Chore: added WORKFLOW.md and updated git-post-receive hook X-Git-Tag: release_22042026-1342 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=b97022c6fd5351215adabfa90ef9c5c191ad8b7c;p=danix.xyz-2.git Chore: added WORKFLOW.md and updated git-post-receive hook --- diff --git a/WORKFLOW.md b/WORKFLOW.md new file mode 100644 index 0000000..f8e6fee --- /dev/null +++ b/WORKFLOW.md @@ -0,0 +1,252 @@ +# danix.xyz — Git Workflow Reference + +Two repositories, one site: + +| Local path | Remote | Purpose | +|---|---|---| +| `~/Programming/GIT/danix.xyz-hacker-theme/` | `danix_git:danix.xyz-2` | Content, config, i18n, static assets | +| `~/Programming/GIT/danix2-hugo-theme/` | `danix_git:danix2-hugo-theme` | Theme layouts, CSS, JS, shortcodes | + +The theme lives inside the content repo as a git submodule at `themes/danix-xyz-hacker/`. +That directory is a full clone of `danix2-hugo-theme` — you can push from there or from the standalone folder. + +--- + +## Working on Content + +All content work happens in `~/Programming/GIT/danix.xyz-hacker-theme/`. + +### Add a new article + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +hugo new content/en/articles/my-new-article/index.md +# write the article, add images to the same directory +git add content/en/articles/my-new-article/ +git commit -m "content: add article 'my-new-article'" +git push origin master +``` + +### Edit an existing article + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +# edit the file +git add content/en/articles/my-article/index.md +git commit -m "content: update 'my-article'" +git push origin master +``` + +### Delete an article + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +git rm -r content/en/articles/my-article/ +git commit -m "content: remove 'my-article'" +git push origin master +``` + +### Add a static asset (image, font, file) + +Files under `static/` are served at the site root. + +```bash +cp ~/Downloads/photo.jpg static/images/photo.jpg +git add static/images/photo.jpg +git commit -m "content: add photo.jpg" +git push origin master +``` + +### Update site config (hugo.toml, i18n strings) + +```bash +# edit hugo.toml or i18n/it.yaml / i18n/en.yaml +git add hugo.toml +git commit -m "config: ..." +git push origin master +``` + +--- + +## Working on the Theme + +You have two equivalent ways to edit the theme. Pick one based on context. + +--- + +### Option A — From the standalone theme folder (preferred for theme-only work) + +```bash +cd ~/Programming/GIT/danix2-hugo-theme +# edit layouts, assets, JS, CSS... +git add . +git commit -m "feat: ..." +git push origin master +``` + +Then update the submodule pointer in the content repo so the new commit is tracked: + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +git add themes/danix-xyz-hacker +git commit -m "chore: bump theme submodule" +git push origin master +``` + +--- + +### Option B — From inside the submodule (convenient when testing with real content) + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme/themes/danix-xyz-hacker +git checkout master # always do this — submodule starts in detached HEAD after update +# edit files +git add . +git commit -m "feat: ..." +git push origin master +``` + +Then bump the pointer in the parent repo: + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +git add themes/danix-xyz-hacker +git commit -m "chore: bump theme submodule" +git push origin master +``` + +--- + +### Rebuild CSS after changing templates or Tailwind classes + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +npm run build +# then commit the compiled CSS inside the theme +cd themes/danix-xyz-hacker +git add assets/css/main.min.css +git commit -m "build: recompile CSS" +git push origin master +# then bump pointer +cd .. +git add themes/danix-xyz-hacker +git commit -m "chore: bump theme submodule (CSS rebuild)" +git push origin master +``` + +--- + +## Production Deployment + +Pushing to `danix_git:danix.xyz-2` (master) triggers the `post-receive` hook on the server. + +The hook: +1. Creates a fresh Hugo site in `/tmp/danix.xyz-compile` +2. Checks out the content repo there +3. Clones the **latest tip of `danix2-hugo-theme` master** into `themes/dagreynix` +4. Runs `hugo -t dagreynix --minify` +5. Publishes to `/var/www/html` + +**Important:** The hook always clones the current tip of the theme repo — it does NOT use the submodule pointer. This means: + +- Pushing a theme change to `danix_git:danix2-hugo-theme` is enough for production to pick it up on the next content deploy. +- You do NOT need to bump the submodule pointer to deploy theme changes. The pointer is for local tracking only. +- If you want to deploy a theme change immediately without a content change, make any trivial commit in the content repo and push it. + +--- + +## Edge Cases + +### I edited the theme from Option B but forgot `git checkout master` first + +You committed to a detached HEAD — the commit exists but is not on any branch. + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme/themes/danix-xyz-hacker +git log --oneline | head -5 # note the commit SHA, e.g. abc1234 +git checkout master +git cherry-pick abc1234 # apply the detached commit onto master +git push origin master +``` + +Then bump the pointer as usual. + +--- + +### I forgot to bump the submodule pointer after pushing theme changes + +No problem. Do it now: + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +git submodule update --remote themes/danix-xyz-hacker # fetch latest theme commit +git add themes/danix-xyz-hacker +git commit -m "chore: bump theme submodule" +git push origin master +``` + +--- + +### The submodule is out of sync after pulling the content repo on another machine + +```bash +cd ~/Programming/GIT/danix.xyz-hacker-theme +git pull origin master +git submodule update --init --recursive +``` + +--- + +### Fresh clone on a new machine + +```bash +git clone --recurse-submodules danix_git:danix.xyz-2 danix.xyz-hacker-theme +cd danix.xyz-hacker-theme +npm install # restore Tailwind build pipeline +``` + +If you forgot `--recurse-submodules`: + +```bash +git submodule update --init --recursive +``` + +--- + +### I want to pin production to a specific theme version (not latest tip) + +This requires changing the hook on the server. The current hook always clones master tip, so there is no pinning without modifying `git-post-receive` on the server to use `git clone --branch ` or `git checkout ` after cloning. + +For now, treat `danix2-hugo-theme` master as the production branch — don't push broken theme commits there. + +--- + +### I want to check what theme commit is currently deployed + +```bash +ssh danix_git "git -C ~/repositories/danix2-hugo-theme.git log --oneline | head -1" +``` + +--- + +## Quick Reference + +``` +# content change → deploy +cd ~/Programming/GIT/danix.xyz-hacker-theme +git add && git commit -m "..." && git push origin master + +# theme change → deploy +cd ~/Programming/GIT/danix2-hugo-theme # or themes/danix-xyz-hacker/ +git checkout master +git add && git commit -m "..." && git push origin master +# then bump pointer: +cd ~/Programming/GIT/danix.xyz-hacker-theme +git add themes/danix-xyz-hacker && git commit -m "chore: bump theme" && git push origin master + +# check submodule status +git submodule status + +# update submodule to latest theme +git submodule update --remote themes/danix-xyz-hacker +``` diff --git a/git-post-receive b/git-post-receive index c8062a1..b2c61be 100644 --- a/git-post-receive +++ b/git-post-receive @@ -3,7 +3,7 @@ # theme repository THEME_REPO=$HOME/repositories/danix2-hugo-theme.git # repository logical name -REPO="danix.xyz" +REPO="danix.xyz-2" # Directory where to work on our site TARGET_DIR=/tmp/danix.xyz-compile GIT_DIR=$HOME/repositories/${REPO}.git @@ -67,8 +67,8 @@ do git --git-dir=$GIT_DIR --work-tree=. -C "$TARGET_DIR" checkout -f log "Cloning theme from $THEME_REPO" - git clone $THEME_REPO ${TARGET_DIR}/themes/dagreynix - log "Theme cloned at commit: $(git -C ${TARGET_DIR}/themes/dagreynix rev-parse --short HEAD)" + git clone $THEME_REPO ${TARGET_DIR}/themes/danix-xyz-hacker + log "Theme cloned at commit: $(git -C ${TARGET_DIR}/themes/danix-xyz-hacker rev-parse --short HEAD)" log "Clearing $PUBLIC_WWW" rm -rf $PUBLIC_WWW/* @@ -77,7 +77,7 @@ do git tag release_$NOW $BRANCH log "Running Hugo build..." - /usr/local/bin/hugo -s $TARGET_DIR -d $PUBLIC_WWW -b "${SITE_DOMAIN}" -t "dagreynix" --noTimes --minify + /usr/local/bin/hugo -s $TARGET_DIR -d $PUBLIC_WWW -b "${SITE_DOMAIN}" -t "danix-xyz-hacker" --noTimes --minify log "Hugo build complete." log "========================================"