Version control with Git
We use Git for version control, with the shared Ampersand repository located at Github. This chapter provides the information to get to the repository and clone it for having your own local copy.
We use Git for the following purposes:
- 1.to have a shared repository that contains our source code;
- 2.to work on different features in parallel without interference and without having to wait for each other;
- 3.to prevent loss of code because multiple copies exist on multiple sites;
- 4.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:
Understanding the basics of Git is essential for anyone working on Ampersand. Fortunately, there is good help available:
- 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, stating that you want/need write access to the Ampersand repo or any other repo in the project.
- 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 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?)
- 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).
- 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"
Checking out means to create your own local copy of the repository. By default, the Git directory in your home directory will be used for all local repositories. You have various options to do this
- Use TortoiseGit for integration with your file system
- 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
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.