Follow-up from review feedback on #1084 (comment), where this was explicitly deferred as out of scope for that docs PR.
Area
cli
Current limitation
glx init scaffolds eleven entity-type directories but leaves them empty. Git does not track empty directories, so none of them survive a commit — only vocabularies/ (which has content) and the two root files do.
Reproduced against main:
$ glx init archive && cd archive && git init -q . && git add . && git commit -qm init
$ git ls-files | grep -c vocabularies/ # 25
$ git ls-files | grep -cE '^(persons|events|sources)/' # 0
$ cd .. && git clone -q archive clone && find clone -type d -not -path '*/.git*'
clone
clone/vocabularies
Two consequences:
1. A documented command fails for anyone who clones the archive. The Research Cycle section added in #1084 tells readers to stage entity directories by name. On the author's own machine those directories exist, so it works; on a fresh clone it does not:
$ git add persons/ events/ citations/ sources/
fatal: pathspec 'persons/' did not match any files
$ echo $?
128
This is the exact clone-and-collaborate workflow the guide's Remote Backup and Collaboration sections encourage, so the failure lands on the collaborator rather than the author. #1084 addresses the docs side by switching that line to git add -A; this issue is about the underlying scaffold.
2. The scaffold stops being self-documenting. The point of creating eleven empty directories is to show a new user where each entity type goes. A collaborator who clones sees only vocabularies/, losing that affordance precisely when they are least familiar with the layout.
Proposed improvement
Have createMultiFileArchive (glx/init_runner.go:96) write a .gitkeep into each entity-type directory it creates, alongside the existing .gitignore and README.md. The directory list is already derived from glxlib.AllEntityTypes, so new entity types would be covered automatically.
Worth deciding during implementation:
- Removal on first use. Whether
.gitkeep should be deleted once a directory holds real entities, or left permanently. Leaving it is simpler and harmless; removing it keeps archives tidy but adds a cleanup path to every entity write.
- Naming.
.gitkeep is convention, not a Git feature — any tracked file works. It does tie a general-purpose scaffold to Git specifically, though the project is explicitly Git-native, so that seems acceptable.
.gitignore interaction. Confirm the generated .gitignore does not exclude the new files.
Context
Not a data-correctness bug, and the blast radius is limited — worth scoping before anyone picks it up. A cloned archive is still fully functional: glx validate passes on it (it reads the 25 vocabulary files and reports valid), and glx add person recreates the missing directory on demand rather than erroring. So this is about the documented Git workflow and about scaffold discoverability, not about archive integrity.
Test coverage should assert that each entity directory contains a tracked file after glx init, so the guarantee does not regress when the entity-type list changes.
Follow-up from review feedback on #1084 (comment), where this was explicitly deferred as out of scope for that docs PR.
Area
cli
Current limitation
glx initscaffolds eleven entity-type directories but leaves them empty. Git does not track empty directories, so none of them survive a commit — onlyvocabularies/(which has content) and the two root files do.Reproduced against
main:Two consequences:
1. A documented command fails for anyone who clones the archive. The Research Cycle section added in #1084 tells readers to stage entity directories by name. On the author's own machine those directories exist, so it works; on a fresh clone it does not:
This is the exact clone-and-collaborate workflow the guide's Remote Backup and Collaboration sections encourage, so the failure lands on the collaborator rather than the author. #1084 addresses the docs side by switching that line to
git add -A; this issue is about the underlying scaffold.2. The scaffold stops being self-documenting. The point of creating eleven empty directories is to show a new user where each entity type goes. A collaborator who clones sees only
vocabularies/, losing that affordance precisely when they are least familiar with the layout.Proposed improvement
Have
createMultiFileArchive(glx/init_runner.go:96) write a.gitkeepinto each entity-type directory it creates, alongside the existing.gitignoreandREADME.md. The directory list is already derived fromglxlib.AllEntityTypes, so new entity types would be covered automatically.Worth deciding during implementation:
.gitkeepshould be deleted once a directory holds real entities, or left permanently. Leaving it is simpler and harmless; removing it keeps archives tidy but adds a cleanup path to every entity write..gitkeepis convention, not a Git feature — any tracked file works. It does tie a general-purpose scaffold to Git specifically, though the project is explicitly Git-native, so that seems acceptable..gitignoreinteraction. Confirm the generated.gitignoredoes not exclude the new files.Context
Not a data-correctness bug, and the blast radius is limited — worth scoping before anyone picks it up. A cloned archive is still fully functional:
glx validatepasses on it (it reads the 25 vocabulary files and reports valid), andglx add personrecreates the missing directory on demand rather than erroring. So this is about the documented Git workflow and about scaffold discoverability, not about archive integrity.Test coverage should assert that each entity directory contains a tracked file after
glx init, so the guarantee does not regress when the entity-type list changes.