Using Git via the editor

Using Git via the editor

> Editor in depth

Introduction

What is Git?

Git (pronounced with a hard "g", to rhyme with "bit") 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 you can use locally (on your machine or in the Leek Wars editor), it can also interact with a software forge: a server that hosts Git repositories.

Leek Wars supports several forges. The simplest option is to pick one of these:

• GitHub, a proprietary service owned by Microsoft (USA). It also hosts the Leek Wars code.
• GitLab.com, the official instance of GitLab (USA), free software that you can self-host.
• Bitbucket, a proprietary service owned by Atlassian (USA).
• Codeberg, the official instance of Forgejo, community-driven free software that you can self-host. Codeberg is run by a German non-profit organization.

You can also 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 it and choose "Initialize Git repository". This folder will contain all the files tracked by Git.

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

Making commits

("commit" is Git's word for saving a set of changes: you _commit_ them to the history)

At the top of the Git tab, use the drop-down selector to check that the right 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 them as a draft, not yet set in stone in the history.

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

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

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 together so you don't end 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://example.net/my-username/my-repo.git. It is the address of your repository's main page, with .git added at the end.

You then need to allow Leek Wars to access the repository. How you do this 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 your profile, then Settings, then Developer Settings (at the very bottom). On the page that opens, choose Personal access tokens, then Tokens (classic). Pick an expiration (90 days, for example) and only grant the permissions 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 somewhere 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. You must do this before you can push anything.

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

• GitHub: the main way is the "Install GitHub App" button. During installation, choose which repositories to grant access to; back in Leek Wars, you can then 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, check "Self-hosted instance" and enter the forge's address (this checkbox also exists for GitHub).
• Forgejo: there is no "Self-hosted instance" checkbox 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 stored in Leek Wars. To send it to the forge, you push it with the ⬆ button at the very bottom of the Git tab.

Every time you want to send new commits, push again.

Other features

The editor and the Git tab also offer:

• Clone a repository: File menu → "Clone a git repo", then enter the repository URL and the destination folder.
• Pull: the "Pull" button fetches the commits from the remote, with a choice between a merge or a 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 changes.
• Conflict resolution: if a merge or a rebase runs into conflicts, the editor lets you resolve them and then continue.
• Undo last commit: the changes from the undone commit stay in the index.
• Compact repository: reduces the space taken up by the repository (useful for your quota).
• Built-in Git terminal: shows the log of the Git commands run by the editor.