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.

The last line changes the default editor for commit messages to notepad instead of vi (if you can use vi you probably don't need this guide). For more details, e.g. how to use Notepad++ as the commit editor see the Git Book

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

The upstream remote is needed so you can get George's latest updates from the kronosaur repositories

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:

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

Making changes

Lets start by “accidentally” deleting a file. Remove TransCore/Antarctica.xml and run git status:

The change (file deleted) is currently listed as a “Change not staged for commit” and git is giving us two options add it to the current commit or discard to current changes. So we can restore the file using git with:

Our change has now been staged ready for the next commit. If we were to delete PlayerShips.xml and restore it with git checkout it would keep the change to startingCredits (we can unstage by using the git reset command). We can continue making changes and adding them to the current commit with git add. To see all the changes in the staging area use can use git diff --cached and finally we can commit it with:

I find that the GitHub Desktop works fine with the Kronosaur/master repository branches; just select the local master, then click Compare, select Kronosaur/master, then click Update from Kronosaur/master. What issues do you have with the Desktop?

I find that the GitHub Desktop works fine with the Kronosaur/master repository branches; just select the local master, then click Compare, select Kronosaur/master, then click Update from Kronosaur/master. What issues do you have with the Desktop?

Mainly it seems to generate a lot of unnecessary "merge remote-tracking" commits e.g. in https://github.com/kronosaur/Transcendence/pull/51 4 of the commits look like they were generated by the desktop sync/update button. At the moment they're a just a minor cosmetic annoyance, but if we get more contributors it could make the commit history and network graph much harder to follow.

However, I have only tried the github client briefly - it seemed to create merge commits where the offical git client just does a fast-forwards merge... I'll probably try it a bit more as I update the guide though in case it's just a configuration option I haven't found

The merge commits from that pull request were from some mismanagement on my computer. I have found out how to remove them using the rebase command. Personally, I use GitHub Desktop because it provides a good GUI to view and prepare commits, regardless of whether it seems somewhat incomplete with missing features. I have also had at least a few infuriating experiences with the git documentation. To save some trouble, here are some useful commands that users should know about.

;This adds all the commits from kronosaur/master to your local master without requiring you to keep an annoying merge commit.
git rebase kronosaur/master master
;Use this to revert your last commit without leaving an annoying commit saying that you reverted it.
git reset HEAD^1
;If Sync is overwriting your local master because you used a reset, tell the origin that your local master is the "official" version by forcing a push.
git push -f

this is a great guide that I really needed.
I just forked transcendence, cloned it to my pc.

Now, I need help with some git etiquette, regarding what and how should I push upstream to George.

Do I have to make a branch for each fix I want to tackle ?
I'm not sure how my cloned repo would work if I want to fix multiple things, do I branch my branch ? or merge my branch back to my origin and then branch again when i want to fix something else ? (sorry if it sounds stupid, but I'm far from understanding well git terminology)

When I edit my own repos, I just commit and merge with the only master branch. Is it bad ?

Would George prefer many push requests for small fixes or a larger single one ?

Regarding what git to use, I would prefer to stick with the windows desktop version, as it is already the tool I use to manage my repos. I don't feel comfortable using git by command line, but I do have git shell accessible from the desktop version in case I need it.

this is a great guide that I really needed.
I just forked transcendence, cloned it to my pc.

Now, I need help with some git etiquette, regarding what and how should I push upstream to George.

Do I have to make a branch for each fix I want to tackle ?

You don't have to - you could commit your fixes to your master and send George a pull request for your master.

However, if you're working on multiple fixes at the same time this can result in a very big pull request which is hard to review. Also once you've opened a pull request, any further commits to the same branch are added to the request.

I generally create separate branches - a branch might address several related ministry tickets, but unrelated fixes get a separate branch e.g.: these four pull requests were all submitted around the same time: 45464748

Note - George accepted three of them as they were, but requested a change in PR48 which I did by pushing another commit to that branch.

I'm not sure how my cloned repo would work if I want to fix multiple things, do I branch my branch ? or merge my branch back to my origin and then branch again when i want to fix something else ? (sorry if it sounds stupid, but I'm far from understanding well git terminology)

What I usually do is keep my master in sync with kronosaur/master. When I'm working on a fix I create a new branch from master (or kronosaur/master), then send George a PR for that branch when it's ready (or I want review comments)

If George accepts the PR it will get merged into kronosaur/master and then it'll end up in my master branch when I sync with kronosaur/master.

I don't directly merge my branches into my master (neither local, origin, or gcabbage/master) as that would cause a conflict with George's merge

Would George prefer many push requests for small fixes or a larger single one ?

I try to go with many small / medium PRs rather than a single large one.

Of course, this doesn't always work. Some of my early mission refactor PRs were probably a bit large, but I was moving large amounts of code from stationType to MissionTypes, so there wasn't really an alternative.

If all the small fixes are related then I'd group them together e.g. fixing lots of typo / spelling mistakes could be easily combined into one PR.

Wow, giantcabbage, this is an excellent post and thread! Cool to see that T development has become active on Github. Exciting! And hi d1gdug!! Awesome to see that you are still around here as well! Got brought back here via a PM with questions about G.O.D and it brought back some good memories. Would love to get back into some modding given the time. Is irc still active? I will definitely be bookmarking this thread to read up on later.

What a pleasant surprise. I never expected to see a Retired Staff member come back just like that. Much has changed; the wiki is more complete, Xelerus is now deprecated, and the Multiverse is ready for community mods. Also, giantcabbage, NMS, and I are now contributing to the GitHub repository for the game.

Ooh, discord, that's cool! I'll have to try and make time to look by one day. I wouldn't say that I have returned though, but who knows :D

Is Xelerus completely deprecated? Kind of sad to hear that. Is the multiverse the replacement for that now? I thought the multiverse was more for complete add ons to T? So you could host a tiny QoL mod on the multiverse?