godot

*.import and *.tres files in godotengine


I'm new to godotengine and want to make a project and upload it on github. I just get confused that those *.import files which are created automatically on adding a new assets and *.tres files which we make to save our tileset maps or something else are needed to be uploaded? thanks.


Solution

  • Version Control consideration for Godot projects

    In this answer I go over the different kinds of files that Godot generates automatically that you might wonder if exclude or not exclude from version control.

    *Note: All Godot text files use LF (\n) for new line (i.e. Unix style line endings), and are UTF-8, regardless of platform. Set your .editorconfig and .gitattributes accordingly. The rest of the answer is about what to exclude (or not to exclude) in .gitignore.

    A .gitignore example file is provided at the end.


    project.godot

    tl;dr; DO NOT EXCLUDE project.godot from version control. This is your project file. It is necesary.

    It is text-based (basically INI files) and fairly small, so it plays well with version control.

    Note: In Godot 2.x, the file was engine.cfg instead.


    override.cfg

    tl;dr; Exclude override.cfg from version control.

    This file is used to override project settings. Often used for testing or troubleshooting. You might want to exclude it to allow to have custom settings per machine.


    *.tres files

    tl;dr; DO NOT EXCLUDE *.tres files from version control.

    They are text-based (basically INI files) and fairly small, so they play well with version control.

    The *.tres files can - and often exist - unassociated with an imported resource. If an *.tres file is missing… You are in trouble.

    and *.tres files which we make to save our tileset

    It is not mandatory to use the "save" option on your TileSet. If you add a TileMap, give it a new TileSet and save the Scene, Godot saves the TileSet as part of the scene file.

    Saving it to a *.tres file will allow you reuse it (on different TileMaps, or on different scenes). And it also means you can edit it on its own (which is good for version control).

    Once you saved it to a *.tres file, that file IS your TileSet, it describes what sections of what textures is what tile. As I said, if the file is missing, you are in trouble. You would have to do that again.

    Where is each tile placed is part of the TileMap data, part of the scene.


    *.import files

    tl;dr; DO NOT EXCLUDE *.import files from version control, but not the .import (Godot 3)/.godot (Godot 4) folder.

    They are text-based (basically INI files) and fairly small, so they play well with version control.

    There a partial answer here: Godot: what are .import files, and should you commit them to git?. I'll elaborate further.

    The *.import files have the import settings (what you set in the Import panel). Know that they must exist along side the imported file. If an .import file is missing, Godot will re-import the associated resource with the default settings. This is not good if you changed said settings. And then Godot recreates the *.import file.

    The *.import files reference files in the .import folder (.godot/imported in Godot 4.x). But you can exclude that folder. The folder has a read only cache, with duplicates of the resources in a binary format convenient for Godot (and thus not good for version control). With the original file and the *.import file, Godot reconstructs it.

    See Files generated on the import process:

    Importing will add an extra .import file, containing the import configuration. Make sure to commit these to your version control system!

    Keep the *.import files along side their respective resources.


    *.translation files

    tl;dr; Exclude *.translation files from version control.

    They are binary files, so they DON'T play well with version control.

    Godot gererates *.translation files from imported *.csv files with text translations. As long as you have the *.csv and corresponding *.import files, Godot generates the *.translation, so you don't need them in version control. Futhermore, they are a binary format, so they don't play well in version control anyway.


    export_presets.cfg

    tl;dr; You might exclude export_presets.cfg from version control.

    It is text-based (basically INI files) and fairly small, but might contain sensitive information.

    Godot generates this file when you use the "Export..." option from the "Project" menu.

    They have the export configuration for the project. Usually only one machine will have the responsability to export the project, and the file might have sensitive data (keys for encrypting and signing the build). So you might opt to exclude the file from version control.

    Notes:


    ~* files

    tl;dr; Exclude ~* files from version control.

    They are temporary binary files.

    Godot will write temporary files with the prefix ~ for hot reloading GDExtensions. These files are copies of the binaries of the GDExtension that Godot will load instead of the original. So the original is not in use, which allows the user to replace it with a new build, and allows Godot to detect that the user did so.

    Note: This feature is available since Godot 4.2.


    *.tmp files

    tl;dr; Exclude *.tmp files from version control.

    They are temporary files.

    Godot will write *.tmp files as intermediate step when updating files. If these files linger around it means that Godot failed to write the final file it was trying to update.

    While they might be useful to recover the data that Godot was trying to write to the final file, you don't want them in your repository.


    .mono and data_* folders

    tl;dr; Exclude .mono and data_* folders from version control.

    They contain .NET binaries, et.al.

    The folders .mono and data_* (where * is the project name) contain .NET/Mono builds.

    Godot has switched from Mono to .NET, although:

    1. The builds still have "mono" in the name, and Godot still uses a .mono folder for .NET builds.
    2. Mono is still supported (this might change in the near future).

    mono_crash.*.json and mono_crash.*.blob files

    tl;dr; Exclude mono_crash.*.json and mono_crash.*.blob files from version control. Also exclude the .mono folder.

    They are crash reports.

    Mono (not .NET) will create crash memory dumps with the name pattern mono_crash.*.blob and associated metadata (memory layaout information) with the name pattern mono_crash.*.json.


    android folder

    tl;dr; Exclude the /android folder from version control.

    Contains an Android project.

    The /android this folder contains the Android build template. Which only the machine responsible for exporting the project needs. You get it by using the option "Install Android Build Templates..." from the "Project" menu.


    *.uid files

    tl;dr; DO NOT EXCLUDE *.uid files from version control.

    They are text-based, and contain only the uid path, so they play well with version control.

    In Godot 4.4 (in development at the time of writing) we get an *.uid file for each script. They have an unique identifier for the script.

    Godot developers opted to add the unique identifier this way because scripts are plain text written by the user, and thus lack a good way to add generated metadata to them. The developers might replace *.uid files with full metadata files fot Godot 5, but we are not there yet.

    Godot generates the uids based on the script and path in way that is consistent across machines. However...

    Godot will use the uids to reference the scripts. This means that Godot does not need to update the paths every time you move the script. But, if the *.uid files are not in version control, a new clone of the repository will result in Godot regenerating them. Which, in the case of a moved script, will result in a new uid that does not match the original.

    Keep the *.uid files along side their respective scripts.


    Others

    Note: If you want to exclude a folder from both Godot and git, add a .gdignore file to the folder to exclude it from Godot (the .gdignore is left emtpy), and add the folder to .gitignore to exclude it form version control.


    Example

    This is an example of a .gitignore file for Godot 4.2+:

    # Godot
    /.godot/
    /android/
    *.translation
    *.tmp
    ~*
    
    # Mono
    /.mono/
    /data_*/
    mono_crash.*.json
    mono_crash.*.blob
    
    # Visual Studio
    /.vs/
    
    # Visual Studio Code
    /.vscode/