Put your project in Git
A project made from the starter ZIP works without Git, and you can keep it that way. Git becomes worth learning when you want a history of your changes to go back to, a copy on GitHub, or CI that checks every push. This page makes your project a Git repository with the engine as a submodule: a pointer to one release of Labrador’s own repository, rather than a copy of its files. That is the shape Start your own project makes, so from then on every page written for that shape applies, Move your engine pin among them.
If all you want is a history and a copy on GitHub, there is a shorter way: Put your project on GitHub commits the engine as the plain files the ZIP gave you, and moving to a newer Labrador then stays the starter ZIP’s way. A submodule is worth the extra steps when you want to move between releases with Git, one command at a time.
Nothing here changes your game. The engine folder the ZIP gave you is moved aside, not deleted, and the same release of the engine is downloaded in its place. Only when the project builds and its tests pass with the downloaded engine do you delete the old one, so a failed download or a wrong release costs nothing: Putting it back restores the project as the ZIP made it. It takes about ten minutes, and downloads about 20 MB.
Before you start, close Visual Studio, your game, and any File Explorer window that shows the project. A program that has a file open in the engine folder stops step 4. The project should build and pass its tests as it is, as in Get the starter project, so that you know a failure later is this page’s.
-
Install Git and tell it who you are, if you have not already: steps 2 and 5 of Install the tools. Install Git before you open the prompt you use for the next steps, then check it with:
Terminal window git --versionIt prints a version, such as
git version 2.52.0.windows.1. If it says'git' is not recognized, Git is not installed, or was installed after this prompt opened: open a new x64 Native Tools Command Prompt and try again. -
Go to your project and see which release its engine is. In the x64 Native Tools Command Prompt:
Terminal window cd /d C:\dev\mygametype README.txtAmong the lines it prints is this one, naming the release:
Output Labrador version: v0.2.0Yours may name another, such as
v0.3.0. Write it down: step 6 uses it. If the line saysa development build, not a release, your ZIP was not a release’s, and there is no tag to choose in step 6; use a release’s ZIP from Get the starter project instead. -
Make the folder a repository:
Terminal window git initGit answers
Initialized empty Git repository in C:/dev/mygame/.git/. It may also print a few lines startinghint:about the name of the first branch, which you can ignore. The.gitfolder it makes is hidden, and holds the history. If it saysReinitialized existing Git repository, the project was already a repository, perhaps from Put your project on GitHub; carry on, and read the note in step 5. -
Move the ZIP’s engine aside. This moves
external\labradorout of the project, to a folder beside it namedlabrador-from-zip, which isC:\dev\labrador-from-zipforC:\dev\mygame. It moves nothing if you are in the wrong folder, or if that folder is already there:Terminal window if not exist external\labrador\CMakeLists.txt (echo There is no engine in external\labrador here. Nothing was moved.) else if exist ..\labrador-from-zip (echo There is already a folder ..\labrador-from-zip. Nothing was moved.) else (move external\labrador ..\labrador-from-zip)It prints:
Output 1 dir(s) moved.externalis now an empty folder. What the other messages mean:There is no engine in external\labrador here.: the prompt is not in your project’s folder, or the engine has already been moved. Runcd /d C:\dev\mygameanddir external. Ifexternalis empty andC:\dev\labrador-from-zipexists, the move has already been made: go on to step 5.There is already a folder ..\labrador-from-zip.: it is left from an earlier try, or made by hand. Look in it withdir ..\labrador-from-zip. If it holds an engine (the list hasCMakeLists.txt,engineandsamples) and yourexternal\labradoris still there, you do not need the old one. If it is empty (the list ends0 File(s)and shows only.and..) or holds no engine, nothing in it is the project’s. Either way, delete it withrmdir /s /q ..\labrador-from-zip, and run the box again.Access is denied.and0 dir(s) moved.: a program has a file in the engine open, most often Visual Studio, the game, another command prompt whose folder is inside it, or File Explorer. Close it and run the box again. Nothing was moved.
-
Download the engine’s repository into the place the old one was:
Terminal window git submodule add https://github.com/matt439/Labrador.git external/labradorIt downloads about 20 MB: that took 3 seconds on a fast connection, and at 1 MB a second takes about 20. It prints:
Output Cloning into 'C:/dev/mygame/external/labrador'...warning: in the working copy of '.gitmodules', LF will be replaced by CRLF the next time Git touches itand then the prompt. The warning is harmless: it says only that Git stores the file’s line ends its own way. The new file
.gitmodulesrecords where the engine comes from.What a failure means:
-
fatal: unable to access 'https://github.com/matt439/Labrador.git/': Could not resolve host: github.com, thenfatal: clone of ... failed: the machine could not reach GitHub, because it is off the internet or something between it and GitHub stopped the download. Nothing was downloaded. Check the connection and run the box again; Git starts over. If you want to stop for now, put the project back. -
fatal: 'external/labrador' already exists and is not a valid git repo: the old engine is still in the project, because step 4 did not move it. Do step 4, then this one. -
fatal: 'external/labrador' already exists in the index: the project was already a repository with the engine committed as plain files, as Put your project on GitHub commits it. Tell Git to stop tracking those files, which leaves your other files and your history as they are, then run the box again:Terminal window git rm -r --cached -q external/labradorIt prints nothing. Step 9’s commit then records the engine’s change from plain files to a submodule, as that step shows.
-
fatal: please make sure that the .gitmodules file is in the working tree: an earlier try got as far as step 9’s commit and was put back without the last part of Putting it back. Nothing was downloaded. Run that section’s line, finish as its After step 9 says, and start again where it tells you.
-
-
Choose the same release. Paste this line, but before you press Enter, change
v0.2.0to the version from step 2, as Typing the commands shows:Terminal window git -C external/labrador checkout v0.2.0It prints a long note and ends with the release’s commit:
Output Note: switching to 'v0.2.0'.You are in 'detached HEAD' state. You can look around, make experimentalchanges and commit them, and you can discard any commits you make in thisstate without impacting any branches by switching back to a branch.If you want to create a new branch to retain commits you create, you maydo so (now or later) by using -c with the switch command. Example:git switch -c <new-branch-name>Or undo this operation with:git switch -Turn off this advice by setting config variable advice.detachedHead to falseHEAD is now at 1e60fb2 Prepare v0.2.0Detached HEAD is expected: the engine folder is now fixed at that release, which is what you want, and you will not make commits inside it. Start your own project, step 2, says more about it.
If it says
error: pathspec 'v0.2' did not match any file(s) known to git, there is no release of that name: herev0.2is missing its last.0. Check the spelling against step 2 and run the line again. Nothing was changed. -
Check that Git leaves Visual Studio’s folder out. The project’s
.gitignorenames the folders Git does not record:Terminal window type .gitignoreOutput out/.vs/out/is the build folder, and.vs/is the folder Visual Studio makes when it opens the project: about 60 MB of its own databases, which change every time it opens and which it keeps open while it runs. A starter made before 31 October 2026 lists onlyout/; if yours does, add the second line, then check again:Terminal window echo .vs/>> .gitignoreIt prints nothing. Without that line, a
git add .with Visual Studio open stops witherror: open(".vs/CMake Overview"): Permission deniedandfatal: adding files failed, and with it closed records the databases. -
Build and test with the downloaded engine:
Terminal window cmake --build --preset x64-debugctest --preset x64-debugThe engine’s files are new copies, so the build runs CMake again and compiles the engine before your game: 100 steps, about 10 seconds on a fast desktop. It starts with
[0/1] Re-running CMake...and some vcpkg lines, ends with[99/100] Linking CXX executable game\MyGame.exe, and the tests end:Output 100% tests passed, 0 tests failed out of 2If the build fails where it passed before step 4, the release you chose in step 6 is not the engine the ZIP held: check it against step 2 and run step 6 again with the right one. If you cannot find why, put the project back. Read a build error shows how to find the line that matters.
-
Make the first commit, the project’s first saved version in its history:
Terminal window git add .git commit -m "Start from Labrador's starter project"git add .may print warnings thatLF will be replaced by CRLFfor some files, which are harmless.git committhen prints onecreate modeline for each file it recorded, after a first line like this one:Output [master (root-commit) bb9b5d9] Start from Labrador's starter project23 files changed, 1449 insertions(+)Your seven characters after
root-commitdiffer, and so can the counts; the line may saymaininstead ofmaster. The engine is one of those files, the pointer to its commit, rather than its thousand files.outand.vsare not among them. If Git saysAuthor identity unknown, do Tell Git who you are and run thegit commitline again.In a project that was already a repository, with the engine committed as plain files, the first line has no
(root-commit), and the commit records the engine’s change from those files to a submodule:Output [main 31dfe51] Start from Labrador's starter project887 files changed, 5 insertions(+), 250151 deletions(-)create mode 100644 .gitmodulescreate mode 160000 external/labradordelete mode 100644 external/labrador/.gitattributesand a
delete modeline for each of the engine’s other files, 884 in all. Those are the plain copies the submodule replaces: the engine is still inexternal\labrador, and nothing of your game is deleted. -
Delete the engine you moved aside. The project no longer needs it:
Terminal window rmdir /s /q ..\labrador-from-zipIt deletes the folder and everything in it without asking, and prints nothing. If it prints
The system cannot find the file specified., there is nothing to delete.
Your project is a Git repository now. Check it:
git statusgit submodule statusOn branch masternothing to commit, working tree clean 1e60fb26c4fdfcd1582c35c6862d8a06cc4c9b09 external/labrador (v0.2.0)with your branch’s name and your release. The long number is the engine’s commit, and the release in brackets is the tag you chose.
Putting it back
Section titled “Putting it back”Until step 10, the engine the ZIP gave you is in C:\dev\labrador-from-zip. If a step fails and
you want to stop, or to start this page again later, this one line puts the engine back as the
ZIP made it, in your project’s folder. It deletes the downloaded engine, if there is one, moves
the old one back, deletes .gitmodules and the downloaded history in .git\modules, and tells
Git to forget what it was about to record. It changes nothing if the old engine is not there:
if not exist ..\labrador-from-zip\CMakeLists.txt (echo There is no engine in ..\labrador-from-zip. Nothing was changed.) else (rmdir /s /q external\labrador 2>nul & move ..\labrador-from-zip external\labrador & del .gitmodules 2>nul & rmdir /s /q .git\modules\external 2>nul & git reset -q)It prints 1 dir(s) moved..
Before step 9, that is all. git status then lists your project’s files as untracked, as
after step 3; for a project that was already a repository, it prints
nothing to commit, working tree clean, as before you started. The build works as it did
before step 4. To leave Git altogether, also delete its folder with rmdir /s /q .git, which
deletes the history with it; do that only in a project you made a repository of on this page.
After step 9, the commit still records the submodule, and git status says so:
On branch masterChanges not staged for commit: (use "git add/rm <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) deleted: .gitmodules
no changes added to commit (use "git add" and/or "git commit -a")Finish with one of these two, or a later try stops at step 5 with
fatal: please make sure that the .gitmodules file is in the working tree:
-
In a project you made a repository of in step 3, delete the repository, and step 9’s commit with it:
Terminal window rmdir /s /q .gitIt prints nothing, and
git statusthen saysfatal: not a git repository: the project is as the ZIP made it, with.vs/in.gitignoreif step 7 added it. To try again, start at step 3. -
In a project that was already a repository, record the engine as plain files again, in a new commit that keeps your history:
Terminal window git rm -r --cached -q external/labradorgit add .git commit -m "Put the engine back as plain files"The commit prints
886 files changed, 250151 insertions(+), 4 deletions(-), thendelete modelines for.gitmodulesandexternal/labrador, and acreate modeline for each of the engine’s files.git statusis then clean. To try again, start at step 4; step 5 then saysalready exists in the index, and its answer there works as before.
If it says There is no engine in ..\labrador-from-zip, the old engine is not there: either
step 4 did not move it, and external\labrador still holds it, or step 10 has deleted it, and
the downloaded engine is the only one. Do not delete external\labrador then.
Where to go next
Section titled “Where to go next”- Save and undo changes with Git is what you do with the repository every day: see what changed, record it, undo a broken edit and go back to an earlier version.
- Put your project on GitHub makes the account and an empty
repository, connects your project to it and pushes, with what each failure means. Its step 2
is done already: skip to its step 3. Anyone who clones it, you included on another machine,
needs
--recurse-submodules, as Start your own project explains, because the engine is a submodule. - From here, move to a newer Labrador with Move your engine pin, not with the starter ZIP.
What was checked
Section titled “What was checked”On 31 October 2026, with Git for Windows 2.52.0, the steps were run as worded in a project
extracted with Windows’ tar from a starter ZIP that starter_zip.py made of a clean clone at
v0.2.0, at C:\dev\g11-author\s2g\mygame, and built and tested there first. No release with
a starter ZIP existed yet, so this stood in for one; its README.txt named v0.2.0 and its
.gitignore held only out/, so step 7’s added line was needed. The quoted output is from that
run, with the folder changed to C:\dev\mygame. Step 4 moved the folder; step 5 downloaded the
engine from GitHub in 3.3 seconds into a .git\modules folder of 19 MB; step 6 checked out
v0.2.0; step 8’s build ran 100 steps in 9 seconds and both tests passed; step 9 recorded 23
files; step 10 deleted the old engine, and git status and git submodule status printed what
is quoted. In a starter made from this tree, whose .gitignore already lists .vs/, steps 3 to
10 with the engine checked out at the public master, there being no release of it, recorded 24
files and left git status clean. The same steps on a project made at v0.1.0 by that release’s own
assemble.py, at C:\dev\g11-author\pin\mygame, checked out v0.1.0 and built.
With that project open in Visual Studio 2026, its .vs folder held 60 MB, git status stayed
clean, and a git add of .vs with its files not ignored stopped with the Permission denied
message in step 7. Each failure was made on purpose in other projects from the same ZIP:
Access is denied by holding CHANGES.md open in another process during step 4; the guard’s
messages with the prompt in the wrong place and with ..\labrador-from-zip already there;
Could not resolve host with the address’s github.com changed to github.con, after which the
right address downloaded without any cleaning up; already exists and is not a valid git repo
with step 4 left out; already exists in the index, and the git rm --cached line, in a project
first committed as plain files as Put your project on GitHub does, whose commit after step 6
recorded the submodule and 884 deleted engine files; and pathspec 'v0.2'. The line under
Putting it back was run after the failed download, after a successful download
and checkout, and in the project committed as plain files; each time the engine came back and
git status was as the section says, and after the last the project configured, built and passed
both tests.
Its two messages were seen too. The hint: lines of step 3 were not seen: this machine’s Git
names the first branch itself.
A second person then followed the page as worded, in fresh projects from the same ZIP, and every
box and failure gave the output quoted, except three places the page has since been corrected
for: the line under Putting it back, run after step 9’s commit, left .gitmodules listed as
deleted, and a second try then stopped at step 5 on .gitmodules; step 5’s note promised a
git status in step 9, where a project committed as plain files instead sees the commit quoted
there; and an empty ..\labrador-from-zip had no advice. The corrections were run the same day
in fresh projects at C:\dev\g11-fixer: an empty ..\labrador-from-zip gave step 4’s second
message and 0 File(s) in dir, and the box worked after rmdir; in a project made a
repository on this page, the line after step 9 printed the git status quoted, a second try
stopped at step 5 with the .gitmodules error, and the line followed by rmdir /s /q .git put
the project back so that steps 3 to 10 then ran cleanly to the status quoted above; in a project
first committed as plain files, step 9’s commit printed what step 9 quotes, and after the line
the three lines recording the engine as plain files printed the counts quoted, left git status
clean, and let steps 4 and 5 run again with already exists in the index and its answer;
put back once more, the project configured, built and passed both tests.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.