Version control with Git
We use Git for the following purposes:
to have a shared repository that contains our source code;
to work on different features in parallel without interference and without having to wait for each other;
to prevent loss of code because multiple copies exist on multiple sites;
to have an accurate registration of changes, their authors, and the time each change has occurred.
We maintain and use the following repositories at Github:
Repo | purpose |
​Ampersand​ | contains the source code of the Ampersand compiler up to the point that all the regular docker images can be generated from this repository. |
​ampersand-models​ | contains a collection of Ampersand models, which are meant for reuse by the public at large. |
contains language support for VS-code, such as syntax coloring, code snippets, and the like. | |
​Publications​ | This repo is meant for collaborative writing of journal and conference papers about Ampersand. |
​Prototype​ | contains JavaScript source code of the prototype front-end and back-end generators and runtime code. |
​documentation​ | contains the source code of the documentation of Ampersand on GitBook. |
​TheToolsWeUse​ | contains the source code of the documentation on GitBook of tools used to create Ampersand. |
​RAP​ | contains the source code of RAP, a tool that lets you analyse Ampersand models, generate functional specifications and make prototypes of information systems. It is the primary tool for students of the Open University of the Netherlands in the course Rule Based Design. |
​MirrorMe​ | contains the source code for an argument assistance system. It is based on defeasible reasoning along the lines of Toulmin and Hohfeld. |
​sentinel​ | (obsolete) Software for automated testing the Ampersand software. Today, most of our testing is done by means of Travis-ci. Before that we heavily used our own sentinel to warn about bugs. Today, Sentinel is only used for issues with known bugs. Things that are known to break, and we didn't find time to solve them. |
​webFiles​ | contains all kind of consolidated documents that are related to Ampersand in some way. They are stored here to ensure that we have stable URLs to these documents, so we can hyperlink to them wherever appropriate |
Understanding the basics of Git is essential for anyone working on Ampersand. Fortunately, there is good help available:
​The help at GitHub​
If you want write access to the Ampersand repo, create yourself an account at GitHub, if you don't have one already. You don't need that if you just want to read.
Ask one of the administrators of Ampersand to add you as member to the team if you want/need write access to the Ampersand repo or any other repo in the project.
If you need a local copy on your own computer, install Git for Windows or Git for MacOS to stay abreast with the latest version.
When installing for Windows:
Accept all defaults, except:
4th screen check "Windows Explorer integration" / "Simple context menu" / "Git Bash here"
6th screen "Use Git from the Windows Command Prompt"
Git works from the command prompt. There are however some tools that make life easier when you work with Git. Not necessary, but very much appreciated.
Install TortoiseGit to use Git in your Windows Explorer.
Accept all defaults
Install SourceTree to visualize the history in the most popular Git client.
No global ignore, further everything default
When at Add an account, select GitHub and supply your credentials.
Install KDiff3 to get help in merging conflicts. To avoid KDiff3, you can merge conflicts from your editor or IDE as well.
To select KDiff3 in SourceTree, go to SourceTree / Tools / Options / Diff and select KDiff3 for External Diff Tool and Merge Tool.
Pin Git Bash to Start menu to use Git from a command line interface.
When you use excel-files (*.xlsx and *.xls), you can extend git to handle these files properly with ExcelCompare. This works for command-line git on Mac. Similar extensions exist for Windows (TBD: which?)
To avoid typing a GitHub password for every commit you make, install an SSH-key. Here is the short version:
Generate a SSH Key
Start / All programs / Git / Git GUI: Help / Show SSH Key
Press Generate Key. You can supply a pass phrase, but that's optional. You should of course keep it for yourself. (it is in $home/.ssh/id_rsa). When you use a pass phrase, you will have to supply it now and then.
Access to repositories of AmpersandTarski (GitHub).
Go to your personal settings​
press Add SSH Key
Title: add a description of the machine you currently work on (eg. "Windows Laptop Stef")
Key: past your generated key
Press "Add Key"
By default, the Git directory in your home directory will be used for all local repositories. The easies way is to use SourceTree for manipulating repo's.
It is also pretty easy using Git Bash:
cd git
git clone git@github.com:AmpersandTarski/Ampersand.git
TortoiseGit
First time, you have to configure ssh:
Start / All Programs / TortoiseGit / Network:
At "SSH Client" fill in: C:\Program Files (x86)\Git\bin\ssh.exe
The Ampersand repository at Github contains the authoritative source code of Ampersand.
The master branch is used for releases only. @hanjoosten is currently the primary guardian of the release process.
The development branch is used only to commit developments that are ready to be tested by the Ampersand inner-circle.
Every developer develops on his or her own branch(es). Typically these are spawned from the development branch.
You are done with this page once you have your local copy of the Ampersand source code on your own computer, under Git. Do this only if you want to change the Ampersand software; not if you only want to use Ampersand.
​
