Working with GitHub Repositories

In a previous part of this series, you saw how to create a new GitHub account and how to customize your profile by committing a README file into a special repository. We did all this through GitHub’s web interface. In this guide, you’ll learn how to work with GitHub repositories by pulling this special repository to your local machine, making changes to your README, and pushing the changes back to GitHub.

Creating a New SSH Key

For increased security when working with remote Git repositories, it is recommended to set up an SSH key for communicating with GitHub. If you already have an SSH key set up for your current system user, you can skip to the next step.

You can create a new SSH key by running the following command on your terminal, replacing “[e-mail]” with your actual email address:

ssh-keygen -t ed25519 -C "[e-mail]"

You will be prompted to provide the location to save your key, and a passphrase. You can use the default location ~/.ssh/id_ed25519. The passphrase is like a password that adds increased security to your key, so it’s not recommended to leave it blank. You will be prompted to provide this passphrase from time to time to unlock your SSH key.

You can verify that the key was created by looking at your .ssh directory:

ls -la ~/.ssh

-rw-------  1 erika erika  464 Sep 23 19:48 id_ed25519
-rw-r--r--  1 erika erika  102 Sep 23 19:48 id_ed25519.pub

The id_ed25519.pub file is the public portion of your SSH key. You’ll use the content of this file to set up your SSH key within GitHub. The id_ed25519 file without extension is the private portion of your SSH key, and should never be shared.

Adding an SSH Key to your GitHub Account

To add your SSH key to your GitHub account, access the menu “SSH and GPG Keys” under your Settings.

Click on the “New SSH Key” button. On the screen that appears, you’ll be asked to provide a title for your key, and the public key contents. Leave the key type as “Authentication Key”. If you created your SSH key following the instructions on this guide, this is how you can obtain the contents of the public key:

cat ~/.ssh/id_ed25519.pub

Copy the full output to the “Key” field.

Click on the “Add SSH Key” to confirm.

With the key added, you are now ready to pull repositories from GitHub via SSH.

Cloning a GitHub Repository

You’ll now pull your special GitHub repository to your local system, so that you’re able to edit your README offline. Access your GitHub profile and go to your special repository. You can also access your repo directly with the address https://github.com/your-github-username/your-github-username.

Click on the green “Code” button, then click on the “SSH” tab under “Clone”. Copy the URL that starts with git@ in the text box.

Then, go to your terminal to clone the repository to your local machine:

git clone [e-mail]:boredcatmom/boredcatmom.git

You may be prompted to provide your SSH key passphrase. You should get output similar to this:

Cloning into 'boredcatmom'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (3/3), done.

You can now access your repository files directly from a text or code editor or from your terminal.

❯ ls boredcatmom
README.md

Committing and Pushing your Changes

After making the changes you want in your README.md file, it is time to commit your changes and push them back to the remote repository. Let’s review the Git workflow with this image:

This will be similar to what we did in the first article in this series, when we initiated an empty Git repository and committed a file to it. To see the current repository status, run:

git status

This should indicate that the README.md file was modified, but its not yet staged for commit. To add the file to the commit stage, run:

git add README.md

Then, commit your changes with:

git commit -m "updating readme"

Now you can finally push your commit to the remote repository:

git push origin main

Again, you may be prompted to provide the passphrase to your SSH keypair. You should get output similar to this:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 1.36 KiB | 1.36 MiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:boredcatmom/boredcatmom.git
   691417c..26edb28  main -> main

Now, if you reload your GitHub profile, it should reflect the changes made to the README file.

Congratulations! You made your first push. Now you know how to clone a repository, make changes, and send them back to the remote repository.

Creating new Repositories and Connecting Existing Repositories to GitHub

Remember the testgit local repository from the first part of this series? That repository was not connected with any remote repo, so there was nowhere to push. Now that you have your GitHub account set up, you can create an empty repository and connect it with your local testgit repo. Instead of cloning the remote repo locally, you’ll configure your existing local repository to use the GitHub remote repo as upstream. In the context of Git and GitHub, "upstream" or “origin” refers to the original or main repository from which your local repository was created, and where changes should be sent. That’s why we run git push origin main when we want to push changes to the remote main branch.

To test this out, go to your GitHub dashboard at github.com and click on the + button on the top right, then select “New Repository”.

You’ll be redirected to a form to create a new repository. Choose a name for it – it doesn’t need to be the same name as your local git repo. Add a description if you want, and leave all other fields unchecked. Click on the “Create repository” button when you’re ready.

Once the repo is created, and because it is empty, it will show you information about how to connect this repo with your local Git setup. Grab the repository’s SSH URL, we’ll need it to configure your local testgit repo.

Then, go to your terminal and access the repo that was previously initialized::

cd ~/testgit

You’ll now run a command that will connect this repo with a remote one that will now be the origin.

git remote add origin [e-mail]:boredcatmom/sandbox.git

This command will not give you any output. To update the remote repository and set your local repo to track the remote main branch as its upstream, run:

git push -u origin main

Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 1.24 KiB | 1.24 MiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:boredcatmom/sandbox.git
 * [new branch]     main -> main
branch 'main' set up to track 'origin/main'.

If you reload your repository page on GitHub, it should now have a single readme.txt file that says “Git Crash Course”. You effectively copied your local repo and all its history to the brand-new repository you created.

Conclusion

In this article, you learned how to clone repositories and push your changes back to GitHub, and you also learned how to connect a local git repository to a remote GitHub repository.

In the next part of this series, we’ll learn about Git branches and how to collaborate with other developers and work together in the same repository.