From d9b00d94e79768fe0e16ffd9f3b97045e990951a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:48:15 +0000 Subject: [PATCH 1/4] Initial plan From db8b88b08810c4a4d600a8edbdd00bb771433463 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:53:32 +0000 Subject: [PATCH 2/4] Fetch and verify Git LFS assets before Hugo builds Co-authored-by: NValsan <15096090+NValsan@users.noreply.github.com> --- .devcontainer/devcontainer.json | 2 +- .github/workflows/test.yaml | 4 ++++ .github/workflows/website.yaml | 2 ++ Makefile | 16 +++++++++---- readme.md | 14 +++++++++++ scripts/verify-lfs-assets.sh | 41 +++++++++++++++++++++++++++++++++ 6 files changed, 74 insertions(+), 5 deletions(-) create mode 100755 scripts/verify-lfs-assets.sh diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index c71299b45..88b74c6ee 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -2,7 +2,7 @@ "name": "Drasi Docs Dev Container", "image": "hugomods/hugo:node-git", "remoteUser": "root", - "postCreateCommand": "cd docs && git submodule update --init --recursive", + "postCreateCommand": "git lfs install && git lfs pull && ./scripts/verify-lfs-assets.sh && git submodule update --init --recursive", "postStartCommand": "cd docs/themes/docsy && npm install && cd ../../ && hugo server --bind 0.0.0.0 --baseURL=http://localhost:1313", "portsAttributes": { "1313": { diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index f81583a39..df661ccdf 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -22,6 +22,10 @@ jobs: uses: actions/checkout@v5 with: submodules: true + lfs: true + + - name: Verify Git LFS assets + run: ./scripts/verify-lfs-assets.sh - name: Get Release ID by Tag id: get_release diff --git a/.github/workflows/website.yaml b/.github/workflows/website.yaml index 8d2986aad..4941dd06a 100644 --- a/.github/workflows/website.yaml +++ b/.github/workflows/website.yaml @@ -32,6 +32,8 @@ jobs: with: submodules: true lfs: true + - name: Verify Git LFS assets + run: ./scripts/verify-lfs-assets.sh - name: Setup Node uses: actions/setup-node@v5 with: diff --git a/Makefile b/Makefile index c575e9009..029141221 100644 --- a/Makefile +++ b/Makefile @@ -20,7 +20,7 @@ VERSION ?= latest # render uncommitted/untagged tutorial changes via a Hugo module replacement. TUTORIALS_LOCAL ?= ../learning-drasi-server -.PHONY: help update-tutorials tidy serve preview-tutorials preview-docs build +.PHONY: help update-tutorials tidy serve preview-tutorials preview-docs build lfs check-lfs help: ## Show this help. @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \ @@ -34,13 +34,21 @@ update-tutorials: ## Pin the tutorials module to VERSION (default: latest tag) a tidy: ## Tidy Hugo module requirements (go.mod / go.sum). cd $(HUGO_DIR) && hugo mod tidy -serve: ## Run the local Hugo server against the pinned module version. +lfs: ## Download the Git LFS assets (e.g. the homepage explainer video) into the working tree. + git lfs install --local + git lfs pull + ./scripts/verify-lfs-assets.sh + +check-lfs: ## Fail if any Git LFS asset is still a pointer file instead of real content. + ./scripts/verify-lfs-assets.sh + +serve: lfs ## Run the local Hugo server against the pinned module version. cd $(HUGO_DIR) && hugo server --disableFastRender -preview-tutorials: ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL). +preview-tutorials: lfs ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL). cd $(HUGO_DIR) && HUGO_MODULE_REPLACEMENTS="$(TUTORIALS_MODULE) -> $(abspath $(TUTORIALS_LOCAL))" hugo server --disableFastRender preview-docs: preview-tutorials ## Alias of preview-tutorials. -build: ## Build the static site into docs/public. +build: lfs ## Build the static site into docs/public. cd $(HUGO_DIR) && hugo diff --git a/readme.md b/readme.md index 10d0fef3a..18f68586a 100644 --- a/readme.md +++ b/readme.md @@ -27,10 +27,24 @@ Alternatively, you can follow the instructions below to setup and run a local Hu - [Hugo extended](https://gohugo.io/) - [Go](https://go.dev/) (required for Hugo modules) - [Node.js](https://nodejs.org/en/) +- [Git LFS](https://git-lfs.com/) (required for media assets such as the homepage explainer video) ### Setup Hugo and Docsy 1. Clone the [drasi-project/docs](https://github.com/drasi-project/docs) repo +1. Media assets (`*.mp4`, `*.mov`) are stored with Git LFS. Without Git LFS these files are checked out as small text pointer files and the site will render an unplayable video. From the root of the repo run: + + ``` + git lfs install + git lfs pull + ``` + + You can confirm the assets are real files (and not pointers) at any time with: + + ```make check-lfs``` + + The `make serve`, `make preview-docs` and `make build` targets run `git lfs pull` and this check automatically. + 1. The Docsy theme is configured as a submodule which needs to be pulled. From the root of the drasi-project/docs repo (where this readme is located) run: ```git submodule update --init --recursive``` diff --git a/scripts/verify-lfs-assets.sh b/scripts/verify-lfs-assets.sh new file mode 100755 index 000000000..bbb3ff94d --- /dev/null +++ b/scripts/verify-lfs-assets.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# +# Verify that every Git LFS tracked asset (for example the homepage explainer +# video in docs/assets/video) has been materialized in the working tree. +# +# When a repository is cloned without Git LFS, tracked files are left on disk as +# small text pointer files. Hugo happily copies those pointers into the +# generated site, which produces a page that references an unplayable "video". +# Running this check before Hugo makes that failure loud instead of silent. +# +# Usage: scripts/verify-lfs-assets.sh +set -euo pipefail + +cd "$(dirname "$0")/.." + +if ! command -v git >/dev/null 2>&1; then + echo "verify-lfs-assets: git is not installed." >&2 + exit 1 +fi + +if ! git lfs version >/dev/null 2>&1; then + echo "verify-lfs-assets: Git LFS is not installed." >&2 + echo "Install it from https://git-lfs.com and run 'git lfs install && git lfs pull'." >&2 + exit 1 +fi + +# 'git lfs ls-files' marks each entry with '*' when the real object is checked +# out and '-' when only the pointer file is present. +pointers="$(git lfs ls-files | awk '$2 == "-" { print $3 }')" + +if [ -n "$pointers" ]; then + echo "verify-lfs-assets: the following Git LFS assets are still pointer files:" >&2 + echo "$pointers" | sed 's/^/ - /' >&2 + echo >&2 + echo "Fetch the real content before building the site:" >&2 + echo " git lfs install" >&2 + echo " git lfs pull" >&2 + exit 1 +fi + +echo "verify-lfs-assets: all Git LFS assets are checked out." From 95e9d7d76c00388a445929c4396517f3e6a3fc32 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:54:18 +0000 Subject: [PATCH 3/4] Address review: keep devcontainer submodule cwd, handle paths with spaces Co-authored-by: NValsan <15096090+NValsan@users.noreply.github.com> --- .devcontainer/devcontainer.json | 2 +- scripts/verify-lfs-assets.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 88b74c6ee..632d69493 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -2,7 +2,7 @@ "name": "Drasi Docs Dev Container", "image": "hugomods/hugo:node-git", "remoteUser": "root", - "postCreateCommand": "git lfs install && git lfs pull && ./scripts/verify-lfs-assets.sh && git submodule update --init --recursive", + "postCreateCommand": "git lfs install && git lfs pull && ./scripts/verify-lfs-assets.sh && cd docs && git submodule update --init --recursive", "postStartCommand": "cd docs/themes/docsy && npm install && cd ../../ && hugo server --bind 0.0.0.0 --baseURL=http://localhost:1313", "portsAttributes": { "1313": { diff --git a/scripts/verify-lfs-assets.sh b/scripts/verify-lfs-assets.sh index bbb3ff94d..3e52ac35f 100755 --- a/scripts/verify-lfs-assets.sh +++ b/scripts/verify-lfs-assets.sh @@ -26,7 +26,7 @@ fi # 'git lfs ls-files' marks each entry with '*' when the real object is checked # out and '-' when only the pointer file is present. -pointers="$(git lfs ls-files | awk '$2 == "-" { print $3 }')" +pointers="$(git lfs ls-files | awk '$2 == "-" { sub(/^[^ ]+ [^ ]+ /, ""); print }')" if [ -n "$pointers" ]; then echo "verify-lfs-assets: the following Git LFS assets are still pointer files:" >&2 From 25e4da54758eea85f0004a79663107c0ae7e744c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:55:11 +0000 Subject: [PATCH 4/4] Use offline check-lfs as build prerequisite; clarify docs and guidance Co-authored-by: NValsan <15096090+NValsan@users.noreply.github.com> --- Makefile | 8 ++++---- readme.md | 4 ++-- scripts/verify-lfs-assets.sh | 5 +++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 029141221..36e8a061a 100644 --- a/Makefile +++ b/Makefile @@ -39,16 +39,16 @@ lfs: ## Download the Git LFS assets (e.g. the homepage explainer video) into the git lfs pull ./scripts/verify-lfs-assets.sh -check-lfs: ## Fail if any Git LFS asset is still a pointer file instead of real content. +check-lfs: ## Fail (with instructions to run 'make lfs') if any Git LFS asset is still a pointer file. ./scripts/verify-lfs-assets.sh -serve: lfs ## Run the local Hugo server against the pinned module version. +serve: check-lfs ## Run the local Hugo server against the pinned module version. cd $(HUGO_DIR) && hugo server --disableFastRender -preview-tutorials: lfs ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL). +preview-tutorials: check-lfs ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL). cd $(HUGO_DIR) && HUGO_MODULE_REPLACEMENTS="$(TUTORIALS_MODULE) -> $(abspath $(TUTORIALS_LOCAL))" hugo server --disableFastRender preview-docs: preview-tutorials ## Alias of preview-tutorials. -build: lfs ## Build the static site into docs/public. +build: check-lfs ## Build the static site into docs/public. cd $(HUGO_DIR) && hugo diff --git a/readme.md b/readme.md index 18f68586a..1a88470fd 100644 --- a/readme.md +++ b/readme.md @@ -39,11 +39,11 @@ Alternatively, you can follow the instructions below to setup and run a local Hu git lfs pull ``` - You can confirm the assets are real files (and not pointers) at any time with: + Or run `make lfs`, which does both and then verifies the result. You can check the assets are real files (and not pointers) at any time, without network access, with: ```make check-lfs``` - The `make serve`, `make preview-docs` and `make build` targets run `git lfs pull` and this check automatically. + The `make serve`, `make preview-tutorials`, `make preview-docs` and `make build` targets run this check first and fail with instructions if an asset is still a pointer file. 1. The Docsy theme is configured as a submodule which needs to be pulled. From the root of the drasi-project/docs repo (where this readme is located) run: diff --git a/scripts/verify-lfs-assets.sh b/scripts/verify-lfs-assets.sh index 3e52ac35f..14c30d1d0 100755 --- a/scripts/verify-lfs-assets.sh +++ b/scripts/verify-lfs-assets.sh @@ -33,8 +33,9 @@ if [ -n "$pointers" ]; then echo "$pointers" | sed 's/^/ - /' >&2 echo >&2 echo "Fetch the real content before building the site:" >&2 - echo " git lfs install" >&2 - echo " git lfs pull" >&2 + echo " make lfs" >&2 + echo "or, without make:" >&2 + echo " git lfs install && git lfs pull" >&2 exit 1 fi