Source control with Git

Git keeps a history of a folder: every saved state, who made it, and a way back to any of them. It's also how a website or an app gets to a host. Kitlig has a Git view in Dev mode, so you can commit, branch, tag, push and deploy without leaving the project.

Kitlig drives the Git that's installed on your computer. Your SSH keys, your sign-ins and your Git settings work the way they do in a terminal, and anything you do here shows up there.

Note

Git has to be installed. If it isn't, the view says so and offers Check again once you've installed it from git-scm.com.

Opening it

There are three ways in:

On Dev's front page, click Source control at the bottom of the list on the left. It opens on a list of everything in the project that is or could be a repository.
With a website, game or app open, click Git in its bar. The view opens straight on that folder.
In the bar along the bottom of the window, click the branch name next to the spend readout. It works from any mode and opens the repository it names.

Dev in the top left of the view takes you back to where you were.

The branch in the bottom bar

Once something in the project is a repository, the bottom bar shows its branch. A dot with a number counts changed files, an up arrow counts commits to push, and a down arrow counts commits to pull. Hover it for the same in words.

It speaks for the repository you last had open in Source control. Failing that it shows the whole project's, and failing that the first folder that has one. With nothing in Git yet it reads Git and opens the list of folders.

One project, several repositories

A repository is one folder with its own history. A project can hold more than one, and the first page lists every candidate in three groups:

Project: Whole project is the project folder itself, with records, scenes, workflows, CAD parts and everything under web/.
Websites, games and apps: each one can have a repository of its own, with its own branches and its own remote. That suits a site you publish or an app you share by itself.
Project folders: one folder by itself, such as CAD parts, Scripts, Workflows, Library or Scenes. Any other top-level folder shows up here once it holds a repository.

A row that is already a repository shows its branch, how many files changed, and how many commits wait to be pushed or pulled, and reads Open. The others read Start a repository. Click a row to go in.

Once you're in, the picker in the bar switches between them, and Repositories goes back to the list. Nothing is lost by switching; each repository keeps its own state.

Starting a repository

A folder that isn't a repository yet shows a card instead of its changes.

Set First branch. main is the usual name.
Leave the starter ignore rules ticked unless you have your own. They keep caches, installed packages and secrets out. An existing .gitignore is never replaced.
Click Start a repository here.

Warning

If the project is already a repository and you start another inside one of its folders, the project stops looking inside that folder. Ignore the folder in the project's rules so the two histories don't overlap.

Note

Media is large. Most Git hosts refuse files over 100 MB and slow down long before that. For the whole project, turn on the Large media group under Ignore rules unless your host is set up for big files, and keep media safe with Backups.

Changes and commits

The Changes tab lists what's different from the last commit.

Changes holds files you've edited, added or deleted. The letter says which: M for changed, N or A for new, D for deleted.
Staged holds what goes into the next commit.

Click a file to read its change on the right. Green lines were added, red lines were removed. Hover a file for its buttons: the plus stages it, the minus unstages it, and the arrow discards the change. Stage all, Unstage all and Discard all act on the whole list.

File sizes

Every file shows its size on disk, and a thin bar under the row measures it against the biggest changed file, so the heavy ones stand out. Each list's heading has its total, and the strip above the lists has the total of everything.

Largest first sorts both lists by size. Name puts them back.
A size in brass is 50 MB or more. A size in red is over 100 MB, and a banner says how many files are.

Warning

Most Git hosts refuse a file over 100 MB, and the whole push fails with it. Ignore those files before you commit: once a big file is in a commit, removing it later means rewriting history.

Right-click a file for the same actions, plus three ways to keep it out of Git from now on:

Add to .gitignore ignores that one file. For a file Git already tracks it reads Add to .gitignore and stop tracking, and does both. The file stays on disk.
Ignore the folder ignores everything in the file's folder.
Ignore every … file ignores every file with that extension, anywhere in the repository.

Warning

Discarding can't be undone. A changed file goes back to how it was, and a new file is deleted.

To commit:

Stage the files that belong together, or stage nothing to take everything.
Type a message that says what changed.
Click the commit button. It reads Commit 3 staged, or Commit all 5 when nothing is staged. Ctrl+Enter in the message box does the same.

Commit and push commits and then sends the branch to its remote. Amend the last commit replaces the last commit with a corrected one. Only amend a commit you haven't pushed.

History

The History tab draws the commits as a graph, newest at the top. Each branch runs in its own coloured lane, and a merge shows as two lanes joining. Labels on a row name the branches and tags that point at it: the filled one is what you have checked out.

All branches shows everything, local and remote. This branch shows only what the checked-out branch contains. Show older commits loads more.

Click a commit to open it. You get its full message, its author and date, the files it changed, and each file's change. From there:

Branch from here starts a new branch at that commit and switches to it.
Tag names that commit.
Check out puts the files back to how they were at that commit so you can look around. You're off any branch until you switch back to one.

Branches and tags

Switch branches from the second picker in the bar, which also has New branch…. The Branches & tags tab has the rest:

Branches: click one to switch to it. Hover for merge into the current branch, rename and delete. Deleting a branch with commits that aren't merged anywhere asks a second time.
On remotes: branches that exist on the remote. Click one to get a local branch that follows it.
Tags: New tag names the commit you're on, with an optional note. Hover a tag to push it, check it out or delete it. Push all sends the branch and every tag.
Stash: Stash changes puts every change aside, new files included, and leaves a clean working copy. Bring back returns the latest stash. Use it when Git won't switch branches because your changes would be overwritten.

Remotes, accounts and keys

A remote is the copy of the repository on a host such as GitHub or GitLab. The Remotes & accounts tab sets where this repository goes and who it goes as.

Adding a remote

Create an empty repository on your Git host.
Paste its address into the field under Remotes. The name is usually origin.
Click Add remote.

Addresses that start git@ use an SSH key. Addresses that start https:// use your Git credential helper, which opens its own sign-in window the first time. Each remote is labelled with which one it is. For an SSH remote, Test sign-in asks the host who the key signs in as.

Who commits and pushes here

These settings apply to this repository only. Leave a field empty to use your computer's own setting.

Name and Email go on every commit. Git refuses to commit without them.
SSH key pins this repository to one key. That's the way to push one site as your work account and another as your own. This computer's default leaves the choice to your SSH agent and ~/.ssh/config.

This computer

This card lists what Git can sign in with:

Signed-in accounts found through the GitHub CLI, with the host and whether it uses SSH or HTTPS.
SSH accounts: the Git hosts named in ~/.ssh/config, such as a github-work entry that signs in to github.com with its own key. Test asks the host which account that entry signs in as. Copy address copies the start of a remote address for it, like git@github-work:, ready for you/project.git.
SSH keys: the keys those hosts use, each with the hosts that use it. Type a host next to Test against and click Test on a key to see which account it belongs to. Keys that no host names are behind Show other keys.

Only Git sign-ins are listed. Servers you log in to from ~/.ssh/config, and keys that only sign in to them, are left out.

Kitlig reads names and public keys only. It never reads a private key or a password, and it doesn't store any sign-in itself.

Note

Kitlig can't answer a password prompt. A key with a passphrase has to be loaded in your SSH agent first, or the push fails with a message saying the host refused the key.

Fetch, pull and push

The buttons on the right of the bar talk to the remote:

Fetch looks at what changed on the remote without touching your files.
Pull brings the remote's commits into your branch. The number next to it is how many are waiting.
Push sends your commits. The first push of a branch also makes it follow the remote branch from then on.

If the remote has commits you don't, the push is refused. Pull first, then push. After an amend or a rebase, Kitlig offers a force push instead. It only replaces the remote's commits if nobody has pushed since your last fetch.

Deploy

Many hosts build and publish a site whenever one particular branch is pushed. Set that up once and Deploy becomes one click.

On Remotes & accounts, under Deploy, pick the remote and type the branch your host builds from, such as main, production or gh-pages.
Click Save. A Deploy button appears in the bar.
Click Deploy. Optionally name a tag for the release, then confirm.

Deploy pushes what you have checked out to that branch, whatever branch you're on. With a tag, it also creates the tag and pushes it.

Note

Deploy is a push. What happens next, the build and the publish, is up to your host. Kitlig doesn't watch it.

Ignore rules

A .gitignore file lists what Git should leave alone. The Ignore rules tab edits it two ways, and both write the same file.

On the left, by ticking:

Ready-made groups switch a set of rules on or off: System files, Node.js, Python, Firmware builds, Secrets and Editor settings. The whole project also gets Kitlig caches, Temporary media and Large media. Hover a group to see its rules.
Files lists the folder's contents. Tick a file or folder to ignore it, untick to keep it. Click a folder to look inside. The rule that ignores an entry is shown next to it.

On the right, by typing: the file itself, one rule per line. Save writes it, and Revert drops your typing.

A tick saves straight away and takes any unsaved typing with it.

Note

Ignoring a file that Git already tracks changes nothing by itself. Those entries get a Stop tracking button. It keeps the file on disk and removes it from the repository with your next commit.

Activity

Everything Kitlig asks Git to do is logged on the Activity tab, newest first: the exact command, every line Git printed, how long it took and how it ended. A failure shows Git's own message, with a plain hint for the common ones.

While something runs, a strip at the bottom of the view shows the step and a progress bar for uploads and downloads. Show output jumps to the log and Cancel stops it. Actions on the same repository run one after another.

What it doesn't do

It doesn't resolve merge conflicts for you. A conflicted merge is flagged on Changes: fix the marked files in the code editor, stage them and commit, or click Abort merge.
Rebase, cherry-pick and submodules aren't in the view. Do those in a terminal; the view picks up the result when you come back to it.
There's no Git LFS setup. If your host needs it for big files, set it up in a terminal first.