Using Git

Disclaimer: This is not a general Git introdution. Instead this page is geared towards people who only need Git in combination with ThinStation.

Introduction

Git is the version control system used to develop ThinStation. It also allows you to switch to a different version of ThinStation with ease.

You can use Git to efficiently “save” your ThinStation configuration files. This gives you the opportunity to return to a known working state if your development is stuck. It also allows you to elegantly migrate your personal configuration to a new version of ThinStation.

Git related terms and concepts

Linear development

When you initially cloned ThinStation you created a “working directory”. It contains all ThinStation related files and is under Git’s control, i.e. Git watches over all files.

If you changed (files in) the working directory and want to save certain changes, it’s time to create a “commit”. That’s a recursive snapshot of all tracked files in the working directory. Only carefully chosen changes (compared to the previous snapshot) will be a part of the snapshot.

Example: To persist changes in the files build.conf and thinstation.conf.buildtime type

git add build.conf thinstation.conf.buildtime
git commit

If you continue development you will create more commits.

git add …
git commit
git add …
git commit

This leads to a linear line of development:

o--o--o  (a series of commits “o”)
         -> direction of development ->

Branched development

The above is a simple example for a branch. Each branch has a unique name refering to the newest commit in a series. In ThinStation branches are used for example to develop different major versions of the framework. That’s why you cloned a certain branch from the ThinStation repository (e.g. 5.5-Stable). Let’s call these branches “system branches” for clarity’s sake.

o--o--o  5.5-Stable (a system branch)

In addition to system branches you can create personal branches to store tuned configuration files. We will call them “config branches” here. A config branch starts at a certain well defined commit, typically the newest in a system branch. This reflects the fact that you based your work on top of ThinStation.

git checkout -b mybranch
git add …
git commit
git add …
git commit

leads to

o--o--o  5.5-Stable
       \
        o--o  mybranch (a config branch)

Note that your own “local” branching does not affect system branches at all. “Official” ThinStation development goes on, i.e. system branches continuously grow by new commits. To locally see the latest changes to ThinStation you have to “fetch” them:

git fetch
o--o--o--o--o--o--o  5.5-Stable
       \
        o--o  mybranch

In such a situation you will want to update your config branch to be based on the latest system branch commit. Git calles this a rebase:

git checkout mybranch
git rebase 5.5-Stable
o--o--o--o--o--o--o  5.5-Stable
                   \
                    o--o  mybranch

To avoid problems afterwards, it is best to reset the build environment

./setup-chroot    # entering
clean_chroot      # cleaning
exit

before you start with the rebase.

Sometimes you want to tranfer a commit from one branch to another without merging the two branches. Enter (checkout) the destination branch first. Then

git cherry-pick commit-ID

This is called “cherry picking” and will create a new commit by default.

Example use of config branches

Let’s assume you have a powerful development workstation but pretty slow thin clients. For this reason you may prefer developping and testing your software configuration within a virtual machine. Only after everything is working as expected in the virtual machine you switch to using real hardware (thin clients).

This could be achieved like this:

1. Start by creating a new config branch (e.g. called vbox) on top of the latest ThinStation stable system branch.

    o--o--o  5.5-Stable
           \
             vbox
   

2. Depending on your desktop virtualization software (VMware or VirtualBox) tune to the appropriate machine profile and make a first commit. Then develop until you are satisfied with the user facing software configuration. Make commits whenever appropriate.

    o--o--o  5.5-Stable
           \
            o--o--o--o vbox
   

3. Now create a second config branch (e.g. called myclient). Switch the machine profile and test. If necessary fix remaining issues. Then commit your changed files.

    o--o--o  5.5-Stable
           \
            o--o--o--o vbox
                      \
                       o--o myclient
   

Which is equivalent to:

    o--o--o  5.5-Stable
           \
            o--o--o--o--o--o myclient
                      \
                       vbox

4. If you need to change your software configuration, switch to the branch vbox before developing.

    git checkout vbox     # note the missing -b
    git add …
    git commit
    o--o--o  5.5-Stable
           \
            o--o--o--o--o--o myclient
                      \
                       o vbox
   

5. Finally cherry-pick (i.e. transfer) the most recent commit into myclient:

    git checkout myclient
    git cherry-pick vbox