How to develop with Tortoise Git

From BlackBox Framework Wiki
Jump to navigation Jump to search

If you work under Windows and if you do not want to learn the git command line tools there is an option, use Tortoise Git. Tortoise Git is a powerful GUI based git tool that is integrated nicely with the Windows Explorer. It is known to work reliably and it offers all the git functionality without forcing you to use or learn all of it. It is also easy to install a diff tool for BlackBox .odc files for Tortoise Git. Without a diff tool, it is not possible to use git effectively.


The first step is to install Git, which is available from During the install process it is acceptable to take default choices.

The next step is to download and install Tortoise Git for Windows, which is a graphical front-end for Git. This is available from This is only done once. See Diff for setting up a diff tool for BlackBox .odc files.

Cloning a repository

Git always works on a local repository and so does Tortoise Git. For getting a local repository you must first clone the remote github repository to your local machine.

  • Click Mouse-Right on a directory that does not already contain a .git folder and activate the "Git Clone ..." menu item.
  • fill in the form: URL:
  • Directory: a default is presented. It is recommended to append the issue number. This helps a lot to stay organized in particular if you want to work on several issues in parallel. You can also add a mnemonic. An example directory for issue-#140 is "<path>\blackbox#140 unwrap".
  • Branch: Check this option and specify the branch name in the field to its right. This is the branch name in the github repository, for example "issue-#140". If the branch does not yet exist, you have to create the branch first on github (see How to develop with Git for instructions.). Note: Without checking the "Branch" option the cloned repository would be working on "master". This bears the danger that changes can easily and unintentionally be pushed back to master rather than to an issue branch. Therefore, never clone the "master" branch.
  • Press "OK".
  • After a few seconds of file transfer you should have a blue "Success" message, and the specified directory should be populated.

Running BlackBox with the clone

The cloned directory contains only the sources and resources of BlackBox. It does not contain any binaries. Therefore, after the clone has been created, you must set up an existing BlackBox installation to /USE the clone. This can be done by creating a link to the BlackBox.exe file and editing the properties manually or, more efficiently, by copying a prepared batch file into the clone's root directory. The batch file can be reused for several such directories. The contents of the batch file is:

start /b C:\"Program Files"\"BlackBox Component Builder 1.7"\BlackBox.exe /USE .

You may have to adapt the path, though, and you can add more options, e.g. /NOSCROLL.

Give the batch file (plain ANSI from a simple editor like Notepad) a name like "Run.bat", and save it into the Git path (eg <path>\blackbox#140 unwrap) where it is run by double clicking it.

Committing changes, etc.

After starting the link or the batch file, BlackBox will store any changes into the cloned repository. You can commit the changes by means of the context menus offered by Tortoise Git. Mouse-Right on a folder or file shows an extended Windows context menu and allows you to see a log, a diff, or to commit changes (look also into submenus). The Commit command button can be found on the bottom line of the "TortoiseGit -> Diff", "TortoiseGit -> Diff with previous version", and "TortoiseGit -> Check for modifications" dialogs. When committing changes follow the conventions for the first line of the commit message as specified in How to develop with Git#Bi-Directional Traceability. In particular, end the first line of the message with a string like "Refs: #140.".

Pushing back changes to github

Git commits any changes locally and so does Tortoise Git. After the work on the issue has been finished the context menu item Push... can be used for pushing back the locally stored sequence of commits to the related github branch.