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.

Installation

The first step is to install Git, which is available from https://git-scm.com/. 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 https://tortoisegit.org/download/. 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: https://github.com/BlackBoxCenter/blackbox.git 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 right to it. 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. 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".

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.

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). 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.

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.

Retrieved from "http://wiki.blackboxframework.org/index.php?title=How_to_develop_with_Tortoise_Git&oldid=386"