Git and GitHub

1. What is the purpose of this document?

This document aims to show you how to use Git and GitHub in as simple and easy-to-follow steps as
possible to create version-tracked and easily shareable documents.

However, for this, some basic concepts must first be clarified to understand why it is worth using Git and
GitHub, what version control is and why it is better to use this method than, for example, to create
separate Word documents and manage the content through it.

When people hear Git or GitHub, they immediately think developers use them for coding, tracking
conversions, collaborative code development, etc. And this is indeed true, as both tools are prevalent
among developers. But the purpose of this document is to explain comprehensibly, even for non-
developers, how to use these two tools effectively to create content and prove that ‘general users’ can
also use them successfully in many cases.

2. What is version control?

There are two fundamental aspects to consider when creating content:

The first is that we can track the changes made to the content; we know when and who made what
changes to the given content, and we should also be able to return to any previous versions if we see
that the latest version is not the best.

The second aspect is that the content we create should be easily shareable: others can express their
opinions as efficiently as possible and make suggestions for improving the content. Also, the content
creator should be able to integrate these improvements and modifications into the latest version easily:
version control is about controlling and tracking different versions of a given project.

A sound version control system (VCS) tracks and records changes to any file (or group of files), allowing
you to revert to earlier versions when necessary. Version tracking enables team members working
elsewhere in space and time to communicate with each other and develop specific content.

The most significant advantage of version tracking is that everyone sees the latest content and can make
constructive comments and suggestions, thereby improving the quality of the given content.

3. What is Git?
Git is a distributed, open-source version control system.

By distributed, we mean there is no central data repository, but its users download the Git source code
to their machine and use it to modify the content they create (code, text and other types of content).

Git is open-source because it can be freely used, copied, distributed, studied and modified.

Git is also a version control software: actually, it is so popular that Git is used by more than 90% of
professional developers.

1
With its help, you can store your created content, perform version tracking, and send it to GitHub.

4. What is GitHub?
GitHub is a cloud-based repository hosting service that allows team members to work together and
manage their content.

A repository (usually abbreviated as “repo”) is where all files belonging to a given project are stored.
Each project has its own repo and can be accessed via a unique URL.

Github has three main functionality groups: a cloud repository, a collaborative development platform
and a project management tool.

If you want to create and develop content, you can do it without GitHub. Git is perfectly sufficient so
that you can return to an earlier version of the given content at any time by using its version control
capabilities, and you can also store the content in it. Therefore, you do not need to look for a cloud
service provider but store the data locally on your computer.

However, in the case of locally stored data, there is a considerable risk of complete data loss in the
event of a computer failure.

Most people create backups to avoid this. In the case of backup copies, however, there is no explicit
version tracking, and especially if the version number of a particular piece of content increases a lot, it
makes it very difficult to perform proper version tracking. After a while, we will not know which version
has changed and which has not. Another huge disadvantage of storing content locally is that it makes
joint work with others almost impossible.

To solve these burning problems, GitHub was born in 2008 to make working with Git as easy as possible.
Today, Git and GitHub are complementary technologies that help each other work together as efficiently
as possible.

The content created in Git is saved and stored in a remote repository on GitHub, and we make changes
to the content either in Git or directly on GitHub and take advantage of the benefits provided by these
popular tools.

If, after this, you think you give a chance to use Git and GitHub to create content, then please stay with
me and let’s get down to business: let’s see how to install Git, create a repository on Github, create
content and develop it collaboratively.

5. How to install Git?

The best way to install Git is to go to the official Git website, choose your operation system and
download it from there. Git supports all operating systems, and the process is hassle-free. Once the
download is complete, run the installer and follow the steps required.

There are various options during installation, but the default settings are sufficient for most users.

2
After choosing your installation options, the installer installs Git on your computer.

Git is designed to be used by more than one person. After successful installation, use the Git Config
command and set the username and user email address you want to use. Since Git is a terminal without
having a usual user interface, this code should be written in the Git command line interface as follows:

git config --global user.name “your-user-name”

git config --global user.email “[email protected]”

The global option ensures that every project on your computer will use the same name and email
address. You may use your GitHub email address here if you already have a GitHub account. After the
installation, please verify that Git has been installed correctly: open your comment prompt and run the
command as follows:

git --version

After hitting enter, your current Git version should be displayed and look something like this:

git version 2.42.0.windows.2.

6. How to initialise Git?

Once you configured Git, the next step is to prepare the folder that will hold the project. With the
following command, you can initialise an empty repository on your machine:

3
% git init

When you initialise Git, it creates an invisible folder called .git in the project folder, where Git stores all
the information about the project. Git is going to write these files for you and take care of keeping track
of what the project is doing.

In order to create an entry that we can go back to, we have to add the files to the staging environment.
With the add command, staging is a temporary area where we can store files that we want to commit
later on; you use the git add command and specify the file name that you want to move to staging:

% git add FILENAME

The last step in the process is to commit the files with the commit command. Look at the commit
command as if you had pressed the save button in a regular application: we are creating a ‘snapshot’ of
our content, a point to which we can return later if necessary.

You always need to include a message for this, and the syntax for that is as follows:

% git commit -m “First commit”

It tells Git that this is one of the checkpoints you want to track for your project so that you can return to
it later.

6.1. Why is it so important?

Do you remember we said that Git is a version tracking software, the essence of which is to log the
changes of a given file or content over time and to be able to view any previously created version at any
time?

For each commit, it is worth giving a short but good description of what kind of change you made so that
when you look back in three months or half a year, you can still remember what that change was.

Also, let’s not forget that the ‘soul’ of Git and GitHub is cooperation, collaborative work, content and
code sharing (open-source projects), and in light of this, your commit comment must be understandable
to others as well.

7. How to set up the first project?

In order to create a functional project, the following steps must be taken.

1. Set up a remote repository on GitHub to create your first project.

2. Link your local repository to the remote repository (clone a repo).
3. Push changes to add your local files to the remote repository.
4. And then, finally, you need to learn how to fetch any changes that have happened in the
repository and pull those changes onto your local machine.

4
7.1. Set up a remote repo
Go to the GitHub website, create an account, or log in to your existing one. Go to the Home of GitHub
(GitHub Dashboard) and click on the Create New Repository button:

Give a name to your repository and give a short description. GitHub checks whether the repo name is
available or not. Then, decide whether you want to create a public (anyone on the Internet can see your
repo) or a private repository (you can choose who can see and commit to your repository):

Adding a Readme file to your repository is always a good idea. This markdown file will be your ’business
card’ to other GitHub users, where you can provide a longer description of your project (so when you
share your private or public project with others, they will understand what it does and how it works).
Click the ‘Create repository’ button to generate your first remote repo on GitHub.

5
Your first repository has been created on GitHub.

7.1. Clone a repository

There are several ways to do it. If you do not like using terminals, you may clone (copy) your GitHub
repository (remote repo) to your computer using the GitHub Desktop’s user interface.

Another option can be to use a tool like Visual Studio Code (VS Code) and add the GitHub Repositories
extension to it. First, download VS Code, then click on the extensions tab on the left:

6
Choose the ‘GitHub Repositories’ extension. This extension allows you to open and edit remote
repositories quickly and conveniently.

Once the extension is installed, click on the GitHub button in the lower left corner so that the below
options appear in the top search bar:

Next, choose the option ‘Open Repository from GitHub’.

7
Finally, choose the repo you are looking for from the list of your GitHub repos. In our test case, we are
looking for the repo we just created on GitHub (TestRepo):

Your remote repository opens up locally within your Visual Studio Code:

The same repository looks this way on GitHub:

8
Congratulations, you have created the link between the local copy of your repository and the one in the
cloud on GitHub.

7.2. Push changes to GitHub

I made some changes in the local machine and sent them (by using the push command) to GitHub. I
added a new line, “Now I am making some changes :- ).”

This change can be seen on different parts of the screen (the modifications are marked on the screen
with the numbers below):

1. After the name of the file, the capital ‘M’ indicates the change
2. On the left pane, the Source Control button shows a change (there is one change)
3. The branch indicator at the bottom of the screen also shows with an asterisk that there is a
change
4. In the text area, you can also see the change (the application indicates the modification with a
light blue vertical wavy line in front of the change):

What was changed becomes visible if you click on the light blue vertical wavy line. It can be beneficial in
case there are many changes in the file so that you can easily compare the versions:

9
Click on the Source control button on the left:

Navigate to the message field (which is circled in red in the figure below):

And make a clear and descriptive message about the change you made. Then, click on Commit and Push:

10
The Source Control button becomes inactive, just like the ‘Commit ＆ Push’ field:

It means that you committed (sent) your changes to GitHub. These changes become visible once you log
in to GitHub and open your repository. Your comment message is visible next to the filename that
contains the change (README.md). The file itself is open in the lower section of the screenshot, and the
text change is also visible:

11
 7.3. Fetch changes to your local machine
When you fetch changes, the process is the opposite of what was described above: changes may have
occurred on GitHub (if you are not working alone on a specific project, there is a real chance of this
happening).

In the case of fetching changes, you open Git or a terminal (i.e. Visual Code Studio) and query whether
changes have been made on GitHub. If so, you copy those changes to the local repository.

To mimic the process, I intentionally make changes to the test repository (TestRepo) on GitHub, save
those changes, open the local repository with Visual Code Studio and copy the changes on my local
machine.

First, go to your repository on GitHub and open the file you want to change. There are several ways to
do that: you may click on the filename to open the file or click on the pencil icon to edit it:

Then, on the next page, click on the pencil icon:

12
In the editor, make some changes to your file. Once you are ready with your modifications, click on the
‘Commit changes’ button:

The commit changes window pops up, and GitHub auto-populates the ‘Commit message’ field with the
‘Update your filename’ message. You can keep this text, but it is worth entering a clear, short text that
better describes the changes and can be understood later, even by you or your colleagues (or other
GitHub users). So, instead of the below,

You may use something similar to this:

13
Next, click on ‘Commit changes’. You may leave the radio button on ‘Commit directly to the main
branch’ since you do not want to create a new branch at this stage. In the new screen, you can read the
text of your commit:

With a commit, you save the changes and form a point on the theoretical timeline of content creation,
which you can return to at any time during the content development.

If you log in to Visual Studio Code, the changes become visible (circled in red):

14
What if VS Code is open while a change is made on GitHub? To model this scenario, I added a new
sentence to my file:

And saved (in ‘Git and GitHub language’ committed) my changes:

To make the changes in VS Code visible, the only thing you should do is open the repository (which has
been changed) and click on the Refresh button:

15
Do not worry if you do not know which repository was changed: by clicking the Refresh button, the
editor (VS Code) will indicate which repository was changed.

8. Why do you need these two environments?

The philosophy of Git and GitHub is based on the fact that we do not work alone; instead, several people
work on the same project (or even several people work together on several projects), and the changes
are saved in a central repository. The local version of the environment is called Git, whereas the central
cloud-based repository is called GitHub.

Typically, you work on your local repo and send your changes (Push) to GitHub. This usually happens
even if many people work on the same project: developers and content creators work locally on their
own computers, and after completing their work, they send their changes to GitHub.

To avoid conflicts in the content, every time we start our work in the local repository on our computer,
we request from Github with a pull command any changes that someone made in the meantime until
we last opened the repository on our machine.

Also, to avoid content/code conflicts, we push the changes to GitHub whenever we finish work on our
local machine, thus maintaining the latest code in the cloud repo (GitHub).

It is best to follow this working method and get used to this kind of workflow since, in most cases, we do
not work on the content alone but in collaboration, which significantly facilitates successful joint work.

Please note that the statements made here are elementary, and the Git workflow itself can be much
more complicated than this. However, to start working on a specific project, the most important thing is
to understand the Git Push and Git Pull commands so that data conflicts do not arise and your
cooperation with others can be successful.

The diagram below from the DataCamp website represents very well what kind of ‘transitions’ there can
be between local and remote content and how we can always store the latest content in the central
location.

16
 9. What if you do not want to use the editor?

Not everyone likes to use the command line since you have to learn commands to use it. With an
intuitive and well-designed user-friendly user interface, many activities can be solved with a couple of
mouse clicks without typing command lines.

If the terminal is difficult to use or users are very averse to it, there is an option for users to create,
manage and develop content without command lines through the GitHub interface.

This chapter is about creating and managing content on the GitHub interface alone, without using a
terminal (or any type of editor, like VS Code), and how to share content with others and develop it
collaboratively.

I use the same test repository (TestRepo) to demonstrate the above goals.

9.1. How to create a new file?

Open your repository, click the ‘Add file’ button and choose the ‘Create new file’ option.

17
A new window opens, where you can name your file (1), create content (2) and save your changes
(commit changes(3).

I also added the extension ‘md’ to create a markdown file. Next to the name, you can see that the file
was created in the ‘main’ branch. Above the editing area, you can find the ‘Edit’ and the Preview’
buttons. You are in ‘Edit’ mode while you are editing your file. If you want to see your changes, please
click the ‘Preview’ button.

After you are done with the changes to make, click on ‘Commit changes’, write a commit message and
write an extended description if the description of changes requires a longer explanation:

18
Once you click ‘Commit changes’, you are redirected to the repository’s main page showing all the files
and folders (if any):

9.2. How often should you make commits?

The answer to the question is more complicated than it seems at first. Perhaps we could understand and
answer this question in the simplest way if we looked for the answer to why it is necessary to commit in
Git and GitHub. Similar to saving a file, a commit takes a snapshot of the current state of the file.

Although GitHub automatically saves changes, there should be often points during the development of
content that can be returned for some reason.

So, the answer to the question is that it is necessary to commit when creating some logical element or
idea in the content has been completed. That is, you can close some logical unit, or some goal has been
achieved.

19
What kind of logical content or what goal can be set during content development is influenced by what
the content itself is.

If, for example, we are coding on the GitHub interface and the goal is to create a specific feature, then it
is worth committing (i.e. adding a point in the development process where we can go back and check
later whether it really works or another solution we need to find and then the code needs to be
developed) if the given feature has been coded.

If the task is to write an article or prepare a report, then the logical unit after which it is worth
committing is the completion of a chapter or, in the case of a report, the preparation of a statement.

Git assigns each commit a unique ID, called a SHA or hash, which identifies the changes since the
previous commit. If you commit every time you change a line of code (when you are coding) or after
each paragraph (in case you write an article), it will be hard to read the commit log and determine
precisely when and what happened and which previous version could possibly be reverted to if we
wanted to fix something.

If you are working on a project alone, it does not matter how often you commit. But even in this case,
the description of the commit should be meaningful so you can remember what change you made when
you read it.

9.3. How to add images to your project?

Pictorial illustrations are essential elements of content creation; they greatly help and simplify the
understanding of the text and also facilitate navigation in the content. In this chapter, we look at how to
add images to your markdown files in your GitHub repository.

9.3.1. Commit the image directly to your GitHub repository

Use a local image that is committed to your GitHub repository. However, instead of placing images in
the root of your project, it is much better if you create an ‘Images’ folder within your repository to
organise your image files and project better. In the screenshot below, you can see a project in which a
separate ‘img’ folder was created for the images, making the folder structure more transparent:

20
It is perhaps one of the simplest methods; however, it has a significant drawback: you have to store the
images locally, and if you store many images, they can increase the size of your repository.

Besides that, you need to be aware of the syntax of adding an image in a markdown file, which is as
follows:



The Alt text (alternative text) describes the appearance or function of an image on a page. The alt text is
read aloud by screen readers used by visually impaired users. Then comes the relative path to the
image. It is a good practice to plan in advance what kind of folder structure you create on your computer
so that you can manage the images more efficiently. This method is best used when we do not have
many images.

9.3.2. Use a remote file

Another option is to use an external file storage service (e.g. Dropbox, Google Drive, etc.). In this case,
you can get the direct and full URL of the image and then use it directly in your markdown file. You may
also use other sources and tools for free images, and you can use the availability of the image where the
given image is stored at the given service provider. Such sources include Unsplash, Pexels, Pixabay,
Canva, and Flickr, for example.

The method is the same, but the link to the image points to the service provider’s page (where the
image is stored). So instead of using this:


In the markdown file, you may use something like the below:

![Alley, Street, Umbrellas image from Pixabay Image by Fabien - Pixabay Ambassador from Pixabay](/
https://cdn.pixabay.com/photo/2023/10/02/16/20/alley-8289479_1280.jpg “Street Umbrellas”)

21
So, if you use the above reference in your markdown file, the below image will show on the screen:

But do not only think of the well-known file storage providers mentioned above (Dropbox, Google Drive,
OneDrive, etc.). You can also use open-source markdown editors to store your files, such as HedgeDoc,
where you upload the image and only use the link generated by the editor. The only important thing is
that the link should point to a hosting provider that you can use in your markdown file. In the example
below, I show the link to the above-mentioned markdown editor (HedgeDoc), which I am using in my
markdown file (and it has the same syntax):

The only weak point of this solution is that you have no control over how long that image will be stored
in that location. That is if the path of the used image changes (because it was either deleted or saved
elsewhere by the service provider), then the given image will not appear in the markdown file of your
GitHub project.

Fortunately, there is nothing to be afraid of since these service providers are connected to millions of
users and provide them with access to these images, so the service provider is not interested in the goal
of frequently changing the access path of the images.

22
 9.3.3. Upload an image file to GitHub

You may upload an image to GitHub and use it to host your image for you. It is more like a workaround
since GitHub does not have a feature specially developed for uploading images. For that purpose, add
your images to some comment (an issue, a pull request, etc.) and copy the URL generated by GitHub.

You can directly drag and drop your image from your computer to a comment field on GitHub. Once the
file is uploaded, a URL is generated, which you can copy-paste into your markdown file.

So open your repository, click ‘Issues’ and create a new issue.

Name your issue, call it ‘images’, ‘image library’ or something similar. Then, locate your file on your
machine and drag and drop the file/files as a comment.

This way, you are uploading your image to GitHub, and at the same time, GitHub generates a link to your
newly uploaded image, and you can use that link to refer to that image by pasting it into your markdown
file.

23
https://www.seancdavis.com/posts/three-ways-to-add-image-to-github-readme/

![Create an issue 1 600](https://github.com/attilacsontos/TestRepo/assets/61838279/dca65de4-1810-

418e-9902-914c558cafd7)

10. Collaboration with GitHub

As mentioned, Git and GitHub were created for collaboration to help work together to achieve a specific
goal. It is no wonder that even in this document describing the basic functions, it is necessary to
mention how we can work together on GitHub after creating our own repository and working on a
specific file.

Considering that this document describes the essential functions and we are trying to explain things as
simply as possible, let’s ignore the use of Git and focus on how we can collaborate only on GitHub.

24
For the collaboration to work, either access to the repository must be given to others (if we are the
owner of the given repo), or others must copy the repository and then send the changes to the owner of
the repository and request that the changes should be incorporated into the content.

10.1. Shared repository model

In this case, the contributors get access to a shared common repository. They create separate branches
to create their own content, and when they are ready, they send a pull request to the owner of the
parent repository.

Pull requests perform the same function as any other GitHub collaboration model: they initiate code
reviews and general discussions about changes before merging them into the main development
branch.

The simplified outline of the practice of branching – Atlassian blog

The creation of branches is necessary so that the collaborators cannot change the primary content (main
branch) but must first propose the development of the content during a pull request (which, if accepted,
will become part of the main branch and, thus, the content will develop).

10.2. Forking a project

In this case, you want to contribute to an existing project you cannot access. When you fork a project,
GitHub creates a copy of the project, which will be entirely yours, and you can work on it as you see fit.

Project owners do not have to worry about adding users as collaborators and give them push access:
GitHub users can fork any of the projects they can find on GitHub.

You can quickly check whether anyone forked (copied) your repository. On the main page of the
repository, there are several places where GitHub indicates whether your repo was copied or not:

25
Forking a project is very easy: visit the main page of the repository (project page) and click on the ‘Fork’
button:

Before forking, you usually search among the repositories. When you come across a repository that
might interest you, you can copy it to your local machine with one click (Fork). The above repository is
the MISP project of CIRCL.

You can see how many people are following (Watch), forked (Fork) and liked (Star) the repo:

These data clearly show how significant and popular the given project is.

26
27
 Purpose: to create simple documentation on how to use GitHub in a simple way, for
non-technical users, so that we can share some of the documents such as the
Thunderbird Userguide with the community.
 Expected outcome : a document, which describes in an understandable way (for non
technical users) how to
1. install git (optional if everything can be done from the web interface)
2. create documents
3. collaboratively modify and maintain these documents

Possible documentation on how to add images in GitHub .md texts

https://www.seancdavis.com/posts/three-ways-to-add-image-to-github-readme/

Useful Git-related links:

https://www.freecodecamp.org/news/how-to-use-git-best-practices-for-beginners/
https://rogerdudler.github.io/git-guide/index.html
https://git-scm.com/book/en/v2
https://www.datacamp.com/tutorial/github-and-git-tutorial-for-beginners?
utm_source=google&utm_medium=paid_search&utm_campaignid=19589720824&utm_adgroupid=143
216588537&utm_device=c&utm_keyword=&utm_matchtype=&utm_network=g&utm_adpostion=&utm
_creative=675429089965&utm_targetid=dsa-
1947282172981&utm_loc_interest_ms=&utm_loc_physical_ms=9063043&utm_content=dsa~page~co
mmunity-tuto&utm_campaign=230119_1-sea~dsa~tofu-tutorials_2-b2c_3-row-p2_4-prc_5-na_6-na_7-
le_8-pdsh-go_9-na_10-na_11-na-
oct23odp&gclid=EAIaIQobChMI3oq8uZThgQMVnpqDBx0fcg7tEAAYASAAEgLUz_D_BwE

https://www.datacamp.com/blog/all-about-git

28
https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-
collaborative-development-models

https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

https://github.com/tholman/intense-images/tree/master/demo/img

29