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 c71299b4..88b74c6e 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 f81583a3..df661ccd 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 8d2986aa..4941dd06 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 c575e900..02914122 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 10d0fef3..18f68586 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 00000000..bbb3ff94 --- /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 88b74c6e..632d6949 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 bbb3ff94..3e52ac35 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 02914122..36e8a061 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 18f68586..1a88470f 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 3e52ac35..14c30d1d 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