Git plugin v3
- Install Git from https://www.git-scm.com/
- Configure your username and email in Git
$ git config --global user.name "your name"
$ git config --global user.email your@email.comYou can install this plugin from the Godot Asset Library here or you can use the manual process mentioned below.
-
Download the latest v3.x release (or see below for installing from source).
-
Windows users should ensure they have the VC 2019 redistributable runtime installed.
-
MacOS users may need to perform a one-time workaround as described here to be able to load the plugin in Godot.
-
Extract the .zip contents under the
res://addons/directory of your Godot project. Please ensure that the plugin does not get extracted insideres://addons/godot-git-plugin-vx.x.x/godot-git-plugin, the plugin requires itself to be kept atres://addons/godot-git-plugin. Downloading this plugin from the Asset Library will not require you to perform this step. -
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.
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.
- Open
Project>Version Control. SelectVersion Control Settings.
- A popup will ask you which VCS plugin would you like to use. In our case we are using Git, so select
GitPluginfrom the drop-down menu. Then clickConnect to VCS, and optionally enter your remote details to use the network features of this plugin, and then clickApply.
If you are not able to see a
GitPluginoption then check if you copied the correct folder tores://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.)
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.
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.
- Stage and unstage files. Double click on the file names to move them from the staged area 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.
PROTIP: Once you have written your commit message properly (use multiple lines if needed), you can then use
Ctrl+Enter(CMD+Enterfor macOS) to commit all staged files instantly or all unstaged files in case the staged area is empty. TheCommiteditor 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.
- Commit history along with author and other metadata
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 git@github.com:<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.
To install from the project source:
- Actual build instructions are in
README.md. - The built plugin will be found at
demo/addons/godot-git-plugin. Copy the entire folder into your project'saddonsfolder, or if you don't have one yet, save time by copyingdemo/addonsinto your project. - Make sure you close the project (ideally the editor, to be safe) when installing or updating the plugin.