GitHub Basics in the Eyes of a Technical Writer…

Nowadays, GitHub can be considered as the most popular collaboration platform that is used in developing software. The main reason that makes it popular is the ability to get more contributors involved to build a community around the software that is being developed and its documentation.

Therefore, it is quite important for anyone who is involved in the process of developing software to learn the basics, workflow, and architecture of Git.

I am writing this blog to manifest my experiences with GitHub as a beginner and from the perspective of a Technical Writer. I hope this blog will help my fellow technical writers and also newbies to understand the basics of GitHub.

• Creating a new repository
• Forking the created repository
• Cloning the forked repository
• Adding the upstream as a remote
• Fetching content from the upstream
• Epitome

Let’s start the journey around the basics of GitHub!

Creating a new repository

An “Organization” is the primary component of GitHub and a “Repository” is the secondary component. Your source codes are stored and maintained in conceptual containers called “repositories” under organizations in the GitHub servers.

Follow the steps below to create a new repository in GitHub.

1. Log in to GitHub.
2. In the upper right corner of the screen, click the + sign next to your avatar or identicon, and then select New repository.
3. Enter the preferred name for your repository.
4. Write a short description.
5. Select Initialize this repository with a README.
6. Click Create repository.

This original repository created in the GitHub server is called the “upstream”.

There will be conflicts when many people try to contribute to the same repository simultaneously. Therefore, to avoid this, Git is architectured based on the concept of getting a copy of this upstream into your machine and doing the edits locally as shown in the below diagram.

Forking the created repository

After creating the repository, the first thing we should do is to make a copy of the upstream, which, in Git terms is referred to as “forking” or creating a “fork” of the upstream. Basically, when you fork a repo, it will be moved to your preferred organization from its original.

You can fork the repo using the provided option as shown below.

Tip: You will be prompted to select the preferred organization to which you want to fork the repo.

Cloning the forked repository

Next, we need to “clone” the fork to our local machine. Follow the steps below to clone it.

1. Click “Clone or download” in the screen of the forked repo.
2. Click the Copy button to copy the URL of the forked repo.
3. In a new Terminal tab, navigate to the preferred location in which you want to save the cloned repo and execute the below command.

git clone <URL_OF_THE_FORK>
E.g., git clone https://github.com/wso2-docs/my-new-repo.git

This creates a clone of the forked repo in the given location so that you can do the required edits locally in it.

Adding the upstream as a remote

You need to always keep the cloned repo updated and synchronized with the upstream. For this, you need to create an alias named “upstream” and set the URL of the upstream to this alias to point the clone to the upstream.

In GIT terminology, this is referred to as adding the upstream as a remote. You can do it by executing the below command.

git remote add upstream <UPSTREAM_REPO_URL>
E.g., git remote add upstream https://github.com/praneesha/my-new-repo

Tip: In the Terminal, if you navigate to the cloned repo and execute the “git remote -v” command, you should view a list of all the “remote” entities of the upstream (i.e., origins and upstreams) that are already configured. You can do this to ensure that the origin and upstream are set correctly to the cloned repo.

Fetching content from the upstream

After adding the upstream as a remote, you can fetch all of its content to the cloned local repo whenever required.

The source code of a repo is stored in conceptual snapshots called “branches”. By default, every repo will have a “master branch”. When you clone the forked repo, only the master branch of it will be cloned from the fork to the local copy.

Therefore, to fetch all of the other branches of the upstream to your cloned repo, you need to execute the below command.

git fetch upstream

Tip: In the Terminal, if you navigate to the cloned repo and execute the “git branch -a” command, you will view all the branches that are available.

Epitome

Given below is a summary of what was illustrated in this blog.

The above are all one-time tasks that you need to do with respect to a particular Git repo.

My next blog will be about how to engage in your day-to-day routine work by doing edits locally in your cloned repo. Stay tuned!