GitHub and GitHub Desktop Tutorial

Prof. Garfield

Deity
Supporter
Joined
Mar 6, 2004
Messages
4,382
Location
Ontario
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)

1-GitHub-Desktop-Sign-In.png

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.

2-Sign-In-To-GitHub.png

4. Authorize GitHub Desktop. (Green Button)

3-GitHub-Authorize.png

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

4-Open-GitHub-Desktop-From-Browser.png

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

5-Finish-Configuration.png

7. GitHub Desktop should now look something like this:

6-Empty-GitHub-Desktop.png

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:

7-Empty-GitHub-Desktop-New-Repo.png

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.

8-Create-new-repository.png

10. GitHub Desktop now looks like this:

9-GitHub-Desktop-Repo-Created.png

You can look at the History tab to see the initialized files.
9a-Initialized-Files.png
 
Last edited:
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.

10-Publish-Repo.png

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

11-GitHub-Repo-Tab.png

We'll select the Example-Repo.

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

12-Code-Tab.png


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:

13-Collaborators.png

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

14-Search-ProfGarfield.png

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

15-Invite-Email.png

16-Accept-invite.png

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:

17-Clone-Repo-Menu-1.png

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-Clone-Menu-2.png

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.

19-Rules-Change.png
 
Last edited:
19. Returning to GitHub Desktop, this change is now visible:

20-GitHub-Change.png

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-Commit-Change.png

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

22-Push-Origin.png

22. On GitHub.com, we now see a more recent change:
23-Example-Repo-Change.png


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


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

25-Pull-Origin.png


24. And, now, the Rules.txt is updated on the original machine:
26-Rules-Updated.png


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:

27-URL-Clone.png

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

28-Change-Repo.png
 
Top Bottom