Guide to FS Open and git

Getting the source: Tortoise Git

(based on Getting_the_FreeSpace2:_SCP_Source_Code)

• Download and install Git For Windows (this is a dependency for TortoiseGit)
• Download and install TortoiseGit (you probably need to reboot after installing)
• Make a new folder on your HDD where you'd like to install the code. You'll need a fair bit of space for the code + the intermediate files when building it. Press right mouse and choose Git Clone from the list.

• A new window will open up. Cut and paste the URL of the FSO Github repository into the URL of repository box (https://github.com/scp-fs2open/fs2open.github.com.git)

• Press OK to begin downloading from the repository (this may take a few minutes, depending on the speed of your internet connection)

Simple Development: Tortoise Git

Note: the guide assumes that you will be developing using a github fork (which is recommended for everyone, SCP members and non-members alike)

• Go to the github webpage and create an account
• Go to the FSO repository on github and click on Fork

• Record the URL for your newly forked copy of the FSO repository

• Get the code per the guide above
  • Note: you need to use the URL for your forked repository, not the main FSO repository listed above
• Right click on the repository directory and select TortoiseGit -> Create Branch
  • Note: all development should be done in a new branch, instead of being done in the "master" branch. It's just simpler

• In the new window, enter the name for the new branch, verify that the branch is based on HEAD (master) and check the "Switch to new branch" box

• Write some code with your Editor of Choice
• Test your new code
• When you're happy with the code, right click on the repository directory and select TortoiseGit -> Diff

• Review your changes by double-clicking on all the files listed in the new window (ensure no unwanted changes have snuck in!).

• This is how the diff will be displayed (using TortoiseGitMerge, which is also used to resolve conflicts)

• When your review is complete, press "Commit" (in the same window that you double clicked on all the changed files)
• In the new window, add a commit message and press OK

• When the commit is complete, press the "push" button to send your commit(s) to your github repository

• Select your local branch name from the drop down list and ensure your Destination -> Remote: is "origin"
• If you want to, you can give the public remote branch a different name to your local branch (this can be useful when rebasing a branch already published to your public repository)
• Finally, press OK

• Go to your Github Repository webpage and select the branch you just pushed

• When you have the correct branch selected, click on the "Pull/Review/Compare" button

• Now click on "Create Pull Request"

• Note: the previous three steps can be done as a single step if you have recently pushed a branch by selecting the "Compare and Pull Request" button

• Add comments to the pull request if you wish, then click "Send Pull Request"

• And that's it! Now you wait for the pull request to be reviewed and committed to primary FSO master branch

Syncing and Simple Conflict Resolution: Tortoise Git

Note: This section is under construction

This section will go over syncronizing your local git repo with a remote, as well as cover some simple conflict resolution.

Once you've committed to your local git repo and verified its integrity (a simple build-check will suffice), you should update the remote repo through the "Push" process.

• Right click on the repository directory and select "Push..."

The Push dialog is displayed. From here, you can push one or more branches from one repo to another, local and remote alike. The "Ref" control group will be the repo that will be pushed onto the repo specified in the "Destination" control group. If you are managing multiple remotes, you may also push one remote to another.

For now, we'll focus on just pushing our local repo onto the remote.

• Select the branch from the local repo in the "Ref" control group
• Select the branch from the remote repo you wish to push to in the "Destination" control group.
• Click OK to start the push

If a conflict between the remote repo and your local repo arises, git will halt the push.

Collaboration with remotes: Tortoise Git

Here we'll go through:

• adding a remote branch from someone else's repository
• committing to that branch and pushing it back to your own repository

You may do this when you're collaborating on a feature prior to it being committed to the master

• Start by right clicking on the local repository directory and selecting "Settings"

• Select the "Remote" item from the left hand menu, then
  • add a local name for the new remote repository
  • add the remote repository URL (I'm using m!m's github repository in this example)
  • Set the "Tags" dropdown to "None"
  • Click "Add New/Save"

• You should be prompted if you want to "...fetch remote branches...", select "Yes"

• All the defaults should be fine, click "OK"
• Note that this step may take a little time

• When it's complete you want to create a local branch to track one of the remote repositories branches
• Right click on the local repository directory and select "Create Branch..."

• Set "Base On" -> "Branch" to the remote branch you want to work on
• Check "Switch to new branch"
• Click "OK"

• Write some code!
• When you're ready to commit, right click on the local repository directory and select "Git Commit -> (branchname)..."

• Enter a commit message
• Review the changes that will make up the commit by double-clicking on files in the list

• When the commit is completed there will be a button to "Push" your branch.
• You probably won't have permission to push to the other persons remote branch, so push to your own remote repository
• Optionally change the remote branch name (e.g. with a reference to the remote it can from)
• Select "Origin" as your "Destination" -> "Remote"
• Click "OK"

• Now you can tell the other person that you've added to their branch and have pushed the changes to your own remote branch
• They can now follow (most of) the steps above to add your repository as (to them) a remote and fetch/merge your changes into their branch
• When that happens you probably want to get their changes into your local branch
• Firstly ensure that you have the branch to want to merge into selected
• Right click on the repository directory and select "Fetch..."

• Select the correct remote repository from the dropdown

• Right click on the repository directory and select "Merge..."

• Select the correct remote branch to merge from
• Click OK and you're done (assuming there are no merge conflicts of course...)

Applying old patches (and conflict resolution)

Note: This section is under construction

Here's one way to apply old patches using git. When I say "old patch", I mean a patch that you almost certainly know is going to have conflicts. This is based off a technique I've used with the git command line. It may be that TortoiseGit provides alternate ways of achieving this, however the advantage of this technique is that it's very similar to the conflict resolution that you may need to do when syncing your repo (plus I have a good example in one of Axem's patches that's been floating around for... nearly 2.5 years!) And I really hate dealing with .rej files, I find the graphical tools used in this method make conflict resolution much easier (of course YMMV depending on your experience/preference!)

• Before you start, ensure that your master is up to date (perform a Sync / Pull)
• Start with creating a new branch (i.e. the typical git response when you want to do almost anything! :))
• The only trick is that you want to create the branch based on a specific commit - in this case the commit that the patch was based on
  • Right Click -> TortoiseGit -> Show Log is your friend in finding the commit revision you need to select

(piccy)

• Save the patch to a file and copy it to somewhere inside the git repository
  • depending on the paths in the patch, the exact location of the patch file *may* matter (I haven't personally tested this)
• Right Click on the patch file, then select TortoiseGit -> Review/apply single patch

(piccy)

• TortiseGitMerge should start with an extra window displayed
• Click "Patch all items" in the extra window to apply the patch
  • If you started the branch at the correct revision the patch *should* apply correctly without any editing
• When done, close both windows (no save is required)

(piccy)

• Next commit the changes to your branch (this is pretty much the normal commit process)

(piccy)

• Now we're onto something new - you are going to "rebase" the current master onto your branch.
  • This is basically saying, apply all the commits from master to your branch *and then* apply the patch "on top" of all those changes
  • This is distinct from a "merge" which is more like applying all the commits from master "on top" of your current patch

Warning: DO NOT EVER perform a rebase on a branch that you have pushed to a public repository. It's just going to cause pain. Perform a "merge" instead. Or maybe create a new branch based off your existing branch, then rebase *the new* local branch and push to a *new* public branch.

• Right click on the repository directory, select TortoiseGit -> Rebase
• Select "master" as the upstream
• Click "Start Rebase"

(piccy)

• As expected, the "Rebase" fails due to conflicts
• Check which files failed, then double click on each file to resolve the conflicts

(piccy)

• The TortoiseGitMerge window should open. This a a graphical interface that assists with conflict resolution. It shows the code from
  • the master branch (Theirs - REMOTE for a rebase)
  • your branch + patch (Mine - LOCAL)
  • the output from your conflict resolution (Merged - filename)
  • Non conflicting changes should be automatically merged
  • Conflicts are marked in red highlight, and their are "Previous Conflict" and "Next Conflict" buttons at the top of the screen to move between conflicts in this file

(piccy)

• This files conflict is simple to resolve
• Right click on the numbers in the "Theirs" window and select "Use text block from 'theirs' before 'mine'"
• Note the red "????" lines in merged window turn green to show the conflict has been resolved

(piccy)

• That's all for this file, click "save" then select "Mark as Resolved"

(piccy)

• Close the window, and that's one file down, two to go! (which I'll skip over in this case)

(piccy)

• Once all the files with conflicts are resolved, click "Commit" to complete the process
• TortoiseGit -> Show Log is very useful to double check that you got the commit right before pushing it to a public repo
• If you didn't get it right, edit the files in your normal IDE to fix the mistakes, make another commit and "squash" the two commits together before pushing to a public repository
• Or if it's beyond saving, delete the branch and start again

• Lastly, here's a list of some of the tools offered by TortoiseGitMerge which can help with conflict resolution (the list has some overlap with stuff I've already mentioned)
  • Right click the line numbers in the "theirs" or "mine" windows to select "text blocks" which will be applied to the "merged" window
  • For simple conflicts you can choose "theirs then mine" or vice versa from the right click menu
  • By clicking on the line numbers on the left hand side you can select individual lines to apply
  • Similarly you can select multiple lines by click/dragging on the line numbers
  • When "theirs/mine" lines are selected another right-click option becomes available, "copy". These lines can then be pasted to "merged"
  • You can also make edits in the "merged" window just like any other text editor
  • Use the "Next/Previous Commit" buttons to rapidly find the conflicts
  • Save when you're done