What is GitHub and how to use it?

GitHub is a platform owned by Microsoft. It became the place of choice for many developers and companies working on open-source projects. You can host public projects for free on GitHub and enjoy the many great features that will make your coding life easier.

You can also create private repositories with a free account, of course. And you can pay if you need more resources. But I’ve been using GitHub for my open-source projects for years (the SDA and journalism libraries, and this course too) and I never reached the limits of the free plan!

As its name states: GitHub works with Git. So I strongly suggest you follow the previous lesson How to use Git? before diving into this one. Here, we are going to follow the same steps as the previous lesson: building a simple program to retrieve the temperature in Montreal. But we are going to store our code in the cloud, with GitHub!

GitHub account

To work with GitHub, you first need to create an account. So start with that.

A social network

When you log into GitHub and land on your home page, you’ll see a Feed section. That’s because GitHub is also a social network. For example, you can see my feed below at the time of writing. It’s great to stay up to date with open-source projects you are interested in or just to see what people you find interesting are working on.

Users have a public profile showing their public activity, and you can follow them to see their activity in your feed. Here’s my profile, for example. Follow me! 🤗

Personally, I like to follow other computational journalists or maintainers of open-source projects I use.

You can update your profile and settings by clicking on the button in the top right corner.

Public repositories also have a public page. When you like a project, you can give it a star. For example, here’s the page for the Simple Data Analysis library I maintain and we’ve been using in previous lessons. Give it a 🌟!

You can also Watch a project to see its activity in your feed. I usually watch for the releases of new versions of open-source projects I use, just to stay up to date.

Creating a repository

Let’s create your first repository! Click on the + button in the top right corner.

Then give your repository a name and make it private (so you won’t be afraid of making mistakes 😉). No need for a readme and .gitignore for now. We’ll talk about those later. Then hit Create repository at the bottom.

Now, the next page tells you how to connect a repository on your computer with the repository we just created on GitHub.

We are going to follow the steps under pushing an existing repository from the command line. Keep this page open.

Create a new folder with the same name as the repository and open it with VS Code. Add a main.ts file with a simple log for now.

console.log("Hello!");

Then initialize a new Git repository in it by running git init.

Then track the new file we just created with git add -A and then let’s commit with git commit -m "My first commit".

Right now, your code is saved with Git locally, on your computer. It’s time to save it remotely, in the cloud, on GitHub!

You can copy the instructions from the GitHub page and paste them into your terminal. Then press Enter to run them! Your URL should be different from mine, but the rest should be similar.

git remote add origin https://github.com/nshiab/my-first-repo.git
git branch -M main
git push -u origin main

Note that you’ll probably be asked to identify yourself. Follow the suggested steps. If you are asked about a password in the terminal, you won’t see what you are typing for security reasons, but typing actually works! It’s always weird the first time. 🤪

And if you refresh your repository page on GitHub, you’ll see your code synced! Your main.ts file is there and you see your latest commit.

Pushing to the repository

There is no README.md in your repository, and GitHub is (strongly) suggesting that we add one. This file’s content will be displayed on the repository page. It’s usually the first thing people will read before checking the code. So let’s do that.

As the .md extension suggests, it’s a Markdown file. Markdown is a convenient and simple syntax often used for documentation. The code will be rendered into good-looking text by the tool or platform you are using. You can focus on the content without worrying about the style, which is nice! We will write some Markdown together, but if you want to know more, check this cheat sheet.

Create a new README.md file in your repo in VS Code and copy and paste this below. As I said at the beginning, our goal will be to fetch the temperature in Montreal.

The # is used for titles. The [text](link) syntax allows you to add links to your text, and the use of backticks creates code blocks.

# My first repository
 
This project retrieves the latest temperature in Montreal from the
[Meteorological Service of Canada API](https://eccc-msc.github.io/open-data/msc-data/obs_station/readme_obs_insitu_swobdatamart_en/).
 
Here's the command to run the project: `deno -A main.ts`

In VS Code, if you right-click on .md files, you can preview them.

Our new file is on our computer. Let’s push it to GitHub. We first need to commit it:

• git add -A
• git commit -m "Adding README.md"

And there is an extra command to push:

• git push

Tada! 🪄 It’s now on GitHub! And your README is used to welcome visitors!

Creating issues

It’s time to fetch and extract the temperature in Montreal!

As we saw in the previous lesson, we try to keep the main branch clean and functional. We work on new features on branches in which we can test and break things without a worry.

In the previous lesson, we created a branch manually in the terminal. But with GitHub there is a better way: using issues.

On public repositories, anyone can create an issue. This is how library maintainers are warned about bugs or receive suggestions for new features or improvements. For example, you can create a new issue for this course or for the Simple Data Analysis library!

Click on your Issues tab in your project.

Then click on the New issue button.

Add a title and a short description (optional). By the way, the description is Markdown! And you have a button to preview what you wrote. 😏

If you collaborate with people, issues can be assigned, which is a great way to organize work. You can also give them labels.

Hit the Create button.

Your issue is now created! Each issue has a unique ID (here it’s #1), and people (or yourself 🥸) can comment on it.

To work on this specific issue on a branch, you can click on Create a branch!

GitHub will automatically generate a name for the branch and will suggest branching out from main, which is exactly what we want.

Keep the option Checkout locally selected and hit Create branch.

Copy the commands and run them in your terminal.

The branch has been created on GitHub but is not yet on your computer. This is why the first command is git fetch origin. It will sync your local repository with your remote one.

The second command is just to switch to your new branch.

Here are my commands. The second one might be a bit different if you wrote a different title.

git fetch origin
git checkout 1-return-montreal-temperature

We are now on our new branch. We can safely work on our code!

Let’s add the code from the previous lesson into our main.ts. This script pings the Meteorological Service of Canada API and retrieves data as XML. The fast-xml-parser library converts it to JSON. And the rest of the code extracts the temperature and the time before logging them.

import { XMLParser } from "fast-xml-parser";
 
const response = await fetch(
  "https://dd.weather.gc.ca/observations/swob-ml/latest/CWTQ-AUTO-minute-swob.xml",
);
const xml = await response.text();
const json = new XMLParser({ ignoreAttributes: false }).parse(xml);
 
const observation =
  json["om:ObservationCollection"]["om:member"]["om:Observation"];
 
const resultTime =
  observation["om:resultTime"]["gml:TimeInstant"]["gml:timePosition"];
console.log(resultTime);
 
const elements = observation["om:result"]["elements"]["element"];
type element = {
  "@_name": string;
  "@_value": string;
};
const temp = elements
  .find((d: element) => d["@_name"] === "air_temp")["@_value"];
console.log(temp);

Install the fast-xml-parser dependency by running deno add npm:fast-xml-parser.

And now the temperature should be logged in the terminal when you run deno -A main.ts.

Finally, commit and push your work:

• git add -A
• git commit -m "Fetching and extracting temperature"
• git push

Now, if you refresh your repository page on GitHub, you’ll see two branches. By default, the main branch is shown, but you can click on 2 Branches and explore if you are curious.

But we also have a big banner suggesting to create a pull request! Interesting… 😏

Creating pull requests

Pull requests are a request to merge a branch into another. Before approving the merge, the code is compared and the changes must be approved. Hit the Compare & pull request button on the banner.

You can then add a title and a description (optional). You can scroll down to see all the commits and changes between the two branches.

Click on the Create pull request.

You created your first PR! This is a great place to review what this request is adding to the project. Here, you can review the commits, the files, and the code. If you work with other people, you can tag them on specific lines to discuss the changes.

GitHub will check that you can actually merge the two branches and that there are no conflicts between them. You can also add automatically triggered tests to check that core features or functions of your project are not getting broken by the changes.

Here, everything looks good, so you can click on the Merge pull request button and then confirm the merge.

Once the merge is confirmed, the changes are brought to the main branch!

GitHub will suggest removing the branch we created. It’s safe to delete it now.

If we check the main page of the repository, we see that our changes are on main. You can check the main.ts file if you are curious. The issue we created has been automatically closed when we merged the PR. It’s convenient, isn’t it? 🥳

This all happened in the cloud, on GitHub’s platform. To bring the changes to your local repository, first checkout to the main branch:

• git checkout main

Then pull the changes:

• git pull

And now your main branch on your computer is synced with the remote repository!

Cloning repositories

Now, let’s imagine that your computer caught fire and is completely destroyed. 🔥

How can you retrieve all of your precious work from the cloud? By cloning the repository.

Delete the folder you worked on so far. Yes, delete it! Trust me!

On your repository page, click on the <> Code button. This is where you’ll find options to clone your code.

Copy the URL.

Next, create a new folder with the same name as your repo and open it with VS Code. Then start typing git clone, paste the URL you copied (don’t forget a space between clone and the URL), then add a space and ..

For me, the command looks like this:

• git clone https://github.com/nshiab/my-first-repo.git .

The dot at the end is important. It tells Git to clone the repo in the current folder. Without it, it will create a new folder inside your folder.

And just like that, you have recovered all of your code.

Of course, cloning is also great when you are collaborating with other people. They can easily retrieve your latest code, with all the branches and commits.

Once a repository is cloned, the next step is usually to install all dependencies with deno install. Because we have a deno.json in our project, Deno will know exactly what to install and which versions.

And then you are good to go to keep working on your amazing project!

Forking a repository

If everyone can clone a public repository (or a private one if they were invited to collaborate on it), not everyone is allowed to push to it and merge into it. And this is a good thing! Imagine the mess and the critical security problems! 😈

When you want to create your own copy of a repository, you can fork it. It will create a copy of the project in your account. You can then work on it and modify whatever you want.

It works kind of like a branch of a repository. There is no impact on the original repository, but if you want, you can create a pull request aimed at the owners of the original repository.

For example, at the time of writing, 16 GitHub users have forked the Simple Data Analysis library. I have no idea what they are doing with it and that’s okay!

If you are curious, feel free to fork it too!

Forking is how a lot of open-source contributions and collaborations happen:

• Someone creates an open-source project.
• Someone else finds it interesting but wants to tweak or fix something. They fork it, update the code, and send a PR to the owner of the original repository.
• The owner checks the PR and, if happy, merges it.
• The contribution is now part of the project and everyone can benefit from it!

Adding a .gitignore

People can clone and fork your repositories but… what if you want something locally on your computer but don’t want to share it with anyone?

For example, let’s create a new password.txt file in our repo.

This is a very important password: potato. Don't share it.

You absolutely don’t want to commit this! 🫣

If you commit it, it will be in your Git history forever. And, of course, you don’t want to push it.

For situations like these, you need to add a .gitignore file to your project. If you have one, Git will check it and ignore any folders or files listed in it. They will become greyed out in your project, meaning they won’t be tracked, committed, and pushed.

Add password.txt to it.

Now, the file password.txt will be ignored, but you still need to commit and push your new .gitignore file:

• git add -A
• git commit -m "Adding .gitignore"
• git push

On your repository page, you can now see your .gitignore, but the password.txt has been ignored and is not part of your project!

Conclusion

Git and GitHub work amazingly well together. With Git, you can keep track of your work while GitHub adds a useful interface to help you organize your work and collaborate with others.

In this lesson, you’ve learned new important Git commands:

• git push to push code to a remote repository saved in the cloud
• git pull to retrieve the latest changes from a remote repository
• git clone to copy a whole repository onto your computer

You have also learned about GitHub issues, pull requests, forks and .gitignore.

But… you might be tempted to keep creating branches locally and merging directly on your computer when working alone. Or even just to work in the main branch! 🤠

And that’s totally fine. Just find the recipe that works for you. But keep in mind that creating issues and reviewing pull requests are great ways to stay focused and review your own work! It’s also an opportunity to be comfortable with tools used by many teams and companies around the world.

Also, when we learn about GitHub Actions to automate tasks like testing, web scraping, publishing libraries and web pages, you’ll be amazed by everything this workflow has to offer.

Interested in more? Join me for the next lesson about GitHub Actions! 🤩