Getting started with git and github

Help building, determining code organization, and other new-to-project problems.
giantcabbage
Militia Lieutenant
Militia Lieutenant
Posts: 104
Joined: Thu Apr 07, 2011 9:05 pm

This is a basic guide to making contributions via github

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.
GitHub Desktop Beta is the new GitHub client.
  • 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)
Atom is a powerful text editor with GitHub integration (basic git functions and GitHub specific functions like Pull Requests). NOTE if you use Atom, then make sure you disable the “Remove Trailing Whitespace” feature (Ctrl+, -> Packages -> whitespace -> Settings)

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

Code: Select all

$ git clone https://github.com/<username>/Transcendence.git
$ cd Transcendence
$ git remote add upstream https://github.com/kronosaur/Transcendence
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:

Code: Select all

$ git clone https://github.com/kronosaur/Alchemy
$ git clone https://github.com/kronosaur/Mammoth
You can compile the source with the free version of Visual Studio

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:

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

Code: Select all

$ git checkout -- TransCore/Antarctica.xml
Now lets make a change to a file. Edit TransCore/PlayerShips.xml and give the Sapphire some more credits:

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")
We can check what changes have been made with git diff:

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>
Lets try the git add command this time:

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

Code: Select all

git commit -m "Give the sapphire more starting credits"
You can also just use git commit, which will bring up text editor window where you can enter the commit message.

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
Reverting Changes

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
This creates a new branch called revelationsGun based on the master branch.

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
5) Commit the changes to your local repositoty

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(-)
6) Push the changes to your github repository

Code: Select all

$ git push
If this is the first time you've pushed to this branch you'll get an error about upstream branch e.g.

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
So use the expanded command it suggests (with git bash you can just select the text and middle-click to paste it):

Code: Select all

$ git push --set-upstream origin revelationsGun
7) Create a pull request
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
Last edited by giantcabbage on Sun Aug 06, 2017 11:15 am, edited 1 time in total.
User avatar
0xABCDEF
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu May 19, 2016 12:58 am
Location: Was destroyed by a Phobos-class dreadnought in the Eridani system

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?
giantcabbage
Militia Lieutenant
Militia Lieutenant
Posts: 104
Joined: Thu Apr 07, 2011 9:05 pm

0xABCDEF wrote:
Fri Aug 04, 2017 6:29 pm
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
User avatar
Song
Fleet Admiral
Fleet Admiral
Posts: 2801
Joined: Mon Aug 17, 2009 4:27 am

Seems all good to me (and thanks for dealing with my pet gripe of the month). I'll try running through this and flag anything that gives me trouble (as a complete noob with regards to git).
Mischievous local moderator. She/Her pronouns.
User avatar
0xABCDEF
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu May 19, 2016 12:58 am
Location: Was destroyed by a Phobos-class dreadnought in the Eridani system

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.

Code: Select all

;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
User avatar
digdug
Fleet Admiral
Fleet Admiral
Posts: 2620
Joined: Mon Oct 29, 2007 9:23 pm
Location: Decoding hieroglyphics on Tan-Ru-Dorem

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.
giantcabbage
Militia Lieutenant
Militia Lieutenant
Posts: 104
Joined: Thu Apr 07, 2011 9:05 pm

digdug wrote:
Sat Aug 05, 2017 4:44 pm
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: 45 46 47 48

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.
digdug wrote:
Sat Aug 05, 2017 4:44 pm
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
digdug wrote:
Sat Aug 05, 2017 4:44 pm
When I edit my own repos, I just commit and merge with the only master branch. Is it bad ?
That's fine - I do the same.

If it's your own repo / you're the only person contributing to it, you don't often need to create branches.
digdug wrote:
Sat Aug 05, 2017 4:44 pm
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.
giantcabbage
Militia Lieutenant
Militia Lieutenant
Posts: 104
Joined: Thu Apr 07, 2011 9:05 pm

I've updated the original post with an expanded introduction and some use of the basic commands.
User avatar
alterecco
Fleet Officer
Fleet Officer
Posts: 1658
Joined: Wed Jan 14, 2009 3:08 am
Location: Previously enslaved by the Iocrym

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.
Get your own Galactic Omni Device
Get it now. It's free!!
Image
User avatar
0xABCDEF
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu May 19, 2016 12:58 am
Location: Was destroyed by a Phobos-class dreadnought in the Eridani system

alterecco wrote:
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.

IRC is not very active. Instead, I recommend that you join our Discord: https://discord.gg/mhrSfbH
User avatar
alterecco
Fleet Officer
Fleet Officer
Posts: 1658
Joined: Wed Jan 14, 2009 3:08 am
Location: Previously enslaved by the Iocrym

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?
Get your own Galactic Omni Device
Get it now. It's free!!
Image
User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2767
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Stop on by Discord! At least idle there. Its been too long!
Image
Image
User avatar
digdug
Fleet Admiral
Fleet Admiral
Posts: 2620
Joined: Mon Oct 29, 2007 9:23 pm
Location: Decoding hieroglyphics on Tan-Ru-Dorem

Alterecco !!
So nice to see you around !
:)
relanat
Militia Captain
Militia Captain
Posts: 941
Joined: Tue Nov 05, 2013 9:56 am

I had a go at this the other day and it is easier than I expected. I will say that without gc's explanation above it would have been much harder if not impossible. Very well done, gc.

I just followed gc's tutorial from Getting Started (using Git Bash) and went from there. I didn't bother with the Alchemy or Mammoth stuff.

Sometimes I wasn't quite sure what I was doing but by referring back to the tutorial I could easily work it out.

If you are thinking of having a go, it is a lot easier than it sounds.

You basically just download some stuff, enter some command line code, enter the changes and then do some github stuff to create the pull request.

Entering the changes is easy. All you do is edit code in your text editing program like when you are modding. When you have finished the git code works out what is different and automatically displays it for you.

The most confusing part was using the actual github pages. There seemed to be an endless series of instructions to click 'Create Pull Request' again and again, and it wasn't always clear about when and where to enter comments.

There is also a quite helpful explanation/tutorial at https://github.com/dashboard which I found worthwhile.

One point, gc, is that I still don't understand the part about creating branches and when or if you need to do that.

Great work. Very well explained.
Stupid code. Do what I want, not what I typed in!
giantcabbage
Militia Lieutenant
Militia Lieutenant
Posts: 104
Joined: Thu Apr 07, 2011 9:05 pm

Basically you need to create branches if you want more than one pull request open.

If you're just working in master then all your commits get added to the same pull request until George merges it (after that you could create a new pull request, but you can't have two open at once without a branch)

Having multiple branches / PRs can be useful if you want to work on multiple things at the same time. e.g I had some recent dockscreen changes and battlearena changes as separate branches. On my computer I could use git to easily switch between master (George's code), dockservices, and battlearena branches for testing.
Post Reply