Git plugin v1 - lalomartins/godot-git-plugin GitHub Wiki

Features

Git plugin provides the Godot editor with the backend hooks to:

  • View diffs for files already committed in Git
  • Stage files to commit
  • Commit files to Git

Prerequisites

$ git config --global user.name "your name"
$ git config --global user.email [email protected]

Installation

You can install this plugin from the Godot Asset Library here or you can use the manual process mentioned below.

  1. Download the latest v1.x release.

  2. Windows users should ensure they have the VC 2019 redistributable runtime installed.

  3. MacOS users may need to perform a one-time workaround as described here to be able to load the plugin in Godot.

  4. Extract the .zip contents under the res://addons/ directory of your Godot project. Please ensure that the plugin does not get extracted inside res://addons/godot-git-plugin-vx.x.x/godot-git-plugin, the plugin requires itself to be kept at res://addons/godot-git-plugin.

  5. Open your project using the Godot Project manager.

Usage

When the project loads up, you are greeted with the Godot editor that you know and love. However, you now have the option to set up a VCS plugin from the editor.

  1. Open Project > Version Control. Select Set Up Version Control.

  1. A popup will ask you which VCS plugin would you like to use. In our case we are using Git, so select GitAPI from the drop-down menu. Then click Initialize and close the popup. The .gitignore and .gitattributes files that this plugin will automatically create are picked up from here.

If you are not able to see a GitAPI option then check if you copied the correct folder to res://addons/ according to the installation instructions.

  1. Open the Commit tab that you may see alongside the Inspector and Node tabs. At first, you will see that every file in the project folder is counted as a new addition to the repository since we have started from a VCS-less project. If you already have Git running on your project then the plugin should be able to just use your existing repository.

  • The .gitignore and .gitattributes are Git specific configuration files and creating them in the project folder is handled by the Git plugin, without any consultation from the Godot editor. You can edit them afterwards for a customized Git experience. If you are using an existing Git repository then the Git plugin will use your existing Git configuration files by default.

  • To manually enforce a change in the project files, we have also provided a Refresh button that detects changes manually. If your file change is not showing up in the staging area, then consider checking .gitignore to see if your file has been ignored by Git in the first place.

  1. Stage the files that you would like to commit to in the next version by checking the required files and clicking Stage Selected. If you are working in a new Git repository then Stage All will stage all the files present in the staging area.

  2. After staging, the staging area will acknowledge the file changes with a green tick.

Alternatively, if you would like to not stage default_env.tres (for example) then you should be able to just uncheck default_env.tres and press Stage Selected. Thus, you may get a view similar to the one below.

This way, default_env.tres will not get committed in the next version.

  1. Add a nice commit message and click Commit Changes.

You may also notice that the number of staged files is also reported. This is for your utility where you may like to confirm if you are committing the correct project files.

  1. After clicking Commit Changes you can start working on the next version of your project!

  2. When you are done, you can choose to shut down the VCS API with the selected plugin by selecting Project > Version Control > Shut Down Version Control. This will take away the VCS integration-related GUI and return you to the normal state of the editor without the VCS integration.

Useful features

Stage Status

At every Git index change, you are notified of the number of files in the stage, the number of files committed and any errors that you may like to fix before committing the next version in history.

Diff Viewer

You would have also noticed the Version Control dock at the bottom of the Godot Editor.

While staging files to the next version, you can view the file changes in the diff viewer. Just click on the file name in the Staging Area and you will see the diff appear in the bottom Version Control dock. Git doesn't show a diff for new files, thus to test this you will have to commit a file first before making changes to it.

For example, let's say we committed new_script.gd once, and then made some changes to it. After saving the changes, we shall see the following view.

Clicking the file name in the Staging Area will show us the following diff.

The diff area also has a manual refresh button on the top right of the Version Control panel to refresh the diff if you feel your changes have not been reflected in the diff shown.