From 398a4dbee30ec0031f5bf8a610a6a79a13c238b0 Mon Sep 17 00:00:00 2001 From: Jayden Sipe Date: Fri, 11 Apr 2025 20:17:22 -0400 Subject: [PATCH] Add Git LFS section --- .../version_control_systems.rst | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/tutorials/best_practices/version_control_systems.rst b/tutorials/best_practices/version_control_systems.rst index a09ffe9da..cf7111062 100644 --- a/tutorials/best_practices/version_control_systems.rst +++ b/tutorials/best_practices/version_control_systems.rst @@ -82,3 +82,98 @@ It is better to set this option as: Creating version control metadata using the project manager or editor will automatically enforce LF line endings using the ``.gitattributes`` file. In this case, you don't need to change your Git configuration. + +Git LFS +------- + +Git LFS (Large File Storage) is a Git extension that allows you to manage large +files in your repository. It replaces large files with text pointers inside Git, +while storing the file contents on a remote server. This is useful for +managing large assets, such as textures, audio files, and 3D models, without +bloating your Git repository. + +.. note:: + + When using Git LFS you will want to ensure it is setup before you commit any files to your repository. + If you have already committed files to your repository, you will need to + remove them from the repository and re-add them after setting up Git LFS. + + It is possible to use ``git lfs migrate`` to convert existing files in your repository, but this is more in-depth and + requires a good understanding of Git. + + A common approach is setting up a new repository with Git LFS (and a proper ``.gitattributes``), then + copying the files from the old repository to the new one. This way, you + can ensure that all files are tracked by LFS from the start. + +To use Git LFS with Godot, you need to install the Git LFS extension and +configure it to track the file types you want to manage. You can do this by +running the following command in your terminal: +:: + + git lfs install + +This will create a ``.gitattributes`` file in your repository that tells Git to +use LFS for the specified file types. You can add more file types by modifying +the ``.gitattributes`` file. For example, to track all GLB files, you can do this by +running the following command in your terminal: +:: + + git lfs track "*.glb" + +When you add or modify files that are tracked by LFS, Git will automatically +store them in LFS instead of the regular Git history. You can push and pull +LFS files just like regular Git files, but keep in mind that LFS files are +stored separately from the rest of your Git history. This means that you may +need to install Git LFS on any machine that you clone the repository to in +order to access the LFS files. + +Below is an example ``.gitattributes`` file that you can use as a starting point for Git LFS. +These file types were chosen because they are commonly used, but you can modify the list to include any binary types you may have in your project. + +.. code-block:: gitignore + + # Normalize EOL for all files that Git considers text files. + * text=auto eol=lf + + # Git LFS Tracking (Assets) + + # 3D Models + *.fbx filter=lfs diff=lfs merge=lfs -text + *.gltf filter=lfs diff=lfs merge=lfs -text + *.glb filter=lfs diff=lfs merge=lfs -text + *.blend filter=lfs diff=lfs merge=lfs -text + *.obj filter=lfs diff=lfs merge=lfs -text + + # Images + *.png filter=lfs diff=lfs merge=lfs -text + *.svg filter=lfs diff=lfs merge=lfs -text + *.jpg filter=lfs diff=lfs merge=lfs -text + *.jpeg filter=lfs diff=lfs merge=lfs -text + *.gif filter=lfs diff=lfs merge=lfs -text + *.tga filter=lfs diff=lfs merge=lfs -text + *.webp filter=lfs diff=lfs merge=lfs -text + *.exr filter=lfs diff=lfs merge=lfs -text + *.hdr filter=lfs diff=lfs merge=lfs -text + *.dds filter=lfs diff=lfs merge=lfs -text + + # Audio + *.mp3 filter=lfs diff=lfs merge=lfs -text + *.wav filter=lfs diff=lfs merge=lfs -text + *.ogg filter=lfs diff=lfs merge=lfs -text + + # Font & Icon + *.ttf filter=lfs diff=lfs merge=lfs -text + *.otf filter=lfs diff=lfs merge=lfs -text + *.ico filter=lfs diff=lfs merge=lfs -text + + # Godot LFS Specific + *.scn filter=lfs diff=lfs merge=lfs -text + *.res filter=lfs diff=lfs merge=lfs -text + *.material filter=lfs diff=lfs merge=lfs -text + *.anim filter=lfs diff=lfs merge=lfs -text + *.mesh filter=lfs diff=lfs merge=lfs -text + *.lmbake filter=lfs diff=lfs merge=lfs -text + +For more information on Git LFS, check the official documentation: +https://git-lfs.github.com/ and https://docs.github.com/en/repositories/working-with-files/managing-large-files. +