GitHub Desktop - A Really, Really Simple Tutorial

This year one of my greatest personal achievements was to finally make some progress with understanding and using GitHub, to the point where I have been able to submit a number of PRs to the Classic Commerce project.

I used GitHub Desktop rather than tackling the command line, but it still gave me quite a few challenges and there was much wailing and gnashing of teeth (both from me and James). One of the main problems is that there was nothing I could find online that explained everything at a really basic level. So, I decided to write up my own; partly to get it very clear in my own mind but also to maybe encourage others to have a go at contributing.

Anyway, here it is: https://simplycomputing.work/github-desktop/

Let me know if anything is missing or confusing and I’ll try and clarify it some more.

14 Likes

I have a github account but not used it, generally working on my own.
Is there a reason why steps 8 & 9 go in the opposite direction to steps 1 & 2

1 Like

Thank you!!!
Steps 6 and 7 (that deal with revisions) were just what I needed today :sweat_smile:

2 Likes

After your changes are applied to the “official” repo you likely want to work with the newest file there.
Maybe someone else has changed something, and doing so you are now working on the most up-to-date version.

1 Like

Yes i understand that you want the latest version. My query was in steps 1&2 Upstream to Origin then Local. In steps 8&9 it goes Upstream to Local then Origin

1 Like

Ok, sorry!
I think (this is true for me with command line):

  • 1 It’s easier to fork from GitHub website (I don’t know how to do it with command line)

  • 2 and then from GitHub desktop to clone to local

  • 8 It’s easy from GitHub desktop to fetch upstream (I don’t know how to do it in GitHub website)

  • 9 and then push to origin

2 Likes

TIL :man_student:

3 Likes

Yes, that’s right Mark. Steps 8 and 9 seem to go in the opposite direction to the rest of the “flow”.

I think it’s because the procedures are mainly based around using GitHub from your local computer. Once you’ve done the initial fork you don’t really need to visit your GitHub account again. It’s all initiated from local, which means it needs to fetch directly from upstream. There’s probably a way to do it by going back to your GitHub account and fetching from upstream to origin. Not sure about this though.

4 Likes

If you install an additional tool (https://github.com/github/hub) then you can do this from the command line. Otherwise it does need to be done from the website.


I think these are both the same question - I don’t think the GitHub website offers a way to do this. You really want a full git client handling this step anyway, since there are lots of different situations that your repository could be in regarding which one is more up to date, etc.


This is a good question, I hadn’t thought about it like that before.

Steps 1 and 2 are one-time things to set up your “origin” and “local” repositories. It’s not really “Upstream to Origin then Local” so much as “create Origin and Local in the first place so that I can work with them”.

I see the rest of the steps as completing a cycle: you start with all 3 locations in sync, and then you end with all 3 locations in sync. Each location serves its purpose - Upstream is official, Origin is where you can push your changes and ask people to look at them, and Local is where you do your work.

When you’re starting a second pull request and you already have Origin and Local set up, then you just need to make sure all your repositories are synced together and you can start with Step 3 in the tutorial.

How to do this syncing is probably a good thing to cover also. For now I will just say that deleting your repositories and starting over is not the right way to do it - this causes a lot of issues if you still have un-merged PRs open somewhere!

4 Likes

I’ve started with Github Desktop a couple of months ago and it seemed nice at the beginning. But I also realized that it was just a first step to dive softly into the command line) It took some time to get used with it, but now I feel more comfortable with Git Bash because direct input gives much more flexibility than GUI.

Can’t say that I completely understand everything I do :slight_smile: But at least I can fit it to my needs. For example, last week I have set Git on a a shared hosting and now use it to deploy some old sites. That was a bit tricky, but finally it works like a charm)

I should really thank the Community once again, because ClassicPress made me to reorganize my own workflow) And it’s absolutely worth the time.

5 Likes

I’ve tried to integrate the steps for the command line usage.
I’m not sure if I’m doing right, expecialy for steps 8 and 9.
Omitted steps are those done in GitHub.

Step 2 - Clone to your local computer

# Let's clone it
git clone https://github.com/user/repo.git

Step 3 - Create a branch

# Create a LOCAL branch "feature-x"
git checkout -b feature-x
# optionally push your new branch to ORIGIN
git push origin feature-x
# You can see all the branches created
git branch -a

# Now you have changed something and want to commit

# See what is changed
git status
# Commit your changes: let's git decide what's changed
git commit -am "Here my commit"
# Commit your changes: decide what to commit
git add mynewdir
git rm myoldfile
git add mynewfile
git commit -m "Here my commit"

Step 4 - publish your changes to origin

# Push your commit(s) to ORIGIN
# First push
git push --set-upstream origin feature-x
# Then just
git push

Step 6 - Make some revisions to your PR

git add file-i-have-changed
git commit -m "Ok, this is my revision"
git push

Step 8 - Fetch the new upstream

# Check if is already here
git remote -v
# If it's not, add it
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
# Fetch the branches and their respective commits from the upstream repository. 
# Commits to master will be stored in a local branch, upstream/master.
git fetch upstream
# Check out your fork's local master branch
git checkout upstream/master -B master

Step 9 - Push new files to origin

# Push to origin
git push origin master

Edited as suggested by @James here.

About master or develop branches an important note from James:

4 Likes

Good instructions @Simone!

Here I would use the following command instead, because it will do a better job of resetting and cleaning up your local branch so that it doesn’t include any unwanted changes:

git checkout upstream/master -B master

After that, the git merge step is unnecessary (it should do nothing). In step 9 you don’t have to “hope the merge has gone right” either, since there was no merge.

Note that for some repositories (including ClassicPress) the default branch is develop rather than master, so you’d use develop everywhere the above instructions say master.

4 Likes

Thank you!
I’ve edited (hope in the right way!) the post with your suggestion.
Simone.

2 Likes

Great work Simone, Once this is finalised I’ll add this onto to each step in the tutorial for those brave souls who want to tackle the command line.

5 Likes

When this tutorial is finished it might be interesting for the blog. Let me know when a version is ready and we can maybe make a post out of it :wink:

3 Likes

@ozfiddler @klein
I think is almost finished but I’m waiting from someone more expert an OK :wink:
Command line is my life but git entered in my life just some months ago :sweat_smile:

3 Likes

I think it would be better to make a separate tutorial with the same diagrams for command-line usage. This would be great to put on the ClassicPress blog if everyone involved agrees.

@ozfiddler were you still planning to add GitHub Desktop screenshots to your tutorial to make each step easier to find?

@Simone your edits look right to me. A few things that might be worth adding:

  • git fetch upstream and git checkout upstream/master -B master from Step 8 should also be done before starting a new PR! Doesn’t matter for the first one, but this will make sure that you are always starting from the right place without any unwanted changes.
  • Deleting your repository locally or from GitHub is never the right solution! This causes a lot of problems if you’ve already submitted any PRs for review, and it is much better to learn how to inspect and fix your branch(es) when necessary.
  • As long as you have committed your changes (and you haven’t deleted any repositories) it is basically impossible to lose any of them, for more help: https://ohshitgit.com/
3 Likes

Err, haven’t I done that already? Each step heading is a link to a separate page with screenshots. Or you can use the side menu. Or did you mean something else?

2 Likes

Sorry, I was expecting to see the screenshots inline with the article text, so I totally missed this! I see now that it would be very long if the screenshots were included on a single page.

This means you can ignore my suggestion here also :slight_smile:

2 Likes

We could duplicate that main page and do another command-line version. The commands could go inline and it wouldn’t be that long.

EDIT: something like this? https://simplycomputing.work/github-commands/

4 Likes