GitHub and GitHub Desktop Tutorial

[Prof. Garfield]

This is a tutorial to get started using GitHub and the GitHub Desktop program. If you're collaborating on a project, using GitHub can make sure that everyone is up to date. This could also be useful if you're passing around playtests for a scenario, so everyone can easily get updates/bug fixes. Periodically uploading to GitHub will also act as a backup for your work.

1. Download and Install GitHub Desktop. Find it here: https://desktop.github.com/

2. Create a GitHub account.

3. Start GitHub Desktop, and select "Sign in to GitHub.com" (Blue Button)

If you're not already signed in to GitHub on your browser, you'll see this login page. If you are signed in, proceed to the next step.

4. Authorize GitHub Desktop. (Green Button)

5. Open GitHub Desktop when the pop-up asks. (White Button, NOT Blue)

6. Press Finish (Blue Button) to complete configuration.

7. GitHub Desktop should now look something like this:

8. For this tutorial, I downloaded a TOT conversion of Hammer of the North ( https://forums.civfanatics.com/resources/hammer-of-the-north.28571/ ), and placed it in the Scenario Folder. This will be a new scenario, which we intend to store on GitHub. To achieve this, we select the "Create a New Repository on your hard drive..." option:

9. We now give the repository the same name as our scenario file ("ToT_Hammer"), a description ("A repo created for a tutorial."), Choose the path to the directory containing ToT_Hammer, and select that folder. We won't worry about a license or Git ignore for now.

10. GitHub Desktop now looks like this:

You can look at the History tab to see the initialized files.

 

[Prof. Garfield]

11. We will publish our repository to GitHub, by selecting the Publish repository button. This window will be shown, take not of the 'keep this code private' option, which we'll keep enabled for now. We will name our repo as "Example-Repo" here.

12. Now, let us open a web browser, and go to our profile on GitHub.com, and look at the repositories tab:

We'll select the Example-Repo.

13. In the "Code" tab, we can see our current file structure and files.

14. One purpose of using GitHub is to be able to collaborate with others. To invite collaborators, we select the Settings Tab, and the Collaborators option:

15. Here, I search for ProfGarfield (my main GitHub Account, I was using a different one so far), and invite myself as a collaborator.

16. The collaborator, (my main ProfGarfield) receives an email, and presses the View Invitation button, then accepts the invitation in the web browser.

17. The collaborator already has active repositories, though this should work if you don't yet have any. (From here, I'm using GitHub Desktop on Linux, instead of a windows VM, so things may look slightly different.) Go to File->Clone Repository. This menu will appear:

In this case, I had to scroll down to find the Example-Repo. I also choose the path where I want the Example-Repo to go, selecting the Scenario Directory of my Test of Time installation. (The local path fills in the repository folder name.

18. Cloning the repository immediately downloaded all the files, and placed them in a directory (which I chose to be in my Test of Time\Scenario folder. Within that folder, I make a change to Rules.txt, changing the "Nothing" improvement to "NONE" instead.

 

[Prof. Garfield]

19. Returning to GitHub Desktop, this change is now visible:

20. To update the GitHub repository, it is first necessary to "commit" the change. We give a short description (not bothering with a long one) and press Commit to main.

21. Next, we need to "Push" the commit to GitHub, since now it is only on our local machine. Choose "Push origin".

22. On GitHub.com, we now see a more recent change:

23. The last step is for the repository creator (my spare ProfGarfield-2 account) to receive the update. Press "Fetch Origin" to update:

Next, we must "pull origin", using the same button.

24. And, now, the Rules.txt is updated on the original machine:

Addendum: Cloning a repository you aren't collaborating on. Here, my ProfGarfield-2 account will clone the over-the-reich-v-5 repository, to follow along with development. In this case, we copy the URL for the repository, and use the URL tab in the Clone a repository menu:

Now, there are 2 repositories for ProfGarfield-2. They can be switched using the leftmost tab.