Git

Whether you code or write documents, often you end up with multiple versions of the same file. You may want to archive one set of changes that are not needed at the moment, then send another set of changes to your colleagues for a review. At a certain point, keeping track of all these versions becomes unfeasible.

Tools like Dropbox or Google Drive, which you may know already, can help a bit. These tools allow you to share your files easily, or to restore their content to an earlier point in time. Here's an example:

Unfortunately, you can only see different versions of a single file. Also, it's hard to tell which version you might want to restore since there is no indication of how individual versions differ. A relatively large project wouldn't be manageable with this approach.

Therefore, programmers tend to use more powerful tools called version control system (VCS). Currently, the most popular one is Git, and we'll learn more about it in this lesson.

Real programs are rarely created by a single person. Two heads are better than one, so it's better to work on a project in a team.

Each team member needs to be able to share their progress with others. Git can be used exactly for that: you can set up a shared repository online that your team members will synchronize with.

Installation

The process of installing Git is described here. If you have skipped the lesson before, you might want to get back to it now.

Repository

Each project that you want to version-control needs to be stored in its own directory. Create a new directory now and navigate inside (use the command cd). Then, create a new Git repository using the command git init:

$ mkdir lessongit
$ cd lessongit
$ git init
Initialized empty Git repository in ./.git/

At first glance, it looks like nothing happened. This command created a hidden directory with the name .git and stored some information about history in there. You can see the file using ls -a (Linux) or dir /a (Windows). .git is a hidden directory because it is managed only by Git and you shouldn't be changing anything inside.

The repository is empty for now - it does not have any files or history. You can see for yourself by invoking git status, a command that shows information about the state of the repository:

$ git status
On branch main

Initial commit

nothing to commit (create/copy files and use "git add" to track)

“On branch main” refers to so-called branches, we'll get back to that later. “Initial commit” means that there is no commit stored yet. And “nothing to commit” says that there are no files to be saved and versioned in the directory.

First commit

We will now switch for a moment to a plain Text Editor (not Microsoft Word but for example Notepad) or optionally Code Editor (VS Code).

Now create a new text file there, write/copy a short poem text inside and save it in the folder where you originally did git init in your command line. Name the file poem.txt and do not forget to save it after you made the edits.

As a quick source of totally unbiased texts to work with, you can have a look here:

The file should span at least five lines so that we have enough to work with. Then, try executing git status again: Git reports that there is a new file in the directory and that it isn't managed by Git yet.

$ git status
On branch main

Initial commit

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        poem.txt

nothing added to commit but untracked files present (use "git add" to track)

We need to make Git track each new file explicitly. Let's do that for the file with your poem:

$ git add poem.txt

Then check the state of the repository again:

$ git status
On branch main

Initial commit

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

        new file:   poem.txt

The lines in green (“changes to be committed”) will be included in the next batch of changes (a commit) that you will create. Let's create our first commit and add a commit message "First commit" via a "-m" suffix:

$ git commit -m "First commit"
[main (root-commit) 1a009f4] First commit
 1 file changed, 6 insertions(+)
 create mode 100644 poem.txt

Congratulations! Your first commit in the repository is finished!

What would happen if you did not add the -m "message" - read the text below. Otherwise you can skip the text block.

Try reporting on the repository again:

$ git status
On branch main
nothing to commit, working tree clean

This short report means that nothing has changed since the last commit. That is expected since we've just commited all our changes!

Now let's have a look at what has changed in the last commit. Execute git show:

$ git show
commit 1a009f4267d5a6ab7ece87cb7514f5b803692e39
Author: Adéla Novotná <adela.novotna@example.cz>
Date:   Mon Mar 20 14:51:34 2017 +0100

    First commit

diff --git a/poem.txt b/poem.txt
new file mode 100644
index 0000000..558d133
--- /dev/null
+++ b/poem.txt
@@ -0,0 +1,6 @@
+Holka modrooká, nesedávej u potoka
+Holka modrooká, nesedávej tam
+
+V potoce je hastrmánek
+Zatahá tě za copánek
+Holka modrooká, nesedávej tam

Notice the unique Git commit ID that allows you to return to this state of your project at any point in the future. The author's name, the date of this commit's creation and the commit message are also listed, along with the summary of changes: a new file poem.txt containing the text in green has been added.

> set LC_ALL=C.UTF-8

Second commit

Make a small change in your poem; replace one word, change punctuation, or add a new verse. Then check the status of the Git repository again.

$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   poem.txt

no changes added to commit (use "git add" and/or "git commit -a")

The file is shown in red again. Something has changed inside! To see the details, execute the command git diff.

$ git diff
diff --git a/poem.txt b/poem.txt
index 558d133..24e2384 100644
--- a/poem.txt
+++ b/poem.txt
@@ -1,6 +1,9 @@
-Holka modrooká, nesedávej u potoka
-Holka modrooká, nesedávej tam
+Holka modrooká
+Nesedávej u potoka
+Holka modrooká
+Nesedávej tam
 
 V potoce je hastrmánek
 Zatahá tě za copánek
-Holka modrooká, nesedávej tam
+Holka modrooká
+Nesedávej tam

The changes are shown on a per-line basis. The lines in red beginning with - indicate the original lines that have been removed; the lines in green starting with + show the newly added lines.

It is easy to see what exactly has changed since the last commit. If your program stops working, but the last commited version still worked, use git diff – one of the changes listed must have introduced the error!

If you are satisfied with the changes, stage them for the next commit:

$ git add poem.txt

As usual, check the status of the repository; the file in green will be included within the next commit.

$ git status
On branch main
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   poem.txt

Before we finalize the next commit, let's talk about the best practices in formulating the commit messages. There are common conventions that most programmers follow: the first line summarizes the changes, the second line is left blank, and the following lines list the reasons for the change or describe the changes themselves in more detail. Each line should have under 70 characters in length; the lenth of the comments (lines starting with #) can serve as a guide here. It is not worth going into detail for changes that are trivial or obvious; rather, focus on the broader context and reasons for the changes. Anything that can help whomever will try to understand the changes in the commit; this might include you few months later.

My commit message will be the following:

Split long lines

Typically, each verse of a poem goes on its own line. I think
that it's easier to read like this. (Although, the real reason was 
to demonstrate git diff.)

Finally, use git commit to create your second commit, and then check it using git show:

$ git show
commit 81cbabb3bd3cd2f3896dd41b20012c44dbd69031
Author: Adéla Novotná <adela.novotna@example.cz>
Date:   Mon Mar 20 14:51:34 2017 +0100

    Split long lines

    Typically, each verse of a poem goes on its own line. I think
    that it's easier to read like this. (Although, the real reason was 
    to demonstrate git diff.)

diff --git a/poem.txt b/poem.txt
index 558d133..24e2384 100644
--- a/poem.txt
+++ b/poem.txt
@@ -1,6 +1,9 @@
-Holka modrooká, nesedávej u potoka
-Holka modrooká, nesedávej tam
+Holka modrooká
+Nesedávej u potoka
+Holka modrooká
+Nesedávej tam
 
 V potoce je hastrmánek
 Zatahá tě za copánek
-Holka modrooká, nesedávej tam
+Holka modrooká
+Nesedávej tam

Diagram

These two diagrams below visualize what each command demonstrated thus far does exactly, and how the changes move from “not staged” to “commited” and back in case of need.

Diagram showing the process of viewing and committing changes:

Now that we have created our first few commits in the repository, let's demonstrate more commands that will help us understand the whole history of our Git repository. The first command is git log.

$ git log
commit 81cbabb3bd3cd2f3896dd41b20012c44dbd69031
Author: Adéla Novotná <adela.novotna@example.cz>
Date:   Mon Mar 20 14:51:34 2017 +0100

    Split long lines

    Typically, each verse of a poem goes on its own line. I think
    that it's easier to read like this. (Although, the real reason was 
    to demonstrate git diff.)

commit 1a009f4267d5a6ab7ece87cb7514f5b803692e39
Author: Adéla Novotná <adela.novotna@example.cz>
Date:   Mon Mar 20 14:51:34 2017 +0100

    First commit

git log prints all commits starting from the newest one and going all the way back to the initial commit at the origin of the repository.

When there are so many commits that they don't fit on a single screen of your command line window, you can browse back and forth using PgUp/PgDn. Finally, exit by pressing q.

To see all details about any commit, execute git show 5ff0b, replacing 5ff0b with the first few characters of the Git commit ID.

Conclusion

These are the Git basics that we'll need in the following lessons. Whenever you perform git add file and git commit, the current version of the file is saved and will be accessible even if you delete the file later. You can always view any past version of any file in your repository, and review all changes made since the last time the project was saved.

Maybe all this sounded unnecessarily too complicated for a beginner. Indeed, our projects will be relatively simple and easy to manage even without the use of Git. But it's a good idea to learn using it from the very beginning; when you get to participate in bigger projects, already being used to Git will come very handy.

So, from now on, whenever you make even a small but meaningful change to your program, as long as the program works at least as well as it did before, use git add and git commit to save the change in Git.