Using GitHub - introduction & tutorial

handy tools that can assist in the development of new software
Post Reply
User avatar
Posts: 304
Joined: Mon May 09, 2016 3:40 pm

Using GitHub - introduction & tutorial

Post by simonm » Sun Sep 16, 2018 6:39 pm

Hi all,
Github/git has come up a few times in various discussions, and often in the context of folks who have some source code or a project they want to publish in the public domain, but are perhaps put off because at first inspection the world of git and Github can seem a bit overwhelming.

I thought it might be useful then to provide some overview tutorial on this topic to demystify it a bit.

Firstly though, while there are many alternative options for online hosting of projects and version control, Github has amassed a lot of credibility for open source project hosting because 1) it is free for public projects 2) the tools are good 3) the active community is large. This tutorial therefore focuses on generally how to setup and make good use of GitHub.

Secondly, some of the questions below may be stuff many of you already know, so just skip those! I tried to cover as many basics as I could in case it's useful.

Thirdly, I've tried my best to just cover the basics rather the details. Any deeper dives can be either followups or rtfm's. :D

What is GitHub?
It is a way to publish projects online so that other folks can see them, access them, and try them out for themselves.

Is GitHub free?
Yes. You can create either a personal or organisation account for free, with the restriction that any projects you host cannot be private; they are visible to everyone on the web. If you want to host private projects, then you have to switch to a paid account.

What is a GitHub project?
Typically projects contain source code, documentation, and basically any other files related to your work.
In GitHub terms - projects are called repositories ('repos')

Why are they called repositories?
GitHub is based on git, an open source command line toolkit for version controlling source code or files. Fortunately, you don't have be an expert in all of the complexities of git to use GitHub, since there are tools available that make it really easy to keep the online version of your project upto date with the version you have on your local computer. Plus GitHub gives you a way to host projects online. For free.

What else does GitHub offer?
You can also do simple task management, bug tracking, release management, and add wiki type content to your repositories. You can also create and host static websites on GitHub.

Do I have to learn/install Git command line to use GitHub?
Not really. The easiest way to use GitHub is to install their desktop application, which gets you everything you need to use GitHub and is essentially a visual frontend on git command line, but their application takes the complexity out of it all. Linux users will need some alternative GUI for git however. (I'm not familiar with Linux so cant advise on that). There are other tools that work with Github, like TortoiseGit for Windows or SourceTree, but GitHub desktop is pretty decent and easy to use.

Why use something like GitHub anyway?
There are so many fantastic projects happening in the Stardot community, across a wide range of interest areas (hardware, software etc.), that making these projects or initiatives publicly available in GitHub offers a great way to not only efficiently manage development of a project over time, but also inspire others with similar interests to contribute enhancements, bug fixes, or even new offshoot projects! On top of this it preserves the skills and know-how for the future reference of the whole community.

How do repositories work?
GitHub, being based on git, uses the principle of distributed version control.
What that means in principle is that one or more folks can make a copy of a project and all of its historical changes on their local computer, work on it locally as normal, and then simply use GitHub as a means to keep track of the changes they've each made, to keep everything in sync.
Because everyone has the same copies of the work done on the project, it makes collaboration very easy. You don't have to be online or connected to GitHub to work on a project locally.

What are the basic functions of a repository?
The primary function of a repository is to track and record changes made to a project over time.
Typical activities are that you can add one or more files, delete files, or edit files in your project.
All of these types of actions can be grouped together into what's called a 'commit', to which you attach a short description, and treat that as a snapshot of a change you made. In this way, you or anyone else can see what and why the changes were made over time.

I've heard about branches - what are they?
You can create a whole separate copy of your repository, simply so you can work on getting a new feature ready, or maybe for testing an experimental feature. These are called branches, and you can create as many as you like. You can also switch between branches, and your local copy will change to reflect whatever state you left that branch in. Better explanation info is here.
You dont have to use branches. A fresh repository will always contain a 'master' branch, and you can just use that if you like.

What about licensing?
GitHub has pretty good support for boilerplate licensing and attribution. See here for their documentation on this. When you create a repository in your GitHub account you can seed it with a license to suit your needs, in this way you have control over your preferred terms of distribution.

How does collaboration work?
For any repository you own, only you can make changes to the project. However, you can invite other GitHub users to be collaborators, which will allow them whatever access permissions you provide. Sometimes, other GitHub users may 'clone' your project, which means they've taken a copy of your project to try out themselves, and they might have made a change they think you would like, so they might create a request for you to consider the change - called a 'pull request'. You dont have to take the change, but you can consider it and discuss it if you like.

What about organisations?
Alternatively, GitHub supports organisational accounts, which can host and own multiple repositories. Organisation accounts do not have a login/password type account, instead they exist with multiple GitHub users as owners/collaborators. The main benefit of this is that any projects in the organisational account are owned by a community rather than an individual. It is straightforward to transfer repositories from an individual GitHub account to an Organisational account, and vice-versa.

Stardot has its own GitHub organisation account, with a growing number of community projects hosted within it. See this thread, if you'd like to be added as a member.

So how do I get started?
If you just want to get cracking, here's a whistle stop list to get your project source off your local drive and online:
1. Sign up for a free GitHub account
2. Create a repository for your project in your GitHub account
3. Consider setting up a default README or LICENSE when you create a new repository
3. Install the GitHub desktop application
4. Clone the repository you just created to a folder on your local computer (I like to have a GitHub root folder in my setup to stash all my projects in)
5. Copy all of the source files for your project into this new folder
6. Using the GitHub desktop application, commit these files into your new local repo (remember these are still only local changes for now)
7. Sync your local repository back to the remote GitHub repository using a pull request
8. In the online GitHub account webview, accept the pull request

Congrats - Your project is now online!

User avatar
Lardo Boffin
Posts: 1941
Joined: Thu Aug 06, 2015 7:47 am

Re: Using GitHub - introduction & tutorial

Post by Lardo Boffin » Sun Sep 16, 2018 7:03 pm

Nice guide! I have some simple projects on there but have never really done anything with it.
Atom, issue 5
BBC model B 32k issue 4, 16k sideways RAM, Watford 12 ROM board, Acorn 6502 coproc
BBC model B 32k issue 7, turboMMC, Opus Challenger 3 512k, Pi 3 coproc
USA Model B
BBC Master, Datacentre + HDD, pi co-proc, econet, NULA

Posts: 213
Joined: Sun Jul 01, 2018 4:12 pm
Location: Toronto

Re: Using GitHub - introduction & tutorial

Post by scruss » Sun Sep 16, 2018 7:28 pm

That's really nice!

I've never used the GUI, only the command line tools. It seems a little strange to have to use a pull request then local sync to get your local files sorted out, but if it works … It's also likely much less of a faff than with the command line tools, though.

A useful feature that space probably didn't allow is designating a certain code state as a release. Releases allow users to download the code in exactly that state, even if your repo has changed considerably.
Last edited by scruss on Mon Sep 17, 2018 12:40 am, edited 1 time in total.

Posts: 343
Joined: Mon Jun 26, 2006 10:21 pm

Re: Using GitHub - introduction & tutorial

Post by guesser » Mon Sep 17, 2018 12:21 am

I was going to say, "why not just push?"
I use either the command line or the TortoiseGit shell extensions, so am not familiar with github's desktop front end either.
A web based teletext editor which can export as Mode 7 screen memory:
Join the Teletext Discord for teletext chat.

Post Reply

Return to “development tools”