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

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 (TODO) or you can use the manual process mentioned below.

  1. Download the latest v3.x release (or see below for installing from source).

  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.

Note: you do not need to manually enable the plugin in the project settings Plugins tab. In fact, you can't; that tab is for script-based plugins, GDExtension plugins load automatically.

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 Version Control Settings.

  1. A popup will ask you which VCS plugin would you like to use. In our case we are using Git, so select GitPlugin from the drop-down menu. Then click Connect to VCS, and optionally enter your remote details to use the network features of this plugin, and then click Apply.

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

The .gitignore and .gitattributes files will be created automatically if not already present. Their contents are picked up from here.

In case your git repository root is not the same as the godot project root, you can set the correct path in the VCS Project Path field. Note currently the plugin will create the .git folder if it doesn't exist (and .gitngnore/.gitattributes), so you may need to remove it after fixing your settings.

Features

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

  • View diffs for files and commits in Git. Both unified and split views are supported by the Godot editor.

  • Stage and unstage files. Double click the file names to move them from the staged to the unstaged area or vice-versa.

If you can't find this panel, try making your right sidebar wider. The default layout of Godot 4.0 has this sidebar too narrow for the Commit panel to appear.

  • Commit changes to Git

  • Branches, use multiple remotes and push/pull/fetch new changes to a Git remote (e.g. a Github repository) with HTTPS or SSH transport. Performing network operations may freeze the editor till the network operation is complete, so you can watch the console logs to view their progress.

  • Commit history along with author and other metadata

FAQs

Why isn't my remote password/SSH passphrase getting saved in the editor?

Currently, the Godot Editor will not save your passwords locally on disk to avoid exposing your passwords to malicious parties. All other remote login settings will be retained.

How to setup network features of this plugin?

After initializing the plugin, enter the remote login settings and hit Apply. You may want to ensure that your SSH public/private key files are having the appropriate permissions for this plugin to be able to load them in.

Open the Commit tab and create a new remote with the SSH endpoint to your Git remote. It should look like the image below.

Note the [email protected]:<organization>/<repository>.git format in the remote URL.

Now Godot should use your specified credentials while pushing new commits to this remote.

Can I use HTTPS remotes?

HTTPS remotes will work normally for read access (pull). Write access requires just a little additional work.

If you are using Github, HTTPS passwords will not work and they will need to be replaced with a Github PAT linked to your Github account. More information on creating a Github PAT is here. Simply paste your PAT in the password field.

Other providers should work as well, but the instructions vary depending on the software. GitLab uses PATs as well, so it should be similar. But to be sure, check the provider's documentation. On the plugin side, you'll want to enter either a password or a token on the password field.

Set up from source

To install from the project source:

  1. Actual build instructions are in README.md.
  2. The built plugin will be found at demo/addons/godot-git-plugin. Copy the entire folder into your project's addons folder, or if you don't have one yet, save time by copying demo/addons into your project.
  3. Make sure you close the project (ideally the editor, to be safe) when installing or updating the plugin.
⚠️ **GitHub.com Fallback** ⚠️