Managing your repositories
This plugin lets you easy-manage your public, private and forked repositories.
Since my purpose was to make a plugin that would let me (and eventually other people) manage in the fastest way possible my Godot projects stored in my GitHub profile, I've really worked hard on creating an intuitive UI, similar to the browser/desktop GitHub one but only with the essential features.
Beginning from your user panel, you can manage your existing repositories, or create a new one.
If you want to create a new repository, press the button on the bottom of the Repositories List, and a popup will open:
To create a new repository you only have to follow the same rules that are applied on GitHub.
- Choose a repository name (instead of spaces use a dash)
- Choose a repository description (*optional)
- Choose if you want the repository to be public or private
- Initialize it with a README (*optional)
- Add a .gitignore (there is a Godot .gitignore which is already compiled to work with Godot Engine projects)
- Add a license (you can choose the license you prefer from the list)
If everything is set up correctly, the repository will be created and the Repository List will be reloaded.
Now, let's find the newly created repository in the Repository List, and double click it.
The Repository Content tab will show something like this:
As you can see, this tab will show you all the essential informations and buttons you need to fully manage this repository.
You can see the name and type of your repository, its description, and the amount of Stars, Forks and Watch.
You can select the branch you want to show with the branch: master button, create a new branch or pull from this branch.
The Repository content list will show in an intuitive way your whole repository.
Unlike GitHub browser/desktop app, in this plugin each file will have its own icon (based on Godot Engine resources), and will be exposed in a "tree" structure, so you can interact with each single file of your repository without entering a specific folder, but just folding/unfolding them.
Now, let's get practical.
Since we didn't initialize the repository with a README, the only files that the repository will contain are .gitignore and LICENSE.
Now, let's assume we want to use this repository to store our whole Godot Project we are working on.
This basically means that we want to "commit changes" to our remote project (the GitHub repository) and "push" these changes.
please, check out what commit&push means through GitHub's offical tutorials about pushing )
If we could do this dragging files from our folders to the chosen repository through browser, or with some lines of code if we are able to use the Git bash (git command-line), we can directly do this within Godot Engine's editor in a simple and elegant way, with all the most important capabilities we need.
Let's press the Commit to Repo button on the bottom of the list and see what we've got:
First, let's choose which branch we want to commit our files to. Let's go for the master branch, since we just created our repository.
check out what branching is in GitHub terms and why it is very helpful).
You can also write a commit message. Even though it is not necessarily required, it can help you or your team understand what this commit is about.
As you will see, there are two important containers in the center of the view: the .gitignore container and Committing files container.
The Committing files one will basically contain and show each file we want to copy inside our remote repository, starting from our project folder.
Now, let's start selecting some files and folders we want to commit using our buttons.
For this example I want to copy my .import folder and each single file contained inside res:// directory. To select multiple files, press the Select Files button and hold CTRL while clicking or different resources, or SHIFT to select a list of them, in the same way as you do with your basic OS File Manager.
Now that we have selected everything, the Committing files container should look something like this:
Each file is ready to be pushed inside or GitHub repository, but before pressing the Commit and Push button, let's take a look at the container on the left, the .gitignore one.
A ".gitignore" is a file containing one or more lines which specify the files, file types or directories we don't want to push, or the exceptions to these.
please, check what a .gitignore files is with datails to understand how it should be used and why it is a very useful resource to manage our repositories. The gitignore pattern is really easy to use but very effective.
Let's ignore the lines that start with a # which will be considered comments and analyze what we ahve inside our .gitignore.
Since we selected "Godot" as our .gitignore sample, what this .gitignore will actually do is ignoring the .import folder, the export.cfg and export_presets.cfg files, .mono folder and data_*/ folder (if our project is made in Godot mono version).
Now, let's press the Commit and Push button and see what will happen.
As you will notice, the plugin will start committing these files and pushing them in your repository.
DO NOT CLOSE GODOT ENGINE'S EDITOR DURING THIS PROCESS. Your files won't be corruppted or lost in any way, but nothing will be pushed and you have to do this process again.
If the commit&push was successfull, the repository will reload and you will be able to see these changes. Let's check them out!
The output is exactly what we were expecting: even if we selected our whole .import folder to be pushed, we ignored it with our .gitignore file, so it won't appear in our repository since it wasn't pushed during this process.
Now, what if we wanted to commit our .import folder too?
Even though if you can always this after the first committing, we can just go back to our Commit and Push panel, click on the Edit .gitignore checkbox and erase the line containing .import; then commit again.
No, and yes. You don't need a gitignore if you don't have specific necessities, and you can just empty the content of your gitignore if you dont need it.
In this example the gitignore is used just to give an example about how my plugin works, and what is a gitignore in general.
To be more accurate and give you another example, to commit and push changes I make for this plugin I'm using this gitignore:
As you can see I'm ignoring all the addons folders I'm using, and some other files which I don't need to change since they are already present in my repository, so I don't want to lose time committing them again.
I'm doing this because the commit&push process begins from the root of your project, which is "res://", so since I just want to commit my plugin and not other plugins wich are nested inside my project folder, I'll just tell GitHub what I want to ignore.
Sometimes we need to delete resources inside or repository.
Let's begin saying that in GitHub you cannot delete entire folders if they are not empty folders (in this case, they will be deleted automatically), and you can only delete one resource at a time.
If you wrongly committed a whole folder you don't need, or some files you want to delete, don't worry!
I've managed to create a simple method to delete multiple resources within your repository at the same time.
For instance, I want to delete VERSION.md and README1.md.
I'll just select both of them holding 'CTRL', and then press the "Delete Resource" button.
Remember, you won't be able to delete a folder selecting it, but with this method you can just select the whole content of a folder 'SHIFT+clicking' them and deleting them. You repository will be deleted automatically once empty.
