Skip to content

Git plugin v3

Jump to bottom Edit New page
Dragonforge Development edited this page Jul 19, 2024 · 7 revisions

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 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. Downloading this plugin from the Asset Library will not require you to perform this step.

  5. Open your project using the Godot Project manager.

Note

You do not need to manually enable the plugin in the Project > Project Settings > Plugins tab. In fact, you can't; that tab is for script-based plugins, GDExtension plugins, like this one, will be loaded 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.

image

  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.

image

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.

Warning

There are known issues with SSH authentication, so consider using HTTPS with a personal access token as your password. (GitHub doesn't support using your actual password in HTTPS authentication anymore, so you must create a PAT.)

How to Make a Fine-grained Personal Access Token (PAT)
  1. Click your profile photo, and select Settings (near the bottom).
  2. Click <> Developer Settings in the left sidebar. (It’s the last option.)
  3. Click Personal access tokens in the left sidebar.
  4. Click Fine-grained token.
  5. Click Generate new token.
  6. Name it whatever project(s) for which you are making it.
  7. Set the Expiration for as long as you like. (We don’t recommend over 90 days).
  8. Make a note to yourself in the Description field. (We suggest, “Using the Godot GitHub plugin.”)
  9. Select Only select repositories under Repository access,
  10. Click the Select Repositories dropdown button that just appeared, and select your repo(s). (You can add as many as you like.)
  11. Open Repository permissions under the Permissions header.
  12. Select Read and Write from the Contents dropdown.
  13. Click the green Generate token button at the bottom of the page.
  14. Copy your token and store it somewhere. (You will need it every time you restart Godot.) You cannot come back to Git to see what it is later, and will have to make a new one if you lose this one.
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 your project's root, then the plugin should detect the closest Git repository in the parent directories. If this file system walk fails, then the plugin will create a new Git repository in your project's root directory.

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. Click on the file names or the commits to open their diffs.

image

image

image

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

image

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.

image

image

PROTIP: Once you have written your commit message properly (use multiple lines if needed), you can then use Ctrl+Enter (CMD+Enter for macOS) to commit all staged files instantly or all unstaged files in case the staged area is empty. The Commit editor shortcut can be customized from the editor settings.

  • 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.

image

image

image

image

image

image

  • Commit history along with author and other metadata

image

FAQs

Why isn't my remote HTTPS 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/pulling new commits to/from 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 HTTPS password field.

SSH authentication will require the SSH service on the remote server to use DH key exchange algorithms. Our SSH library - libssh2 seems to only support diffie-hellman-* exchange algorithms for now.

Why is my editor freezing when I push/pull/fetch new changes?

Below is an example output of a fetch operation. The network features of this plugin are single-threaded, which means the editor will freeze while the network operations are taking place. To view the progress of the network operations, you can check the console logs for Git-like logs.

image

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.
Add a custom footer
Add a custom sidebar
Clone this wiki locally