Git is a distributed version control system which allows you to track all the changes to your project. It can be used for all sorts of projects: software development, Transcendence Mods, or even a book. With version control you have a record of all the changes you’ve made to your project (for example see the Transcendence commit log) and can easily undo changes if you’ve made a mistake.
GitHub is the most popular git repository hosting service with an easy to use web-based interface and several collaboration features (issue tracker, wiki, web hosting, etc.) you can even edit files directly in the web interface.
For a complete introduction to git you can read the Git book which even includes a chapter on GitHub. Other useful links are the Git reference guide and GitHub Help pages.
Command line or GUI
There are many different git clients available and several IDEs have built-in git integration.
The official Git for Windows includes both a command line client (using the BASH shell so you also get grep, sed, aux, diff, and lots of other useful tools) and a GUI.
Microsoft Visual Studio has built in git integration
GitHub Desktop is a GUI client for macOS and Windows which includes basic git functions and some GitHub specific functionality like creating Pull Requests directly in the GUI.
- NOTE The default download is now “Desktop Beta” the link for the old GitHub Desktop is at the bottom of the page.
- Includes a version of the official client (v2.11) with Power Shell integration.
- Some GitHub functions (e.g. create pull requests) are done via web-browser rather than in client.
- Does not include copy of official client, but will download the latest version when needed.
- Desktop Beta appears to only support git CMD (i.e. cmd.exe shell, no BASH or PowerShell)
This guide will assume you’re using the official command line client. All the basic operations should be possible in a GUI client or one integrated into a text editor / IDE.
Getting started
1) Fork your own copy of the Transcendence repository
Go to https://github.com/kronosaur/Transcendence
Click the Fork button (you will need a github account)
2) Install git
Download and install git from https://git-scm.com/
Open Git bash, set your git username and email (use the same as your github account)
Code: Select all
$ git config --global user.name "Mona Lisa"
$ git config --global user.email "[email protected]"
$ git config --global core.editor notepad
3) Clone the repository to your local computer
Create a directory for your Transcendence development work, then right-click on it and select "Git bash here"
Enter the following commands in the shell (replace <username> with your username):
Code: Select all
$ git clone https://github.com/<username>/Transcendence.git
$ cd Transcendence
$ git remote add upstream https://github.com/kronosaur/Transcendence
4) Exploring the Transcendence code
If you want to work with the C++ code then you'll also need to fork and clone Alchemy and Mammoth the core engine and libraries used by the Transcendence game. However, if you just want to work with the XML code you only need the Transcendence repository.
Note - if you want to compile the latest version of Transcendence, but do not plan to submit any code changes you can clone directly from the kronosaur repositories:
Code: Select all
$ git clone https://github.com/kronosaur/Alchemy
$ git clone https://github.com/kronosaur/Mammoth
You will find the XML in the TransCore directory. This is compiled into the Transcendence.tdb file when the game is released; however, you can also run the game directly with the xml files. Just put a copy of Transcendence.exe into the Game directory and it will read the resources from ../TransCore instead.
Git Basics
You should now have access to three copies of the Transcendence repository
- The one on your computer (local)
- Your fork on github (origin)
- The official kronosaur repository on github (upstream)
The basic workflow for contributing a change to the Transcendence code is:
- fetch or pull from upstream to local (to get George’s latest work)
- Make your changes and commit them to local
- push from local to origin (put your changes on GitHub)
- create a pull request on GitHub
- George can then pull your changes from your repository and merge them into kronosaur/Transcendence
Lets start by “accidentally” deleting a file. Remove TransCore/Antarctica.xml and run git status:
Code: Select all
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add/rm <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
deleted: TransCore/Antarctica.xml
no changes added to commit (use "git add" and/or "git commit -a")
Code: Select all
$ git checkout -- TransCore/Antarctica.xml
Code: Select all
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: TransCore/PlayerShips.xml
no changes added to commit (use "git add" and/or "git commit -a")
Code: Select all
$ git diff
diff --git a/TransCore/PlayerShips.xml b/TransCore/PlayerShips.xml
index bf577516..24c30985 100644
--- a/TransCore/PlayerShips.xml
+++ b/TransCore/PlayerShips.xml
@@ -86,7 +86,7 @@
sortOrder= "10"
largeImage= "&rsZubrinLarge;"
initialClass= "true"
- startingCredits= "10d100+1500"
+ startingCredits= "10d100+1500000"
/>
</ShipClass>
Code: Select all
$ git add TransCore/PlayerShips.xml
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: TransCore/PlayerShips.xml
Code: Select all
git commit -m "Give the sapphire more starting credits"
If we check git status again we see that our local branch is now one commit ahead of our GitHub repository (origin), and git helpfully tells us the how to push our commits to GitHub:
Code: Select all
$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
Branches
Example
As a simple example I'm going to address this issue: Revelations missile-ship can hold off entire stations with only its gun.
1) Create a new branch for your change
Open git bash (right click on your Transcendence git folder and select "Git bash here") and enter:
Code: Select all
$ git checkout -b revelationsGun master
You can omit the starting point (master), in which case git will base the new branch on the current HEAD
2) Make your changes to the source code
3) Check they work by running Transcendence
Note - you can put a copy of Transcendence.exe in the Game folder and it will read the xml resources from ../TransCore
4) Check the changes in git:
Code: Select all
$ git status
On branch revelationsGun
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: TransCore/EncountersVol01.xml
no changes added to commit (use "git add" and/or "git commit -a")
Code: Select all
$ git diff
diff --git a/TransCore/EncountersVol01.xml b/TransCore/EncountersVol01.xml
index 463207dd..965a67e0 100644
--- a/TransCore/EncountersVol01.xml
+++ b/TransCore/EncountersVol01.xml
@@ -4690,7 +4690,7 @@
<Devices>
<Device deviceID="&itNAMIMissileLauncher;" minFireArc="300" maxFireArc="60" posAngle="0" posRadius="16"/>
- <Device deviceID="&itFlenserCannon;" secondaryWeapon="true" omnidirectional="true"/>
+ <Device deviceID="&itOmniPartisanCannon;" secondaryWeapon="true"/>
</Devices>
<Maneuver
Code: Select all
$ git add TransCore/EncountersVol01.xml
$ git commit -m "Change Revelations weapon to RK15"
[revelationsGun 78615948] Change Revelations weapon to RK15
1 file changed, 1 insertion(+), 1 deletion(-)
Code: Select all
$ git push
Code: Select all
$ git push
fatal: The current branch revelationsGun has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin revelationsGun
Code: Select all
$ git push --set-upstream origin revelationsGun
Go to your github repository (e.g. https://github.com/gcabbage/Transcendence )
and navigate to the "Compare & pull request" or "New pull request" buttons
You can add links to any relevant ministry tickets in the comments box.
See example pull request