Skip to content

Commit ad8d363

Browse files
committed
Add Git LFS section
1 parent 8c18714 commit ad8d363

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed

tutorials/best_practices/version_control_systems.rst

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,95 @@ It is better to set this option as:
8282
Creating version control metadata using the project manager or editor will
8383
automatically enforce LF line endings using the ``.gitattributes`` file.
8484
In this case, you don't need to change your Git configuration.
85+
86+
Git LFS
87+
-------
88+
89+
Git LFS (Large File Storage) is a Git extension that allows you to manage large
90+
files in your repository. It replaces large files with text pointers inside Git,
91+
while storing the file contents on a remote server. This is useful for
92+
managing large assets, such as textures, audio files, and 3D models, without
93+
bloating your Git repository.
94+
95+
.. note::
96+
97+
When using Git LFS you will want to ensure it is setup before you commit any files to your repository.
98+
If you have already committed files to your repository, you will need to
99+
remove them from the repository and re-add them after setting up Git LFS.
100+
101+
It is possible to use ``git lfs migrate`` to convert existing files in your repository, but this is more in-depth and
102+
requires a good understanding of Git.
103+
104+
A common approach is setting up a new repository with Git LFS (and a proper ``.gitattributes``), then
105+
copying the files from the old repository to the new one. This way, you
106+
can ensure that all files are tracked by LFS from the start.
107+
108+
To use Git LFS with Godot, you need to install the Git LFS extension and
109+
configure it to track the file types you want to manage. You can do this by
110+
running the following command in your terminal:
111+
::
112+
git lfs install
113+
114+
This will create a ``.gitattributes`` file in your repository that tells Git to
115+
use LFS for the specified file types. You can add more file types by modifying
116+
the ``.gitattributes`` file. For example, to track all GLB files, you can do this by
117+
running the following command in your terminal:
118+
::
119+
git lfs track "*.glb"
120+
121+
When you add or modify files that are tracked by LFS, Git will automatically
122+
store them in LFS instead of the regular Git history. You can push and pull
123+
LFS files just like regular Git files, but keep in mind that LFS files are
124+
stored separately from the rest of your Git history. This means that you may
125+
need to install Git LFS on any machine that you clone the repository to in
126+
order to access the LFS files.
127+
128+
Here is an example ``.gitattributes`` file that you can use as a template to get started with Git LFS:
129+
130+
.. code-block:: gitignore
131+
132+
# Normalize EOL for all files that Git considers text files.
133+
* text=auto eol=lf
134+
135+
# Git LFS Tracking (Assets)
136+
137+
# 3D Models
138+
*.fbx filter=lfs diff=lfs merge=lfs -text
139+
*.gltf filter=lfs diff=lfs merge=lfs -text
140+
*.glb filter=lfs diff=lfs merge=lfs -text
141+
*.blend filter=lfs diff=lfs merge=lfs -text
142+
*.obj filter=lfs diff=lfs merge=lfs -text
143+
144+
# Images
145+
*.png filter=lfs diff=lfs merge=lfs -text
146+
*.svg filter=lfs diff=lfs merge=lfs -text
147+
*.jpg filter=lfs diff=lfs merge=lfs -text
148+
*.jpeg filter=lfs diff=lfs merge=lfs -text
149+
*.gif filter=lfs diff=lfs merge=lfs -text
150+
*.tga filter=lfs diff=lfs merge=lfs -text
151+
*.webp filter=lfs diff=lfs merge=lfs -text
152+
*.exr filter=lfs diff=lfs merge=lfs -text
153+
*.hdr filter=lfs diff=lfs merge=lfs -text
154+
*.dds filter=lfs diff=lfs merge=lfs -text
155+
156+
# Audio
157+
*.mp3 filter=lfs diff=lfs merge=lfs -text
158+
*.wav filter=lfs diff=lfs merge=lfs -text
159+
*.ogg filter=lfs diff=lfs merge=lfs -text
160+
161+
# Font & Icon
162+
*.ttf filter=lfs diff=lfs merge=lfs -text
163+
*.otf filter=lfs diff=lfs merge=lfs -text
164+
*.ico filter=lfs diff=lfs merge=lfs -text
165+
166+
# Godot LFS Specific
167+
*.scn filter=lfs diff=lfs merge=lfs -text
168+
*.res filter=lfs diff=lfs merge=lfs -text
169+
*.material filter=lfs diff=lfs merge=lfs -text
170+
*.anim filter=lfs diff=lfs merge=lfs -text
171+
*.mesh filter=lfs diff=lfs merge=lfs -text
172+
*.lmbake filter=lfs diff=lfs merge=lfs -text
173+
174+
For more information on Git LFS, check the official documentation:
175+
https://git-lfs.github.com/ and https://docs.github.com/en/repositories/working-with-files/managing-large-files.
176+

0 commit comments

Comments
 (0)