Using Git via the editor

Using Git via the editor

Introduction

What is Git?

Git is a code versioning system that is commonly used in software projects. Among other things, it lets you:

• keep a history of the code, in which you can go back in time;
• synchronize several devices and work as a team on the same files while limiting conflicts;
• maintain several versions of the same code, to develop and experiment without breaking the working version;
• easily back up the project.

A folder versioned by Git is called a repository (or repo for short).

What is a forge?

While Git is a piece of software that can be used locally (on your machine or in the Leek Wars editor), it can also interact with a software forge. That is a server which hosts Git repositories.

Leek Wars supports several forges; the simplest is to pick one of these:

• GitHub, a proprietary service by Microsoft (USA). Also hosts the Leek Wars source code.
• GitLab.com, the official instance of GitLab (USA), a free software that can be self-hosted.
• Bitbucket, a proprietary service by Atlassian (USA).
• Codeberg, the official instance of Forgejo, a community-driven free software that can be self-hosted, run by a German non-profit organization.

It is also possible to use other forges based on GitLab, Bitbucket, Forgejo, Gitea or Gogs, for example framagit.org or gitea.com.

Using Git for an existing AI

First of all, the AI must be inside a folder, not at the root. Create a folder, right-click on the folder and choose "Initialize Git repository". It will contain all the files to be tracked by Git.

A Git tab with a branch icon appears at the top of the file list (left-hand menu). Go there.

Making commits

At the top of the Git tab, check in the drop-down selector that the desired repository is selected (if you have several).

When files in the repository are modified, the changes appear in the Git tab. For now they are unstaged: think of it as a draft, not yet set in the stone of the history.

When you want to record changes into the history, click the ➕ button to stage them. Summarize the changes in a few words in the "Commit message" field, and confirm.

Note: to see all the buttons of the Git tab properly, you may need to widen it to the right by dragging its right edge!

The history is a list of commits, each commit being a set of changes, with a date and a message. The idea is to be able to find out when a given change was made, to go back in time, to group changes so as to avoid ending up with half-working code...

Connecting to a forge

Setup on the forge

Create an account on a Git forge and create an empty repository there. Find your repository's address, which should look like https://exemple.net/mon-pseudo/mon-depot.git. It is the address of your repository's main page, with .git appended at the end.

You then need to allow Leek Wars to access the repository. The procedure depends on the forge.

• GitHub: the easiest way is to install the Leek Wars GitHub App, directly from the editor (see below). Alternatively, you can create a token: click on your profile, Settings, Developer Settings (at the very bottom). On the page that opens, choose Personal access tokens, Tokens (classic). Pick an expiration (90 days, for example) and only grant the rights needed to contribute to the repository.
• Forgejo: Account settings, Applications, New access token. Allow read and write access to "repository".

If you created a token, keep it safe so you don't lose it!

Setup on Leek Wars

At the bottom of the Git tab, click the cloud button "Remote settings".

This is where you declare the remote repository (the remote): enter a name (for example origin), paste the repository URL and click the "Add" button. This step is required before you can push anything.

For authentication, choose your forge: GitHub, GitLab, Bitbucket or Forgejo.

• GitHub: the main path is the "Install GitHub App" button. During installation, choose which repositories to grant access to; back in Leek Wars, you will be able to pick one of these repositories directly for the remote. Alternatively, paste a Personal Access Token into the "Access token" field.
• GitLab and Bitbucket: paste the token into the "Access token" field. If you use a self-hosted instance rather than gitlab.com or bitbucket.org, tick "Self-hosted instance" and enter the forge's address (this checkbox also exists for GitHub).
• Forgejo: the "Self-hosted instance" checkbox does not exist for this forge; the instance address field is always shown (pre-filled with codeberg.org). Enter your instance's address if needed, and paste the token into the "Access token" field.

Sending your commits to the server

For now, the commit history is only recorded in Leek Wars. To send it to the forge, you do a push with the ⬆ button at the very bottom of the Git tab.

Each time you want to send new commits, do a push.

Other features

The editor and the Git tab also offer:

• Clone a repository: File menu → "Clone a git repo", by entering the repository URL and the destination folder.
• Pull: "Pull" button to fetch the commits from the remote, with a choice between a merge or rebase strategy ("Pull strategy").
• Branches: the branch selector lets you switch branches, create new ones ("New branch...") and see the remote branches.
• History and diff: the "History" button lists the commits, and clicking a modified file shows its differences.
• Conflict resolution: in case of a conflict during a merge or a rebase, the editor lets you resolve them and then continue.
• Undo last commit: the changes of the undone commit remain in the index.
• Compact repository: reduces the space taken up by the repository (useful for the quota).
• Built-in Git terminal: shows the log of the Git commands run by the editor.