Introduction to Game of Trees (EuroBSDcon 2026)

Conceptually, the repository’s data model is a directed acyclic graph which contains four types of objects as nodes.

Each object is referred to by an intrinsic identifier, or object ID, which is a checksum calculated over both the object’s header (type and size information) and the data stored in the object itself.

The 4 object types are as follows:

Blobs

The content of files is stored in objects of type blob.

Trees

A tree object is a manifest which lists any number of blobs or other trees along with their path-names and object IDs, in order to represent a hierarchy of files and directories.

Commits

A commit object points to the root element of one tree, and thus records the state of this entire tree as a snapshot. Commit objects are chained together to form lines of version control history. Most commits have just one successor commit, but commits may be succeeded by more than one subsequent commits so that diverging lines of version control history, known as branches, can be represented. A commit which precedes another commit is referred to as that other commit’s parent commit. A commit with multiple parents unites disparate lines of history and is known as a merge commit.

Tags

A tag object associates a user-defined label with another object, which is typically a commit object. Tags are usually used to represent releases of the software managed in the Git repository.

A Git reference associates a path-like name with an object ID. References act as user-friendly aliases for intrinsic identifiers.

A prominent use of references is providing names to branches in the repository by pointing at commit objects which represent the current tip commit of a branch. Because references may point to arbitrary object IDs, their use is not limited to branches.

A symbolic reference associates a name with the name of another reference, much like a symbolic link in a Unix-like filesystem. The most prominent example is the HEAD reference which points at the name of the repository’s default branch reference, which is usually, but not always, refs/heads/main. Game of Trees resolves the HEAD reference to find the default branch to use if no branch is provided by the user.

A typical Git repository exposes a work tree which allows the user to make changes to versioned files and create new commits. When a Git work tree is present, the actual repository data is stored in a .git subfolder of the repository’s root directory.

A Git repository without a work tree is known as a bare repository. Game of Trees does not make use of Git’s work tree and treats every repository as if it was bare.

When sharing a repository between Git and Game of Trees, a bare repository should be preferred to avoid interactions between Game of Trees and Git’s work tree format. Running both version control systems on the same non-bare repository can sometimes result in unexpected or inconvenient behaviour of either version control system.

Game of Trees uses a custom work tree format which allows an arbitrary number of work trees to be checked out from a Git repository. Each work tree can commit new changes to the repository, and update itself to commits other than the one it was checked out from.

It is possible to scope a work tree to a sub-directory of the file and directory tree stored in commits. This is can be useful when a Git repository contains multiple projects or software modules.

A work tree is always tied to a branch, which means the “detached HEAD” state known to Git users cannot occur with Game of Trees.

More details about the Git repository format are available in the git-repository manual page once Game of Trees has been installed, or online at: https://gameoftrees.org/git-repository.5.html

There is also no shortage of articles and books out there which describe the Git repository format in various degrees of detail.

For details about the Game of Trees work tree format, see the got-worktree manual page, or read it online at https://gameoftrees.org/got-worktree.5.html

To install Game of Trees, run:

See https://gameoftrees.org/install.html for details.

Installable binary packages of Game of Trees are known to exist for the following systems. If your operating system is one of them then please search the database of installable packages.

On other Unix-like operating systems, Game of Trees can be built from source code. See https://gameoftrees.org/portable.html for details.

On Windows, use the Windows Subsystem for Linux (WSL) with one of the Linux distributions above. For example, in Powershell, run:

Reboot, then start the WSL environment:

Now install Game of Trees packages from https://build.opensuse.org/package/show/devel:tools:scm/got by running:

You should now be able to run Game of Trees commands from a Windows Powershell prompt by prefixing the commands with wsl:

In the abstract, version control can be represented by workflows (or “use cases”), each of which serves a specific task or goal as part of the life-cycle of a software development project.

Version control workflows supported by Game of Trees include:

The Game of Trees user interface models version control workflows on top of the Git repository format. User-visible Git repository concepts involved in modeling workflows were already discussed in the “Git Repository Format” section:

Knowledge of any other Git repository internals should not be required while using Game of Trees for version control.

Additional user-visible concepts, which will be covered later in this tutorial, are:

For long-term repository maintenance, especially on servers, a basic understanding of additional Git repository concepts will be useful:

These concepts will likewise be covered later in this tutorial.

The behaviour of got is influenced by shell environment variables. The following two environment variables should be set for the purposes of this tutorial:

Create a new empty directory, and create some directories and text files inside of it. The following file and directory hierarchy is recommended for this tutorial:

Running the following commands will create this hierarchy of files and directories:

The ~/new directory is temporary. It can be removed again once this entire tutorial section has been completed.

Create a new directory which will host repositories and other data required throughout this tutorial:

Switch into this directory and create the first Git repository using the got init command:

Switch into the newly create repository and import the file and directory hierarchy which was created above:

Your editor should open and display a file which contains an empty line at the top, followed by a line which begins with # that you can ignore for now.

Type a log message anywhere in this file to document the initial import of the file hierarchy. (Any lines beginning with # will be ignored and will not become part of the recorded log message.) This first log message could be something as trivial as “initial import”, such that the editor window contains:

Now save the file and exit your editor. The got program should produce output similar to the following, showing the list of files with were added:

We have now recorded a new snapshot in the Git repository which contains the newly added files.

Some Git-repository concepts have already appeared during got import. We will go through them now:

This should print something like:

The output should be:

The intrinsic identifiers of files (blob objects) and directories (tree objects) are also part of the snapshot. They can be displayed by passing the -i option to the got tree command:

The output should be similar to:

The got import command can be used to put a set of files under version control, which now serve as a base for further modifications. But files stored in the repository cannot be changed directly. We must create a work tree (or “working copy”) of the files in order to make changes to them.

The got checkout command is used to create work trees. The simplest way to run this command is as follows:

This should print output similar to the following:

A work tree of the main branch was created in the directory firststeps.

Edit files in the work tree with your editor, or with shell commands. For example:

The current status of files in the work tree can be obtained by running:

This should print a line indicating that the file alpha has been modified:

Changes to file content in the work tree can be viewed by running:

This should print changes in all modified files, using the “unified diff” command known from the diff -u utility on Unix-like systems.

The information conveyed here is as follows:

We are viewing differences between the base versions of files in the work tree at /home/user/tutorial/firststeps and the files located at on-disk paths within this work tree.

Specifically, for the file alpha, the differences we see are relative to the given blob object which was reached via the given commit object.

Both the old (---) and new (+) versions of the file are called alpha.

This line is a “unified diff” chunk header. The @@ symbols are markers which allow the chunk header to be recognized as such when reading the unified diff. The negative number (here -1) indicates the number of lines present in the previous version of the chunk. The positive number (here +1) indicates the number of lines present in the new version of the chunk.

Following the chunk header are lines of file content related to the chunk. As indicated in the chunk header, there is one line which was present in the previous version of the file but has been removed in the new version of file:

And there is one line which is instead present in the new version of the file:

To record a new snapshot which records the change we have made, run:

The editor should open again, showing an empty log message with some comments, similar to how got import behaved:

Write a log message describing the rationale of the changes you have made, (such as "change file alpha in accordance with tutorial instructions". Then save the file and exit the editor.

The got commit command should produce output similar to:

The change has now been recorded in the repository.

The snapshots recorded in repository history can be viewed with the got log command:

This should print two entries, one for each commit present in our repository:

The head commit of the main branch is marked with the branch name in parenthesis next to the head commit’s identifier.

By default, only log messages are displayed. It is also possible to include the list of files modified in each commit by running:

The -d flag adds diff statistics to the output:

It is also possible to view changes to file content by passing the -p (patch) option to got log, either alone or together with -d. For example, run:

The output should be similar to the following. Here, the unified diff headers indicate that we are viewing differences between two commit objects, rather than differences in a work tree.

When diffs become long, it will be useful to pipe the output of got log into a pager program. For example:

This should display output similar to the above in a pager, allowing the user to scroll through.

Obtain a second work tree from the firststeps.git repository:

We can independently modify files in each work tree, and check our changes in.

First, commit a change to file epsilon/zeta from the newly created work tree:

Now commit a change to file gamma/delta from the other work tree:

Each work tree will now contain a different version of epsilon/zeta and gamma/delta, respectively. Run this to confirm:

The above command should print something like:

Likewise, comparing epsilon/zeta between the two work trees yields a difference:

The above command should print something like:

This shows that epsilon/zeta was only changed in one work tree, while gamma/delta was only changed in the other work tree.

This might seem obvious, but there are some non-obvious consequences to consider:

In the latest commit found inside the repository, both files have been changed. We can use the got cat to confirm this:

The above should print:

Both changes are now part of the branch both work trees where checked out from. Run this to confirm:

The output should be similar to the following:

We can see that:

We will learn some details about this an upcoming section called The Game of Trees Work Tree. For now, considering the consequences of the behaviour observed, let’s conclude that committing changes is equivalent to a write-only operation on the repository. The files we changed were written to the repository by the got commit operation, but nothing was ever read back from the repository during the got commit operation. Reading changes from the repository is not a task of the got commit command. This task is left to another command, which is called got update.

Switch to a work tree directory and run the got info command:

The got info command prints the work tree’s meta-data. This meta-data is stored in a hidden .got directory inside the work tree:

For our purposes, the interesting parts are the following:

The work tree base commit indicates which commit the files in work tree where checked out from.

The work tree branch reference indicates which branch the work tree was checked out from.

The work tree records the absolute path of the repository it was checked out from. In case the repository is moved, the path can be adjusted by editing the file .got/repository in the work tree. Alternatively, a new work tree can be checked out from the moved repository.

As seen in the previous section, the work tree records the identifier of the commit from which all files in the work tree were initially obtained as the global base commit.

Additionally, for each file, separate base commit and base blob identifiers are recorded. This can be seen by passing a file path to got info. For example, run:

This should display the same global work tree meta-data as before, following by meta-data specific to the file at path beta:

We can see that a base commit identifier is recorded per-file. This item of meta-data is distinct from the work tree’s global base commit identifier. There is no requirement that all files in the work tree must be based on their versions as found in the single commit which was initially checked out. We can mix and match files from distinct commits in the work tree.

This can be useful in some workflows, e.g. to reset some files to an earlier version if that helps us with searching for the root cause of a problem in a code base.

Game of Trees makes use of this flexibility internally when got commit is run several times in succession in order to record multiple snapshots. Each subsequent commit operation only writes a subset of the changes from the work tree to the Git repository. Files modified in a given commit have their base commit identifier updated accordingly, while meta-data for unchanged files is left alone.

This works as long as the all files being committed are “up-to-date”. Before a file is committed to the repository, its base blob identifier is compared to the blob identifier recorded in the current branch head in the repository. If these identifiers differ then there are new changes for the file waiting to be fetched from the repository into the work tree, and the commit operation will fail.

Fetch new changes from the repository into the second work tree. Run:

This should print something like:

This work tree now accurately represents the state of the main branch’s head commit again, after having diverged while working on changes for the file epsilon/zeta.

As mentioned previously, committing to files which are based on out-of-date versions should not be possible. In this section we examine how Game of Trees behaves when we try.

Modify gamma/delta in both work trees, attempting to commit each time:

The above commit from the first work tree should succeed as before.

Attempting the same from the second work tree should result in an error:

This commit operation should fail with the following error:

Run the got update command to fetch the new changes for gamma/delta into this work tree:

The output should be similar to:

The new changes have been merged with the local (uncommitted) changes. Because the changes overlap (there is only one line in the file which was modified on both sides), a merge conflict has been recorded in the file, as per the diff3 algorithm mentioned earlier.

Examine the contents of gamma/delta. Run:

The contents should be similar to the following:

The file now contains conflict markers, displaying all 3 versions of lines as seen by the diff3 algorithm. (For simplicity, this example uses a single line in all versions of the file. But conflicts across overlapping regions of multiple lines are more usual in practice, and will be surrounded by conflict markers just as well.)

The first version displayed contains the version which was newly fetched into the work tree from the repository:

The second version displayed contains the version the other two versions were based on:

The third version displayed contains the version found in the work tree:

Trying to commit a file with conflict markers should fail. Before removing the conflict markers from the file, run:

The output should be:

While the version control system can detect overlapping modifications and flag them as merge conflicts, it does not know how conflicts can be resolved in a reasonable way. It’s up to the user to modify conflicted sections in the file, ensuring that the merged result makes sense and matches their intentions.

Open gamma/delta in and editor and modify the content to your liking, removing the lines with conflict markers in the process, which are:

Examine the result of your changes with got diff to verify that the changes you are about to commit match your intentions.

The commit operation should now succeed. Run:

The output should indicate a successful commit operation:

For the purposes of this tutorial we will simulate remote repositories by connecting to localhost over SSH.

The Git repository server programs which Game of Trees will invoke across SSH connections are Git’s git-upload-pack and git-receive-pack commands. Please ensure that these programs are installed on your system, and install Git from your operating system’s package manager if they are missing.

Next, generate a temporary SSH key which can be removed again once we are done with this tutorial.

When ssh-keygen asks for a passphrase, you can leave the passphrase empty by pressing Enter twice.

Add the temporary SSH key to the end of your .ssh/authorized_keys file:

Connect once and accept the host key fingerprint if needed:

This SSH command should lead you to a new shell prompt on your own machine. If that worked, run:

and SSH should print:

To avoid the need for passing a temporary ssh key on the ssh command line every time, add the following lines at the end of ~/.ssh/config:

These lines can be removed again once we are done with this tutorial.

The following command should now succeed as before, without having to pass the -i option on the command line:

Create a second Git repository in your tutorial folder:

We leave this new repository empty for now, and configure Game of Trees to refer to it as a remote repository from the firstrepo.git repository.

Create the file ~/tutorial/firstrepo.git/got.conf with the following contents:

This sets the default remote repository, called “origin” by convention, to remoterepo.git on the Git server localhost. (In the real world, the server name will rarely be localhost, of course. It will usually refer to some Git hosting site’s server instead.)

With the remote repository configuration in place, we can now send all pending changes from firstrepo.git to remoterepo.git:

A successful got send command should print something similar to:

Inspect commit history of the firstrepo.git and keep it in mind for later reference:

Inspect commit history of the remoterepo.git repository, which should now contain the same history as the firstrepo.git repository:

List the references which exist in remoterepo.git, using the got ref command:

The output should be similar to:

As expected, this repository now contains the main branch we have sent to it.

List the references which exist in firstrepo.git:

This should print output similar to:

Compared to remoterepo.git, there are three additional references visible. Two references in the refs/got/ namespace, and one reference in the refs/remote/ namespace.

These references are in the refs/got/ reference namespace, which is automatically managed by Game of Trees:

These references point at commits which the two work trees in our ~/tutorial directory are using as their global base commit at present. We can ignore these references for now. They exist to prevent commits in active use by work trees from being garbage-collected by programs such as git gc or gotadmin cleanup.

For our current purposes, this other additional reference is far more interesting:

This reference was created by the successful got send operation above and represents changes most recently sent to, or most recently fetched from, the main branch of the remote repository remoterepo.git, which we labeled “origin”.

Commit another change to the firststeps.git repository:

The above got commit command should succeed with output similar to:

Create a work tree for remoterepo.git and commit a new change from there:

The above got commit command should succeed with output similar to:

The remote repository remoterepo.git now has new changes which are missing in the firststeps.git repository, and vice versa.

In the firststeps.git repository, can use the got fetch command to fetch changes from the default “origin” remote:

The above got fetch command should succeed with output similar to:

The most important line of the above output is:

The firststeps.git repository now contains a copy of the changes which were committed to the main branch of remoterepo.git above, visible under the reference refs/remotes/origin/main.

Inspect commit history of the refs/remotes/origin/main in the firststeps.git repository:

Here, we are asking got log to start traversing history at the commit which can be resolved by following the reference refs/remotes/origin/main.

As a side-note, the following command is equivalent to the above:

To save us some typing effort on the command line, Game of Trees allows us to specify non-absolute reference names, i.e. names without the leading refs/ component. The specified name will first be searched in the refs/heads/ namespace, then in the refs/tags/ namespace, and finally in the refs/remotes/ namespace. This avoids having to type those reference prefixes every time.

The output of the above got log command should match the output of this command, which displays the history of the refs/heads/main branch in the remoterepo.git repository.

It is important to highlight that two distinct branch heads for main now exist in firststeps.git: One which was committed directly to firststeps.git, and one which was committed to remoterepo.git and then fetched into firststeps.git. Both branch heads represent distinct changes which have not been merged yet. We will perform a merge of the changes in the next section.

Much like Git, Game of Trees provides two operations for merging changes. Both operations are explained below. We will use the first one in this section of the tutorial, and the second one in a later section.

Merge: The merge operation takes two branch heads (main and origin/main in our example), then merges files from both heads and their common ancestor commit using the diff3 algorithm, and creates a new snapshot which contains the merged files. The commit object created for this snapshot refers to both two branch heads via two parent commits. This approach leaves the intrinsic identifiers of both branch heads unchanged.

Rebase: The rebase operation builds a list of all commits between one of the two branch heads (the “rebased” one) and the common ancestor commit of both branches. The rebase operation then traverses this list of commits, and merges the changes found in each commit on top of the other branch head (the “base” one) in sequence, using the diff3 algorithm. Each time, the common ancestor used for diff3 is the commit just below the head commit of the “rebased” branch. The commit object created for the resulting snapshot is the tip of a chain of commits, all of which have a single parent commit, which ultimately ends at the head commit of the “base” branch. While the “base” branch head gets to keep its intrinsic identifier, all commits of the “rebased” branch head are rewritten with their parent commit adjusted, which changes their intrinsic identifiers.

The question of whether to merge or rebase changes is largely philosophical. When contributing to a Git-repository-based software project in the real world, there will usually be guidance as to which strategy is preferred.

Nevertheless, the following rules of thumb will usually apply:

We can use the got merge command to merge outstanding changes reachable from the refs/remotes/origin/main branch head into a work tree checked out from refs/heads/main.

First, verify that your work tree of the firststeps.git repository is indeed on the main branch:

The output should be:

The work tree also needs to be a fully up-to-date single-commit work tree. Run the got update command to ensure this:

The work tree status should be clean, without any uncommitted modifications present. Verify this with the got status command:

If the got status command reports nothing then the work tree is clean. If there are any pending changes you want to keep, commit them now and the run got update again once more.

The work tree is now ready to merge changes from the remote repository. Run:

The output should be similar to:

This resulting merge commit can be inspected with the got log command:

The above got log command should show a commit which lists two parent commits:

The first parent commit is the base commit of the work tree in which the merge was performed.

The second parent commit is the branch head of the remote repository’s main branch, as cached locally in refs/remotes/origin/main.

By adding the -p option to the got log command we can examine the changes added to our local main branch during the merge:

The output should be similar to:

The changes shown in the patch below the commit’s log message should correspond to the changes which were originally committed from the work tree of the remoterepo.git repository.

We can now send our changes to remoterepo.git, along with the merge commit we just created:

There is no need to pass any arguments to got send in this case, The current work tree’s branch will be sent by default, which is the branch we have merged new changes into. And we are sending to the default “origin” remote repository, so we do not need to specify a remote repository handle either.

The output should be similar to:

Update the work tree of remoterepo.git to to make the sent changes visible there:

The above got update command might complain as follows:

Ideally, this would not happen and the update would succeed. The update fails because secondary parents of merge commits are currently skipped during the got update commit ancestry check for performance reasons. Until this behaviour is improved, the -b option can be used as a workaround, which explicitly tells Game of Trees that we are fine with updating to the head of the current main branch as seen in the repository:

The output should be similar to:

The change to file alpha originally committed to firststeps.git is now visible in this work tree of remoterepo.git. Verify this by running:

The output should be similar to the following, and display the change you made to file alpha in firststeps.git earlier:

Our current remoterepo.git started out as an empty repository which we sent changes to from our local repository firststeps.git. This is a common scenario when starting a new project and then publishing it on other Git servers. But the far more common scenario is that users want to clone a repository someone else has created and populated with interesting content.

The got clone command can be used to clone remote repositories to the local disk. We can clone our remoterepo.git as follows:

The output should be:

There is now an identical clone of remoterepo.git in localrepo.git. We can compare the set of references to see this:

The list of references in remoterepo.git should be similar to:

Obtain the list of references in localrepo.git for comparison:

This list should be similar to:

While the refs/heads/main branch head reference are identical on both sides, there are some differences:

Additionally, got clone has created a got.conf configuration file in localrepo.git which defines the default “origin” remote repository handle for us, so we do not need to add it manually. Use the cat command to display this configuration file:

The output should be:

This looks similar to the got.conf file we created manually earlier. The only addition is a fetch configuration block, which instructs got fetch to always fetch the default main branch from the remote repository, regardless of which branch is currently checked out in the work tree which got fetch is invoked in.

By default, Game of Trees ignores additional files which appear in the work tree. Files will be tracked under version control only if we explicitly ask for them to be tracked.

Create a new file in a work tree of localrepo.git:

Examine the current work tree status with the got status command:

The output should be:

In the above output, the ? status marker refers to files which are “unversioned”, i.e. not tracked under version control. While Game of Trees notices such files, it will ignore them. In fact, such files are assumed to belong to the user and not the version control system. Game of Trees will never touch such files without an explicit request, even if such files could be affected by operations performed on this work tree. For instance, assuming some remote repository already tracks a file psi and has changes for it which we fetch, the changes destined for this file would be ignored if we were trying to merge them into this work tree. If we do not want the file psi to be ignored, we must add it to version control and commit it.

Unless changes to already tracked files are present in your work tree, trying to commit from the work tree at this point should fail:

The output should be:

Adding new files to version control is done with the got add command:

The output of the got add command should be:

The A status marker means the file is now in “added” state, ready to become part of the next snapshot we create in the repository. While the file is marked for addition, its content is not yet stored in the repository. Any further changes made to the file while in “added” state will become part of the next snapshot created with got commit. Removing the file from disk at this point would still cause its content to be lost.

Commit the addition of file psi by running:

The editor window which opens should contain a log message template which mentions file psi being added:

Enter a suitable log message, save, and exit the editor.

The commit should succeed with output similar to the following:

The file psi is now part of the latest snapshot stored in the repository. Listing files and directories in the snapshot should now display the file:

The output should be:

If your work tree ends up contains a lot of unversioned files (e.g. because software compilation produces a lot of derived build artifacts), the amount of lines reported the ? status marker can drown out useful status information about files under version control.

Game of Trees supports ‘ignore’' lists to hide such files from the output of got status. Ignore lists are stored in a file with the special filename .gitignore (and, for compatibility with the OpenBSD CVS repository, .cvsignore). A .gitignore file can appear in any directory of the work tree and applies to unversioned files located within this directory, and can optionally also apply to unversioned files anywhere below this directory.

The .gitignore file provides patterns which match unversioned file names that should be ignored. One pattern can be defined per line.

In your work tree of localrepo.git, add another unversioned file:

Running got status at this point should result in the file being displayed as unversioned:

The output should be:

Create a .gitignore file which matches all file names ending with “-me”:

Run got status again:

The output should now be:

Add the file .gitignore to version control and commit it:

Ignored files will be hidden from the output of got status unless the -I option of got status is used. Try:

With -I, the expected output is:

Attempt to add the ignore-me file to version control:

There should be no output, and the output of got status should remain empty as well.

Ignored files will not be added to version control by got add. unless the -I option is used to exceptionally add a file which matches an ignore pattern:

Now we should see:

Commit the addition of the ignore-me file. We will remove it again in the next section:

The output should be:

In the previous section, we exceptionally added an ignored file to version control. This was probably a mistake, so let’s remove it from version control again.

Removing files from version control is done with the got remove command. Run:

The output should be:

The D status marker applies to files scheduled for deletion in the next commit. When a versioned file is removed with got remove it is also removed from disk.

We can now commit the deletion of ignore-me as usual:

The output of got commit should be similar to:

Since ignore-me was removed from disk, it is no longer an unversioned and ignored file. Run:

The output should be empty.

When contributing to Git repository you do not have write access to, the repository owner might ask you to send them a patch file.

Game of Trees can generated patch files in the “unified diff” format with the got diff command.

First, let’s make another change to a file in the work tree:

View the change you have made to the work tree:

The output should be similar to:

Commit this change to the repository:

The output of the got commit command should be similar to:

This commit should now be the head commit of the main branch.

So far, we have run got diff without any arguments to inspect uncommitted changes in the work tree. We can also use got diff to view changes that are already present in the repository.

For example, to see the changes in the head commit of the main branch, pass one -c option to got diff as follows:

The output should be similar to the local change above, but with diff headers indicating that the patch is showing the difference between two commits: The main branch head, and the first parent commit of the main branch head:

Passing one -c option always results in a comparison with the specified commit’s firt parent commit.

By passing two -c options, we can view differences between two arbitrary commits. For example, let’s view a patch of all the changes we have made so far since cloning the localrepo.git repository:

The output should be similar to the following:

To obtain a patch file which describres all these changes, we can simply save the above output to a file. Usually, patch flies carry the file extensions .patch or .diff, but this is an arbitrary choice. Run:

We can now send the file localrepo.diff to someone who has write access to another repository, and they will be able to apply our changes there and commit them.

Let’s apply our patch file to a work tree of the firststeps.git repository.

We could use the standard patch command for this task. However, the standard patch command is unaware of the Game of Trees work tree format. When the got patch command is used instead, file additions and removals described by the patch file are automatically recorded in the work tree. Additionally, if the object IDs mentioned in the patch file headers can be found in the local repository, got patch is able to merge files using the diff3 algorithm. The search-replace strategy known from the standard patch command is only used as a fallback. The benefit of this behaviour is that we get merge conflict markers in files instead of .rej (reject) files listing changes which could not be applied.

Switch to your work tree of firststeps.git and apply the patch there:

The output of the got patch command should be:

Status code G indicates that the file alpha was merged using the diff3 algorithm. Files patched using the search-replace strategy would appear with status code M instead.

The files .gitignore and psi were newly added by the patch, and are now already marked for addition with the next commit.

Commit the changes with:

The output should be:

This commit modifies all three files at once. We thus have differences in commit history between localrepo.git and firststeps.git, even though the changes contained within them are the same.

Changes in the work tree can be undone with the got revert command. This command will make all versioned files appear as they did when the work tree was last checked out or updated.

This command needs to be used very carefully because there is no way to bring discarded changes back after got revert!

Schedule a few changes for commit in the work tree, but do not actually commit them. Modify a file, add a new file, and remove another file:

The output of the above got status command should be:

We can run got revert on one file at a time. Try running:

The output should be:

And now alpha should no longer appear in the output of got status. Run:

The output should be:

We can also revert multiple files at once by passing them on the command line. Run:

The shell expands the wild-card argument * to a list of files (alpha, new, and psi) and directories (epsilon, gamma). Because of this, directories appear on the argument list, and our got revert command should fail with an error:

Let’s modify a file in inside a directory as well. Run:

Run got status to verify that zeta is now shown as modified.

Next, we run got revert again, this time in recursive (-R) mode:

The output of got revert should be:

This looks fine at first glance, doesn’t it?

Obtain the current status of files in the work tree with got status:

The newly added file has become an unversioned file again, just as it was before we ran got add.

However, we can now clearly see that the file beta has not been reverted. It is still scheduled for deletion. Since deleted files are not present on disk, the shell wild-card argument * did not add beta to our got revert command line.

Reverting all changes within the current working directory can be done more reliably by passing a path to the current working directory itself. Run:

Here we are passing a dot (.) instead of an asterisk (*), and now beta will also be reverted since it appears in the directory listing of the current working directory.

The output of got revert should be:

Obtain the current status of files in the work tree with got status:

Since got revert will not touch unversioned files, the file new should still be present, and the output of got status will be:

In the previous section we reverted entire files. But sometimes, there is a bad change sitting between several good changes in a file, and undoing just the one individual bad change (or more) would make us happy.

The got revert command has an interactive mode which allows us to select specific changes in files to undo. To try this feature we will need a file which contains more than one line of text.

Generate a file with more than one line of text, and commit it:

Let’s modify a couple of lines in this file:

View the changes made to the manylines file by running:

The output should be similar to:

Let’s assume we wanted to undo the change to line 7 only. Run:

The output should be:

Here, the got revert command displays only the first change on line 2, and then asks whether we would like to revert this change.

Respond by typing:

This will cause got revert to keep the change intact, and move on to the next change:

This time, respond with:

This change will be reverted.

Next, the third and final change should be displayed:

We have already reverted the one change we wanted to revert in this file, so we can stop the process for this file by typing:

This will keep the current change, and any potential later changes, intact.

Now examine the changes with got diff again:

The output should be similar to:

Commit these changes to the manylines file by running:

Bad changes which have already been committed cannot easily be undone directly. Considering that such changes might have been synchronized to other repositories already, attempting to eradicate them completely in all known, or even unknown, clones of the repository is either a difficult or an impossible proposition.

But instead of undoing such changes, we can commit a change which undoes the bad effect of the change. Sometimes, a follow-up fix which gets propagated to all repositories is appropriate. But in some situations, making the same change in reverse will be a more desirable quick remedy.

The got backout command makes it easy to commit the inverse of a bad change. It runs in a work tree and takes either a commit object identifier or a reference name as argument. In both case, a single commit will be undone and presented as a committable change in the work tree. This approach is also known as a “reverse merge” of the bad change.

Let’s try undoing the main branch head commit in the work tree of the localrepo.git repository:

We just made a commit from this work tree in the previous section, and the work tree will likely be in a mixed-commit state as a result. In this, got backout will raise an error:

In order to provide a clean and accurate single-commit representation of the latest repository snapshot for got backout to work with, we need to run:

This will likely not bring any actual changes into the work tree, but simply tweak base commit meta data for all files, and then print:

Still, this was worth doing, because if a work tree happened to be in a state where it was entirely out of sync with the latest repository snapshot, we would likely run into rather strange merge conflicts while trying to reverse-merge a change into this work tree.

With a fully up-to-date work tree, running got backout again should succeed:

The output should be similar to:

Examine the changes which have been merged into the work tree:

These changes undo the effects of our latest change which was committed to the main branch in the previous section.

Commit the result by running:

When the log message template opens in the editor, the log message of the backed-out commit should conveniently be present already, ready for modification or quoting when describing the reasons for and context of undoing this change. Save and exit the editor, allowing the commit to proceed.

The output of got commit should be similar to:

When several files were changed in the work tree, we might want to commit some of those files separately from other files.

Modify two files and add one new file in your work tree of localrepo.git:

The above got status command should print:

Commit just the changes to file psi by running:

The output should be similar to:

Only psi was committed, and the other files should still be in modified and added state as before. To confirm this, run:

The above got status command should print:

This shows that we can ask Game of Trees to commit changes to specific files by passing only the desired files to got commit on the command line. However, we can also stage entire files while leaving other files unstaged, preparing a list of files for got commit to pick up.

Stage the modifications in file alpha by running:

The output of got stage should be:

Only alpha was staged, and the file psi files should still be in added state as before. To confirm this, run:

When a file is staged, its status code is shown in to the second column rather than first column. The above got status command should print:

Staged file content becomes the new base for local changes in the work tree.

View the local modifications in file alpha by running:

The output of the above got diff command should be empty. To view staged changes, we can pass the -s option to got diff. Try:

This shows all staged changes, and the output should display the staged changes for file alpha, similar to:

Modify the file alpha again by running:

View the local modifications in file alpha by running:

This time we should see changes in the work tree, relative to the staged version of file alpha, similar to:

Commit the staged changes by running:

Your log message editor buffer should be preloaded with comments that display staged files only:

The output of got commit should be similar to:

The file new which was not staged was not made part of this commit and should still appear as locally added in the work tree. To confirm this, run:

The output should be:

Revert the addition of file new for now, by running:

When several changes appear in a single file, there might be more than one semantic change contained within the file. For example, a subset of the changes might be about fixing a bug, while another change fixes an unrelated typo in a comment.

By staging specific files or changes within files for commit with the got stage -p command, we can prepare a specific set of changes which got commit will pick up, while leaving all other file modifications in the work tree.

Modify two lines in the manylines file created earlier:

Examine the local changes in the work tree. Run:

The output of got diff should be similar to:

Similar to got revert, the got stage command supports a -p (patch) option which provides an interactive menu to stage parts of a patch. Run:

The first section of output should be:

Avoid staging this changes by responding with:

The next section of output should be:

Do stage this changes by responding with:

The got status command should now report M (modified) status in both columns for file manylines. Run:

The output should be similar to;

The double M indicates that we have both staged and unstaged modifications in file manylines.

Now examine staged changes with:

The output should be similar to:

Examine the local changes, which are now shown relative to the staged changes, with:

The output should be similar to:

Commit the staged changes by running:

Keep the local modification in manylines intact for the next section.

Staged changes can be merged back into the work tree with got unstage. This is a 3-way merge operation, which means that unstaging changes may conflict if local modifications exist on top of staged changes. If the staged file was not modified after staging then the merge result is virtually guaranteed to be free of conflicts.

The file manylines should already contain local modifications:

The output should be:

Stage changes for the file manylines by running:

The output should be:

Add another local change on top of the staged changes:

Verify the local changes by running:

The output should be similar to:

The file manylines now has both staged and local modifications:

The output should be:

Unstage the staged changes by running:

You will likely get a merge conflict, in which case the output looks like this:

The manylines file is now in conflicted status:

The output should be:

If you did not get a merge conflict, don’t worry about it. You can skip the conflict resolution steps below.

View the differences stored in the manylines file:

The output should look similar to:

Edit the file and resolve the conflict in whichever way you prefer.

For example, we could accept both changes to resolve the conflict, and run:

The output would then be similar to the following:

Commit the changes by running:

Game of Trees provides several commands which manage references in the Git repository. The most general of these if got ref, which operates on reference in a Git repository and can provide a full view of all references. The got ref command will operate on references without restrictions but also without any safe-guards.

Other commands operate on references in the context of specific operations and will enforce conventions which make sense in a specific context. These commands usually restrict themselves to one or more reference namespaces. For example, the got branch command uses references in the refs/heads and refs/remotes/ namespace only.

In its simplest form, we can use the got branch command to list the current branch checked out in a work tree. Try it in a work tree of the localrepo.git repository;

If you have followed the tutorial, the output should be:

The command can also be used to list all known branch heads, local or remote:

The output should be similar to:

Above, main refers to the local branch refs/heads/main, which is marked with an asterisk * because main is the current branch of our work tree, and this work tree is fully up-to-date. In mixed-commit work trees, a tilde ~ will be displayed next to the current branch instead.

The origin/main branch refers to refs/remotes/origin/main, as cloned from the default remote “origin” repository remoterepo.git. We also see the remote’s HEAD value being cached, which is useful in case the default branch name is changed remotely.

The output of got branch -l is a simplified view of the output shown by the equivalent got ref command. Try:

The output should be similar to:

A new branch can be created by passing the desired name to the got branch command. Try:

The output should be:

The name we pass is looked up in the refs/heads/ namespace. We cannot accidentally change or overwrite an existing branch while using got branch. Whereas the more low-level got ref command could accidentally overwrite an existing reference if we are not careful.

Create a new branch called counting:

The output should be:

By default, new branches are based on the head commit of the current branch checked out in the work tree. If got branch does not run in a work tree, the new branch will be based on the head commit of the branch resolved via the repository’s HEAD reference.

The new branch should now appear in the branch listing:

Currently, both branch heads are still equivalent. Let’s commit some changes to our new branch. For example, we could create 3 new files as follows:

The output of the above got commit command should be similar to:

The head of the counting branch has moved forward, but main is unchanged. We can change main independently. While we could check out one dedicated work tree per branch, for now let’s switch Our current work back to the main branch ;

The output of the above got update command should be:

The new files added to the counting branch were removed again. Change a file on the main branch:

Now both branches have diverged. We can inspect their independent histories with git log We limit it to traversing just 2 commits via the -l option:

This should show the head commit of the work tree’s current branch, main, followed by its parent commit. The output should be similar to:

Next, ask got log to start traversing history at the commit which can be resolved via the counting branch reference:

This time we should see the branch head commit of the counting branch, based on the same parent commit as main, similar to:

Both changes are sitting in parallel to one another. This situation is quite similar to an earlier situation we saw in this tutorial, where a remote repository contained another change we had just fetched into the local repository but had not merged yet. Only, this time, both references involved are in the same reference namespace, namely refs/heads/.

We could use got merge again to reconcile the branches as we did earlier, but let’s try out the rebase strategy instead this time.

Rebasing the counting branch on top of main requires a work tree of the main branch, which we already have. The work tree must be fully up-to-date and contain no local modifications, run:

The output of the above got status command should be empty.

When rebasing, the command which brings changes from a rebased branch back into the branch it forked off from is called got integrate rather than got merge. Running this command at this point should raise an error:

There should be an error indicating that counting needs to be rebased first:

Let’s try to rebase the counting branch now:

The output should be similar to:

The changes in the rebased commit did not overlap with changes we had sitting on the main branch. Thus, there was no merge conflict. If there were merge conflicts, we would have to resolve them and continue the rebase operation with got rebase -c, in the same was as was done earlier with got merge -c.

Running got log at this point should reveal that the branch head of counting now has a different parent commit, namely the head commit of main:

The output should be similar to:

Add some more numbers to the counting branch:

Examine the history of counting, walking up to 3 commits this time:

The output should be similar to:

As long as the changes on the counting branch are sitting on top of the head of the main branch, we can integrate our changes into the main branch.

First, switch the work tree back to the main branch;

The output should be similar to;

Integrate the counting branch by running:

The output should be:

View the history of the most recent three commits again:

The output should be similar to the following. The branch heads are now equivalent again:

This cycle can be repeated over and over, and with as many branches as we would like, to develop specific changes in isolation.

For now, we can delete the counting branch again. Run:

The output should be similar to:

Game of Trees keeps backups of all rebased branches, allowing us to view the branch as it appeared before rebasing, and potentially restore the branch to an older state.

To see a list of backed-up rebased branch, run:

The output should be similar to:

This gives is all information needed to view this change as it appeared before being rebased. Given the above commit identifiers, a suitable command to see the changes would be:

We could even recreate the counting branch in its earlier state if we wanted to, by running:

The above got log command should display the counting branch back in its original state:

This can be useful when a rebase didn’t work out as expected, or was performed in error.

When backups of rebased branches are no longer required, they can be removed by running:

This will remove references in the refs/got/backup/rebase/ namespace, where the old heads of rebased branches are preserved.

Editing branch history can be useful in order to transform a “messy” commit history in a revised and more appealing commit history. This is usually done only for changes which are still in draft state and have not yet been merged into the main branch. More generally, if anyone is already building other changes on top of a published or privately synchronized part commit of history, editing this part of history is usually unwise.

In our running example, the localrepo.git repository was last synchronized with the “origin” repository remoterepo.git several commits ago, and all changes we have added on top is only visible in our own repository. We can thus freely edit this history before sending our contributions to the remoterepo.git repository.

In a work tree which contains the main branch of localrepo.git, Examine the commit history of localrepo.git, up to and including the cached remotes/origin/main remote branch head. We can enable the summary mode of got log via the -s option to shorten the output a bit. Run:

The output should be similar to:

In this example, there are 16 commits which could in theory all be edited before sending them out.

For example, let’s try to edit the file psi across our local history to make it much prettier. First, we need to ensure that our work tree is clean. Run:

If the output is not empty, commit or revert outstanding changes, and remove any unversioned files.

Starting with a clean work tree, we keep our work on the main branch but back-date our work tree’s base commit to the commit which is the parent of the bottom-most commit being edited. In our case, we can run:

The output should be similar to:

Our work tree is now based on the commit which equals the branch head of origin/main, and we can edit commits between origin/main up to, and including, main by running:

The got histedit command opens an editor window which displays a “histedit script”, showing the part commit history we can edit in chronological order (unlike got log which, displays commits in reverse chronological order). We can edit the histedit script in our editor to let Game of Trees know how history should be changed.

The editor window should look similar to the following:

By default, the histedit script picks all commits as-is, meaning it creates the same history as the original, except that timestamps and perhaps the author meta-data stored in commits can be adjusted.

Let’s do something more interesting: Locate all changes which modify the file psi, and mark them for editing by replacing pick with edit (or just e) at the beginning of the line.

If you are unsure which commits edited the file psi, run the following in another terminal window:

And the output of got log should list all relevant commits:

In the example below, the corresponding 3 commits are marked for editing:

Save the script, and exit the editor. The got histedit command will stop at the first commit marked or editing and allow you to make arbitrary edits in the work tree:

The work tree now contains an interrupted histedit operation, which allows for arbitrary changes to be made part of the commit being edited, including the addition and removal of files, and so on.

Run:

to see the status of files in the work tree. The output should be:

The change which has been merged into the work tree matches the original change which introduced file psi. For example, when running

the output should be similar to:

We can finally begin our quest to make psi a prettier file:

Examine the changes once more with:

If you are happy with the result, ask got histedit to continue editing history:

A text editor will open, allowing you to adjust the log message of the modified commit as needed. Edit the log message, save, and exit the text editor.

This time, got histedit should produce output similar to:

This time, got histedit stops because of a merge conflict in file psi. It would have stopped anyway because we marked all commits which change psi for editing. The merge conflict is a result of changing the contents of psi in ways that conflict when the diff3 algorithm tries to merge changes from later commits into this file.

Open the file psi in a text editor, which should look something like this:

Resolve the conflict by making the content of psi very pretty, for example:

Then save and exit the editor, and ask got histedit to continue once more. Edit the log message of the edited commit, and save and exit the text editor again.

Again, another merge conflict in psi might occur, similar to:

Resolve this conflict to your liking, and continue editing history again:

Eventually, we will have passed all commits which touched file psi, and the histedit operation will conclude:

The modified changes to file psi are now visible in commit history. Run:

The output should only show the changes from the edited history of psi, similar to:

As seen in comments at the top of the histedit script, we are not limited to just editing file contents. We can also fold two or more commits into one commit with the fold command, drop commits from history with the drop command, and only edit log messages in history with the mesg command.

The got histedit command provides some shortcuts: If all you want to do is fold commits (“squashing” in Git’s vernacular) then got histedit -f is the equivalent of replacing all pick commands except for the final pick, with fold commands. The same shortcut works for drop via got histedit -d, and for mesg via got histedit -m.

If you ever find yourself in a bad spot while editing history and change your mind, an interrupted histedit operation can be aborted with got histedit -a.

The previous history of file psi is not really lost yet. Just like in the case of got rebase, the got histedit command keeps backups of the previous states of history. To see such backups, run:

The output should be similar to:

Using this information, we can view the history of file psi from before we started editing it:

The output should display the previous version of the psi file’s history, similar to:

As with rebase, backups can be removed with the -X option if they are no longer required:

The output should be similar to:

Creating a release branch is no different than creating any other branch. For example, we can create a 1.x. branch in localrepo.git as follows:

The output should be:

Tag objects are created with the got tag command. Let’s say we are happy enough with the current state of our 1.x release branch, and want to make our first 1.0 release from it.

We could create a tag in our work tree where the release branch is checked out by running:

We can also create one directly in the repository if we’d like to:

In either case, a text editor will open and allow us to enter a tag message. The editor window should look similar to this:

Enter a simple tag message such as "initial release 1.0", then save and exit the text editor. The got tag command should print something similar to:

We can list all tags and their tag messages by running:

The output should look very similar to the output of got log:

And like with got log, there is also a summary mode:

The output should look similar to:

Some projects prefer to fix problems in the oldest supported release first, then merge the fix towards newer releases and eventually into the main branch. other projects work the other way around, fixing problems in the main branch first. For our purposes, we will use the second approach. The steps to follow are indeed similar enough in either case that once you have seen one of the two approaches, you should be able to easily handle either of them.

Assuming we are fixing problems in the main branch first, switch your work tree of localrepo.git to the main branch, and commit three separate three changes. Here, we use the -m option of got commit to pass a log message via the command line, which saves us from having to use a text editor to write log messages:

There are now three separate changes on the main branch. Imagine that only the second fix is critical enough to become part of the next release. In this case, we would merge just this particular change into the 1.x release branch.

To merge a specific change, we will need to select a specific commit on the command line.

There are several ways to “address” a change we committed. We could pass a literal or abbreviated commit object ID, or we could use the Game of Trees command line keyword syntax to address the change relative to a branch head.

Let’s try out the keyword feature with got log first, before merging anything:

This should print the third fix, i.e. the head commit of main, which is not the fix we want:

We can append a colon and a negative number after the branch name in order to have our commit selection step further down in history. Try:

This shows the first fix, which is still not the one we want. We want the second. The index of the branch head commit itself is zero, which means the head commit’s parent commit can be addressed with index -1:

There it is, this is the fix we want to merge.

In order to merge an individual change, we can use the got cherrypick command. The metaphor being that we can use this command to pick only the best cherries from the tree, or rather from the pile of changes we have collected in our repository.

Switch your work tree to the 1.x branch and merge the second fix using they syntax discussed in the previous section:

The output of the got cherrypick command should be:

Given the above commit identifier, the following command would be equivalent to the one we just used:

And of course, the commit identifier could be abbreviated, provided the abbreviation is unique.

As previously seen with got backout, the change is now sitting in our work tree as a local change. Run:

The output should be similar to:

At this point, we can make any required adjustments needed to apply the change in the context of our release branch, and test our changes. We could even run got cherrypick again to merge additional changes, and use commands which modify work tree state such as got add or got remove, or undo parts of the change with got revert -p. Staging changes and creating multiple commits would also be possible. But it is usually good to keep things simple, and merge and commit just one change at a time.

When we commit the change, the log message editor will be prefilled with the log message of the original change we have cherrypicked into the release branch. Run:

The text editor buffer should look similar to;

The log message must be changed in some way for got commit to succeed. For example, mention that the change is being backported to the 1.x branch, then save file and exit the editor. Then we should see the usual output from got commit:

Our 1.x release branch now contains one additional change, while the other two changes on the main branch are not present here. Run:

The output should be similar to:

We could keep picking more changes from the main branch in this way, and eventually tag the next release version 1.1.

So far, we have been using the got log and got diff commands to view changes, but those tools are limited in scope and usually assume that we already know which commit we want to look at.

The got blame command can be used to annotate the lines of text in a particular file with commit IDs which last changed the line.

Try it out on the manylines file in the localrepo.git repository.

The output should be similar to:

Each line is annotated with its line number, commit ID, commit date stamp, and author. We can see that all lines in this file can be blamed on Tom.

We can now pass commit identifiers to got log or got diff as we are already used to in order to find out more about the change which introduced a particular line. With the above example output in mind, the following got log command will give us the log message of the commit which introduced line 17:

The output should match a usual got log change log entry:

Game of Trees provides an interactive Git repository browser for terminals, called tog, which is similar but not equivalent to the third-party tig tool as known from the Git tooling ecosystem.

The tog command should be installed by default with Game of Trees. if started in any Git repository. When started in a Game of Trees work tree, tog will show local changes sitting in the work tree as well as data in the repository.

Start tog in your work tree of localrepo.git:

With the work tree still switched to the 1.x branch, the default view of tog should look something like this:

The default view of tog is the equivalent to got log. Use the arrow keys or vi-style navigation to select a particular commit.

Pressing Enter on a commit will open a new view which is equivalent to got diff. Depending on the horizontal size of your terminal, tog might display a split-screen showing both the log and diff view side-by-side, or it might display a full-screen diff view. In either case, press q to exit the diff view again.

Pressing R opens the list of references found in the repository. A log view which displays the corresponding branch can be opened by pressing Enter on a particular reference.

In a log view, pick any commit and press T. This opens a tree view which displays the snapshot recorded by this particular commit. Directories can be entered by pressing Enter, and a view equivalent to got blame can be opened by passing Enter on a file. For good results, try the blame view of the manylines file, where pressing Enter on a particular line will open a diff view for the corresponding commit.

In any view, pressing F1 or H will display the available key bindings.

A manual page for tog should already be installed, and can also be viewed online at https://gameoftrees.org/tog.1.html

if you still have time left, try taking tog for a spin on some of real world repositories, guided by the built-in help feature and the manual page.