An introduction to version control using git and GitHub

You might be thinking “Really? Another blogpost about using git and GitHub?” – because the internet is full of them allready. And I agree, but bear with me, I have good reason for writing this blogpost. The short version is that I along with some colleagues, have created a Teams app for sharing knowledge internally (I’ll write a blogpost about the app too – at some point). And a big part of this knowledge sharing is a github repo (its public so you’re welcome to take a look). To make sure everyone in the company knows how to use the repo – and have a ‘resource ‘guide’ too look at if they forget – I chose to write this blogpost. I could of course have made this resource internally, but sharing is caring, and it might be usefull for someone else too.

Disclaimer This blogpost is mainly focused on how to get up and running with git and github for the specific reason of contributing to the PointTaken/knowledge-sharing repo. But it might be usefull for anyone that is new to version control, git and/or github

Table of contents

• What is git and Github
• A (very) short introduction to the concept of version control systems
• Getting started – setting up your environment
• Clone or Fork the GitHub repository
• Add a resource and push the changes
• Keeping your fork updated
• Summary (TL;DR)

A (very) short introduction to the concept of version control systems

As the naming suggests a version control system (VCS) is a way to control different versions of your resources. It does not have to be code resources, it could be (almost) any type of file. A lot of people do this manally by saving a document with different names like: "mydoucumet1.docx", "mydocumentNew.docx" and "mydocumentFinished.docx" – looks familiar?

What a VCS does is keep track of your different versions without you having to rename any files. It also provides you with tools to revert back to a previus state, show you when, who and what changed ++.

Working with a repository

When we work on projects in software development we keep our code and resources in a repository. And this repository is typically hosted somewhere that everyone on the team can get access to. Then the team members clone a copy of this repository to their local computer, and use the VSC, in our case git, to handle the versions and changes accross the copies of the repositories.

Branching and merging

I could write another (long) blogpost about branching and different branching strategies, but for the purpose of this git-introduction I will just give a quick explanation about what branching is, and how it can be used.

In every git repository there is a main branch. You could all work on the same branch all the time, but that tends to create merge conflicts. So it is best practice to create a branch based on main to develop your feature/fix a bug etc, and the merge the branch back to main. At the same time your co-worker can create their own branch and work in parallell on some different feature.

A short intro to the basic git lifecycle stages

• Commit – A commit is a selection of files/changes that you would like to package together and push back to your main repository.
• Add/stage – When you have created a new file, or make changes to a existing file in the repository you need to ‘mark it’ as ready for a commit. You do this by adding/staging the changes.
  If you have files/changes that you want to keep out of your commit – don’t add/stage them.
• Push / Pull – You use pull to get the latest changes from your main repository. And push to push your commit(s) to the main repository.
• Pull request – A pull request is created as a safety/quality step between your changes and the main branch. This can be in your own repository – or from your fork back to the origin repository (as we will cover in this blogpost).

The git ignore file

There might be some files in your repository that you don’t want to be in the VSC, to make git ignore a file or a folder – just add a .gitignore file, and the file/paths inside the file like shown in the image below. (Often this file is genereated for you when you scaffold a code project, but you can still add to it)

Getting started using git and GitHub – setting up your environment

Install git

Firstly you need to download and install git. I would also recommend that you download Windows Terminal and add a git-bash profile to it for easier access, but you will get git bash as part of your git download so feel free to use that on its own.

Or if you prefer to have a visual interface GitHub desktop is a great tool, or you can use the build in tool in VS Code.

Create a GitHub user

To work with the repository used in this blogpost you need a github account.

Download VS Code

You don’t neeeed to have VS Code to work with the files in PointTaken/knowledge-sharing, but it does give you some great tools – like markdown preview – and integrated git tools (if you don’t want to use the CLI). And also, thats what I’ll be using in the examples in this blogpost. You can download VSCode here.

Clone or fork the GitHub repo

Whats the difference – Fork vs Clone

In short: A clone creates a linked copy of a repository where you work directly against the origin repo. But a fork creates an independend copy where you work against your own copy – and then create pull requests to ask if you can merge your changes back to the main repo.

Typically if you have ‘edit priveledges’ on a repository – you clone it. If you only have read access – you fork it.

In this blogpost we will use a forked copy of the repository and create a pull request to push changes back to the main repository.

Create a fork

Go to PointTaken/knowledge-sharing repository on GitHub. In the upper right corner of the page you can see there is “Forks” option.

Click on the small arrow next to it and select “Create a new fork”. This will present you with a dialog where you can give your fork a name etc, no need to change anything, just go with the default settings and click the “Create fork” button.

When the fork is created you will have your own copy of the repository on your GitHub profile, it will also show where the fork originates from.

Create a local clone of your forked repository

In your new forked repository, select the green Code button, and copy the repo url.

Now its time to open GitBash on your computer. You can either open Git Bash directly and navigate to the folder where you would like to keep your local repo. Or use File explorer and go to the folder where you want it – then right click and select “More options” / “Git Bash here”.

Then write git clone and the url you just copied – and hit enter.

When the cloning is done, navigate into the repository by writing cd knowledge-sharing (and press enter). Now you will get some blue text inside parentheses at the end of the line – this shows you that you are inside a git repo – on the main branch.

Create a new resource and push the changes

Open the repo folder in your prefered editor – I recommend using VSCode. Create your resource in the appropriate folder.

Remember to give the resource a descriptive name, and use a prefix to show what type of tech thats being used. E.g “ADD-staleUsers” or “JS-Vue-AppToUploadFiles”. There is a markdown template file you can use as a starting point.

When your resource is ready you want to push it back to your forked repository and then create a pull request back to the PointTaken repository. I’ll show you how to do it using git in VSCode, and using Git Bash (CLI). I prefer to use the CLI so I will cover that first, but if you’d rather use the GUI in VSCode you can jump to the next section.

Using Git Bash to add, commit and push your changes

In git bash write git status too see what files/folders have been changed since your last commit.

In the above image you can see that the new sample I added shows up ass “untracked”. To add (stage) the file use git add <file-path>.

Afterwards, if you run git status again the file will show up as staged/ready to commit.

To commit the changes simply write git commit -m "A descriptive commit message"

And then all you have to do is write git push to push your changes back to your GitHub repo.

Now you can move on to making a pull request back to the PointTaken repository.

Using VSCode to add, commit and push your changes

You can find git tools in VSCode by selecting the version control symbol in the left side menu.

Stage (add) a file to source control by right clicking it and select “Stage changes”

When the changes are staget it will show up under “Staged”

Now you can commit your changes. Add a descriptive commit message and click the commit button.

When your changes is commited you can push them back to your GitHub repository by clicking “Sync changes”.

And thats it, now you can create a pull request back to the Point Taken repository.

Create a pull request to get your changes in the Point Taken repository

Go back to your forked repository on your GitHub profile. Here you can see that your main branch is X commits ahead of PointTaken:main.

To create a pull request against PointTaken:main, select the small arrow next to “Contribute”, and then “Open pull request”.

Fill in a title to your request, and a description. Then simply click “Create pull request” – and you’re done.

Keep your fork updated

When there has been changes in the PointTaken version of the repository it will show up as “This branch is X commits behind PointTaken:main“. To get the latest changes into your forked repository select “Sync fork” and then “Update branch”.

Summary

Git is a version control system (VCS), and GitHub is a hosting service for git repositories.

To work with the PointTaken/knowledge-sharing repo you need to

• install git, VSCode and create a GitHub profile.
• Create a fork of the PointTaken/knowledge-sharing repo – this will show up on your GitHub profile.
• Clone your forked repo to your computer (using git clone <repo-url>)
• Add your resource to the appropriate folder. (Remember to give the resource a descriptive name, and use a prefix to show what type of tech thats being used)
• When you are happy with how your resource looks add/stage it, commit, and push it back to your fork.
• Create a pull request from your fork back to the PointTaken/knowledge-sharing repo.

Git CLI commands

//Clone an existing repo into current directory
git clone <url>

//This gives you an overview over the files that have been changed - and if they are tracked or not
git status

//Add a specific (updated) file
git add <file-path/filename>

//Add all updated files
git add .

//Create a commit for the changes in the staging area
git commit -m "write your descriptive commit message here"

//Push commit(s) back to your repo
git push

---

Did you find this article usefull? Follow me on twitter to be notified when I publish something new!

Also, if you have any feedback or questions, please let me know in the comments below. 🙂

Thank you for reading, and happy coding!

/Eli