GitHub

It has to be noted that GitHub has grown in both size and popularity and is a great place for working on open source projects. Suppose though you want to do more than just raise issues, well, see below for some help.

If you are having problems with GitHub then see GitHub Status, I recently had a problem seeing remote: fatal error in commit_refs when pushing commits to GitHub, turned out that GitHub was having a bad hour.

A useful tool to enhance Git when working with GitHub is a tool called hub · the command-line wrapper for git.

Getting Started

The GitHub documentation and blog is a good place to start, specifically Beginner's guide to GitHub repositories: How to create your first repo - The GitHub Blog. After that Top 12 Git commands every developer must know - The GitHub Blog is a good follow on article.

Cheat Sheet

If you want some help or power tips then tiimgreen/github-cheat-sheet is a great place to start.

Comparing Branches

I believe whether you see the option to do this, or not, depends on your permissions in a repo. If you can create a Pull Request, then you don't see an option to compare branches, but if you cannot create a PR then you do see compare. Personally I think compare is useful, even if you can create a PR.

This is covered in the Cheat Sheet referenced above but, for some reason GitHub provides no obvious way to do this, but you can craft a url yourself as follows:
https://github.com/{user or organisation}/{repo}/compare/{first branch}...{second branch}
If you use "main" for the first branch and your working branch as the second one, it will show you changes in your working branch that are not in "main". You can do other things with this, like using dates, see GitHub - tiimgreen/github-cheat-sheet: A list of cool features of Git and GitHub. for details.

Note that you can also just go to https://github.com/{user or organisation}/{repo}/compare/ which is easier and avoids typing out branch names.

Contributing

Suppose you find a repository and you would like to contribute. It is unlikely the owner will give you direct contributor access, so try something like this:

  • Create an issue, so you can ask the question and discuss your idea
  • In their repository, click the Fork button, this will then create a copy of their repository under your account
  • Do all the changes you want against your forked copy
  • Then in your copy, click "Compare" so you can see if they have updated the same files
  • From the comparison page you can create a "Pull Request" which starts the process of merging your changes

All quite simple really.

It is simple until such a time as you find the repository that you forked has moved on and you want to do another change. If this happens, then you need to do the following on the machine you did the changes:

  • git fetch <repository> - this pulls the original repository changes down
  • git checkout master - should just confirm you are already on "master"
  • git merge <repository>/master - merges the changes to your local git
  • git push - pushes your local git up to GitHub

After this GitHub will see your forked repository as the same as the original repository.

Working with Forks

There is some good help documentation on GitHub to help with forks but one issue I keep struggling with is updating my fork with the latest from the original, so this is what I need to do:

  1. Check an "upstream" is configured by running git remote -v, this should list "origin" as your fork and "upstream" as the original
  2. If the "upstream" is missing then git remote add upstream https://github.com/original_user/original_repo.git
  3. git fetch upstream - to pull the changes on the original into your local repo
  4. git merge upstream/master - to merge those changes in
  5. git push - to push the changes into your fork, so now they should be the same!

Windows Desktop App

This is a short summary of what I did to create a Pull Request with the Desktop App for Windows, it confused me at first but the key is you need to work from your own branch or fork.

  • Create a fork on GitHub, if not already done
  • Clone with Desktop app, to pull repository locally
  • Update from Organisation/master which will refresh an old branch/fork
  • Edit file(s) locally
  • In Desktop commit changes file(s)
  • Click Create "Pull Request"
  • select from master into "Organisation/master"
  • Add summary and description
  • Click Send Pull request

One further problem I find is keeping your branch up to date, it is not obvious how you do this. However I believe there are two keys here. Firstly you need to configure your fork correctly, so follow Configuring a remote for a fork - User Documentation to get this working. Then, once that is done, any time you want to refresh your fork just do Syncing a fork - User Documentation.

Readme Files

You will have noticed that many repositories have a README.md file, this is a "markdown" file and forms the introduction to the repository. If you need help with the syntax see Writing on GitHub - User Documentation which covers everything but Mastering Markdown · GitHub Guides is a great starting point. Do note that GitHub does not use standard markdown but "GitHub Flavored Markdown" or GFM. See also File Formats.

Security

Using Two Factor Authentication or 2FA is always a good idea. However I found that after turning this on I could not clone a repository. It turns out you cannot use your password any more, which is obvious, when you think about it. However the git command line utility does not support 2FA with GitHub, also kind of obvious. The solution is an OAuth2 type token. So login to GitHub with a browser, go to Settings and then "Developer Settings" and generate a "Personal access token", this will then get you going. See Using command-line git with GitHub 2FA | gmacario.github.io for some more information on this.