GitHub is a web-based platform that serves as a central hub for software development. It allows programmers to collaborate on projects, share code, and track changes to their codebase. GitHub is widely used by developers of all skill levels, from beginners to experienced professionals. It provides a powerful set of tools for managing software projects, including version control, issue tracking, and project management. With GitHub, it’s easy to work with others on projects, share your code with the world, and contribute to open-source projects.

GitHub CLI is a command line interface tool that allows you to interact with GitHub from your terminal. With it, you can create, manage, and view repositories, pull requests, issues, and more. It’s designed to be fast and efficient, allowing you to perform common GitHub tasks without leaving your terminal.

The CLI is available for Linux, macOS, and Windows. In this guide, we will focus on the Linux version of the tool.

To use the CLI, you’ll need to have a GitHub account and have it set up on your local machine. Once you have the CLI installed, you can start using it to perform a wide variety of tasks from the comfort of your terminal.

On this guide we will get started by setting up an SSH key, which will allow you to authenticate with Github securely without having to enter your username and password each time.

Next we will take a look at some of the most commonly used commands and we will setup an example repository.

Let’s get started !

Setup an SSH key #

Normally when you work with git you’ll be prompted for a username ans personal access token in order to interact with your remote repositories. By setting up an SSH key on your machine and connecting it with Github you can bypass this process making the whole git workflow faster.

To generate a new key we’ll need to open a terminal and use the command ssh-keygen

$ ssh-keygen -t ed25519 -C "your_email@example.com"

The flag -t specifies the type of key to generate, in this case ed25519. -C is used to add a comment to the key, which is typically an email address. your_email@example.com should be replaced with your actual email address. This command will prompt you to choose a location and a passphrase for your new key. By default, the key will be saved in the .ssh directory in your home folder with the filename id_ed25519.

This command will create a private and a public key which are by default located under the hidden .ssh folder inside your $HOME directory.

Next we will add our private key to the ssh-agent . We know the key is located in ~/.ssh/ and by default its called id_ed25519 so we will add that to the agent using the ssh-add command.

ssh-add ~/.ssh/id_ed25519

Finally we will add our public key to our Github account.

To add the key to our github account we will need to visit the Settings page. Click on your profile picture and select Settings Next under the Access menu click SSH and GPG keys

Click on the button that says New SSH Key

In the “Title” field add a descriptive label like for example “Work Laptop”.

Under “Key type” select “Authentication Key”.

In the “Key” field add the contents of your public key which is : ~/.ssh/id_ed5519.pub

When you are done click “Add SSH key”.

NOTE:

Even if we’ve setup an SSH key, if you want it to function properly with a repository you have already cloned using HTTPS instead of SSH you need to update the URL for the repository to use SSH. Run the following command :

git remote set-url origin git@github.com:USERNAME/REPOSITORY.git

Replace username and repository with your own.

Working with Git #

Installing git #

First we’ll need to install git on our machine.

To install Git on Linux, open your terminal and use the following command:

$ sudo apt-get update
$ sudo apt-get install git

This will update your package manager and then install Git on your machine.

Once Git is installed, you can verify that it was installed correctly by running the following command:

$ git --version

This will display the version of Git that is currently installed on your machine.

While the above instructions are specific to Ubuntu and other Debian based distributions, the process of installing Git on other Linux distributions is similar. However, the specific commands used to install Git may differ depending on the package manager used by your distribution.

For example, if you’re using Fedora, you can install Git using the following command:

$ sudo dnf install git

If you’re using a distribution that uses a different package manager, consult your distribution’s documentation for specific instructions on how to install Git.

General Github Workflow #

The github workflow involves several steps that utilize git commands to ensure that changes are properly managed and reviewed before they are merged into the main codebase. Here is a general overview of the process :

1. Fork the repository: To work on a project hosted on GitHub, you can start by forking the repository to create a copy of it under your own GitHub account. This will allow you to make changes to the codebase without affecting the original repository.
2. Clone the repository: Once you have forked the repository, you can clone it to your local machine using the git clone command. This will create a local copy of the repository that you can work on.
3. Create a branch: Before making any changes to the codebase, it is recommended to create a new branch. This can be done using the git branch command. The branch should be named after the feature or bug that you will be working on.
4. Make changes and commit them: Once you have created a branch, you can make changes to the codebase using a text editor or an integrated development environment (IDE). After making changes, you can use the git add command to stage the changes and the git commit command to commit them to the local repository.
5. Push the changes to the forked repository: After committing the changes to the local repository, you can use the git push command to push the changes to the forked repository on GitHub.
6. Create a pull request: Once the changes have been pushed to the forked repository, you can create a pull request (PR) on the original repository to request that the changes be merged. The PR should include a description of the changes and any relevant screenshots or documentation.
7. Review and merge the changes: The PR will then be reviewed by the project maintainers or other contributors. They can leave comments or request changes to be made. Once the changes have been approved, they can be merged into the main codebase using the git merge command.
8. Update the forked repository: After the changes have been merged into the main codebase, you should update your forked repository using the git pull command. This will ensure that your local repository is up-to-date with the latest changes.
9. Delete the branch: Once the changes have been merged, the branch can be deleted using the git branch -d command.

In this guide we won’t be forking any repository. Instead we will create our own and work from step 3 onward.

Creating a new repository #

On your home page at github click on the “New” button to setup a new repository.

In our case since this is a mere example we will take github’s suggest of short and memorable repository name of “stunning-potato” and set it to be a Private repository. Click “Create Repository” after you’re done.

Our repository is now created and is available at https://github.com/YOU/stunning-potato . Now we can return to our terminal and interact with this remote repository using git.

Working towards our first push #

First, create a folder somewhere that will contain your project. Open a terminal and navigate to said folder.

Inside we will create a simple README.md markdown file for our codebase.

echo "#stunning-potato" >> README.md

This command will simply create the README.md file and append at the end of its contents (which in our case is the beginning of the file since it is empty) the string “#stunning-potato” without the quote marks which in markdown translates to a header 1 which says “stunning-potato”. If you don’t know what i am talking about, you will see the results once we push our changes to the repository.

Next we will initialize the repository using git-init .

Now that we’ve initialized our local git repository, we need to add our new readme file to it using git add .

git add README.md

After we’ve added the file we need to commit it to the repository and add a descriptive message that explains what we’ve done in a simple manner using the git commit command

git commit -m "First commit, added a README file"

The -m flag allows us to add a message to our commit and is recommended for every commit you do as it makes tracking changes to the codebase easier.

Before we move on to pushing our changes let us do a couple of things. First let us determine the name of our main branch and then connect our local repository to its remote counterpart over at github.com

git branch -M main
git remote add origin git@github.com:dark-side-droid/stunning-potato.git

git branch is the command for managing git branches. More about branches later on. -M is the flag that specifies that the branch should be renamed and “main” is the name we’ve appropriately chosen for our main branch.

When using the git remote add origin command take note that in this case dark-side-droid is my github username and correspondingly stunning-potato is the the name of my repository so you should replace them with your own.

Now that we’ve set everything up we can finally push our changes to our remote repository.

git push -u origin main

Everything should work great, and we can now head over to github.com in our browser and see our changes reflected in our repository’s page. We should be able to see our README.md file, alongside its commit message and we should be able to see that we are currently on the main branch.

To further investigate the github workflow lets add two more files in our local repository “file1.txt” and “file2.txt” and push them as well.

touch file1.txt file2.txt

Like we did before, we need to add them to the repository for the tracking of changes but this time we won’t type the git add command once for each file. This time around we will use git add . which adds every file in the current directory.

git add .

As usual commit the changes and then push. This time we won’t need to tell git which origin we are working on since we’ve already done that.

git commit -m "added 2 text files"
git push

After successfully pushing our two text files should be in our remote repository.

Revert #

Suppose however that we’ve made a mistake and we’ve pushed the wrong files in the repository and we weren’t supposed to do that. How do we correct our mistake ? Well github tracks every change we’ve made to the repository using the git log command followed by the git revert command. When we use the command we get the following output.

commit 280ae2d7b89d361eac029ebccc91a06335b1e8c9 (HEAD -> main, origin/main)
Author: Andrew V <emailhere>
Date:   Sun Apr 30 11:11:42 2023 +0300

    added text files

commit 5fb55c403ab4a545df669adc22222487482c827a
Author: Andrew V <emailhere>
Date:   Sun Apr 30 10:58:57 2023 +0300

    First comit, added a README file

We can see our two commits, who made them, the comments we added using the -m flag on our commit and so on. Since we have a problem with the commit which added the text files we can use the git revert command to delete this change.

git revert 280ae2d7b89d361eac029ebccc91a06335b1e8c9
git push

That hash corresponds to the commit ID that we can read in the output above. We use git push to forward our changes to the remote repository. Of course if we want to revert the revert we can follow the same procedure of git log since the revert operation is included in the log as a commit.

Great ! Lets move on to branches.

Working with branches #

Branches are an essential part of the github workflow. Whenever we have any changes to make to our codebase instead of altering it and possibly causing any damage we can instead create a new branch of our code and test our changes on that second branch. If our changes work as intended, we can then merge the two branches and introduce our changes to the main branch.

To create a new branch use the git branch command followed by git checkout to change our current working branch. Usually when we create a new branch we name it according to the feature we are adding or the bugs we are working out and so on. In this example we will use the name “testing” for our new branch.

git branch testing
git checkout testing

Now that we are working on our new testing branch, let us add a new file and push the changes to our remote repository.

touch file3.txt
git add file3.txt
git commit -m "adding new file"
git push -u origin testing

All of the commands above should be recognizable by now. We create a new file, add it and commit the change with a message and push it to the testing repository. If we head over to our browser check our repository we should see our changes reflected on our repository including our second branch, and the new file which is present only on our “testing” branch.

Let us suppose that our changes are exactly what we wanted and everything is working as intended. The next step is to switch back to the main branch and and merge it with “testing”.

git checkout main
git push

Since we’re done with out testing branch let us now delete it.

git branch -D testing

The -D flag deletes the branch even if it has not been merged. Alternatively you may use -d as a safeguard which will only delete the branch if it has been merged. This command will only delete the new branch locally. If you want to delete it from the online repository as well use the following :

git push origin --delete testing

Additionally we can remove all branches that have been deleted locally with git remote prune origin.

Git Pull #

When we are collaborating with other people, it is a relatively common occurrence that someone updates the codebase while we are working on it. If we want to be working on the most recent version we may create a git pull request.

git pull origin main

This command fetches and merges the changes from the remote repository with our own in one step. Alternatively

git fetch origin
git merge origin/main

The fetch command will update your local repository’s knowledge of the remote’s history but it wont update anything yet. When we run the merge command it will merge the changes from the remote repository’s “main” branch into our local repository’s current branch.