Using and understanding source code version control systems is key in becoming a software developer. At Karlstad University in Sweden where I work as an assistant professor I introduce students to source code version control every year. This means that I get a good insight into what students usually have issues understanding and also good ways in getting started in using version control. In this blogpost I would like to present a very simplified initial workflow for solo development using git only locally. I am fully aware that this workflow is not sufficient in many situations especially if you work in a multi-developer setup and also have some obvious flaws like no backup from a secondary repository storages. But remember that this is intended as an gentle introduction to a workflow that acts as the first contact with version control. I have written a set of additional blogpost entries that remedies and extends the shortcomings of this introductory workflow. Please look at:
What is source code version control?
With source code version control (SVC) we mean a tool that provides you the abilities to view and browse a complete history of your project from beginning to end and also the ability to revert to any previous state or see the differences between states. This means that we can look at our source code at different points in time and also revert to a previous version (point in time) if needed. You have probably experienced the need for this at some point if you have written any computer based documents previously, but this is even more crucial when you write source code. In this blogpost we are going to focus on using git (https://en.wikipedia.org/wiki/Git).
SVC and its relation to your IDE
You are probably using an IDE (Integrated Development Environment) for writing your source code and depending on your required IDE it may or may not have SVC support integrated already. Initially I however do not recommend using SVC functionality directly from within an IDE. I base this recommendation on three reasons:
- It is very easy the get SVC functions mixed up with IDE functions. Ie it can be very difficult to understand what the SVC system actually is doing for you. When things feel like magic this is oftentimes the case.
- Different IDEs integrate SVC functionality differently, this means that you are limited to using SVC from within one specific tool instead of knowing how to use SVC with ANY tool.
- By using SVC functionality separately you will be required to understand what it does and how you use it in itself.
Installing git
Please have a look at https://git-scm.com/book/en/v2/Getting-Started-Installing-Git and based on your choice of operating system choose one of the install methods provided.
NOTE: When installing on Windows I recommend that you use Git bash
When git is properly installed you should see something similar to this when running the command ‘git –version‘ in CLI mode (in a shell or from the command prompt)
Illidium-Q36:~ benc$ git --version
git version 2.9.3 (Apple Git-75)
Files to source control in relation to your IDE
You basically use the necessary tools required for writing source-code (like Eclipse, Intellij, Developer Studio, Atom, vim, Emacs, basically any editor). You create the files you need containing the resources you need for the piece of software you are writing. Many IDE’s manages the entire project (the set of files you need) for you and you may not even be totally aware of exactly which files you actually are creating as the tools can be very “helpful” in automating and also “assist” you with required boiler-plate stuff. This is of course very helpful when you know what you are getting help with but if not you may be completely unaware of what actually goes on with your project.
As an example lets look at a simple project in Eclipse. Basically what we have here is one java class called HelloWorld, and as you can see in the IDE this is the only file we have created and we can be mislead to believe that this is the only file we currently need to maintain in Eclipse. But in reality the IDE (Eclipse) in this case oftentimes creates a set of additional files for different purposes (which will vary depending on for example choice of IDE, language we develop in, and framework we use for development).

As you can see I have created one source code file called HelloWorld.java here. But if we look in the actual directory for the project we find that there are a lot more files and even directories there than only the expected HelloWorld.java:
.
├── .classpath
├── .project
├── .settings
│ └── org.eclipse.jdt.core.prefs
├── bin
│ └── HelloWorld.class
└── src
└── HelloWorld.java
As we can see Eclipse have generated a directory structure, compiled the source code into java bytecode, and created a set of other files. If we currently assume that all of these files constitutes our project all of these files should be kept together to ensure that our piece of software will be built in the same way every time. However we do not want to version control all IDE and environment specific files that are generated automatically or the output from a build. These files can be generated automatically when and as needed. To avoid placing these files in a git repo git uses a special file called .gitignore . As the name implies a .gitignore file tells git which files to ignore ie not version control. This also means that the .gitignore file needs to be committed before the automated files are added to the repo. If a file has been committed it will not be removed even if we add that file to our .gitignore. A good practise is to always add a .gitignore file directly after you have run git init. A set of good .gitignore files can be found at https://github.com/github/gitignore . Just choose one and add it to the root directory of your git repo.
To place these files under version control we need to figure out where the IDE placed the files on our computer and then initialize version control functionality there. This being Eclipse we browse to our workspace location and there we will find a folder with our project name.
Illidium-Q36: benc$ cd /Users/benc/eclipse/workspace-folder
Illidium-Q36: benc$ ls
source-code-management-101
Illidium-Q36: benc$ cd source-code-management-101/
Illidium-Q36: benc$ tree -a
.
├── .classpath
├── .project
├── .settings
│ └── org.eclipse.jdt.core.prefs
├── bin
│ └── HelloWorld.class
└── src
└── HelloWorld.java
3 directories, 5 files
Initializing Source Control
If you plan on utilizing a remote repository service such as Github, Bitbucket or Gitlab I recommend that you instead of creating a repository locally as described below you create the remote repository first and then clone it to your local machine. How to do this is explained in section “To create a remote repository at Github” found at https://illidiumq36.wordpress.com/2019/08/19/using-github-to-hand-in-exercises-and-labs-or-sharing-your-code-with-teammates-or-the-world/
Please note that when cloning a repository created via Github the main branch created is named 'main' and not 'master' as is the case if you create the repository via git init.
So the folder illustrated above would be the place we would like to place under version control. To do that using git we run the command ‘git init‘:
Illidium-Q36: benc$ git init
Initialized empty Git repository in /Users/benc/eclipse/workspace-folder/source-code-management-101/.git/
Now we have created an empty git repository in the same location that our IDE uses to save all our files. A git repository is a place where the history of your work is stored. It often lives in a .git subdirectory of your working directory. You can actually see this folder in the ‘git init‘ command output above.
Placing files under version control
The next step is to add all the files we would like git to version control for us, we want to place our files under version control. When using git this is a two step process. Step one is adding the files to git and step two is commiting them to git. This is illustrated below, where all our files initially are not added to git, then they are added and lastly they are committed. I use the command ‘git status‘ to check the current state of our git repository for each state change made in the repo:
Illidium-Q36: benc$ git status
On branch master
Initial commit
Untracked files:
(use "git add <file>..." to include in what will be committed)
.classpath
.project
.settings/
src/
nothing added to commit but untracked files present (use "git add" to track)
Illidium-Q36: benc$ git add .
Illidium-Q36: benc$ git status
On branch master
Initial commit
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: .classpath
new file: .project
new file: .settings/org.eclipse.jdt.core.prefs
new file: src/HelloWorld.java
Illidium-Q36: benc$ git commit -m "Initial commit, HelloWorld class created."
[master (root-commit) afcfe80] Initial commit, HelloWorld class created.
4 files changed, 43 insertions(+)
create mode 100644 .classpath
create mode 100644 .project
create mode 100644 .settings/org.eclipse.jdt.core.prefs
create mode 100644 src/HelloWorld.java
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Adding file changes to version control
Now we have added all our files to version control and the state the files are in right now are saved and in the future viewable and even revert-able if needed.
So now assume that we want to do some changes to our source code.
We start a coding session and generate some changes and some new code in our project.
As we have placed our project under version control, git now recognize this and if we do a ‘git status‘ we will see that:
Illidium-Q36: benc$ git status
On branch master
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: src/HelloWorld.java
no changes added to commit (use "git add" and/or "git commit -a")
So now we need to repeat the process of adding these changes to git and then commit them to the repository. Again I use the command ‘git status‘ to illustrate the change in state in our git repository.
Illidium-Q36: benc$ git add .
Illidium-Q36: benc$ git status
On branch master
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: src/HelloWorld.java
Illidium-Q36: benc$ git commit -m "Created a printMessage method that accepts a String and prints it."
[master 58286f4] Created a printMessage method that accepts a String and prints it.
1 file changed, 4 insertions(+), 1 deletion(-)
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Viewing the history of our source code
So now we have two commits made in our repository (two points in time for our files). We can illustrate this by using the command ‘git log‘. This command will show us the entire repository history from latest to earliest commit:
Illidium-Q36: benc$ git log
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
In gitlingo the latest commit is called “HEAD” and you can always use the word “HEAD” to refer to your latest commit. Also note that each commit has a hashed string, this is the commits unique identifier in the git repository and can always be used to look at or revert to a specific commit (point in time) for your file. Observe that you do not see the actual content of the files instead you see the commit message you give when committing. It is therefore a very very good habit to write a descriptive commit message for each of your commits. If it is good enough you can based on that choose which point in time you would like to look at or even revert your source code to.
Looking at/working with files from a specific point in time
You can always look at files from any commit at any time using git. There is however two things you should be aware of if you want to change the point in time you currently are looking at. Firstly you should ONLY do that when your working directory is clean. If you have changes not added to version control and want to look at another point in time, git will inform you of this and tell you to decide to either stash the or abandon the changes currently made. Git stashing is not a part of this inital workflow so therefore you need to have a clean working directory when you want to move to a different point in time for your files. You achieve that by either doing a
- ‘git add .‘ followed by a ‘git commit -m “message here”‘. This means you add the current state of your files to your git-repo or you do a,
- ‘git checkout — src/HelloWorld.java‘. This means that you abandon the changes you made to the file and you revert to the latest committed point in time for the file (HEAD).
With a clean working directory you can now move to a different point in time by using the command ‘git checkout name_of_commit‘.
Secondly, moving to a specific point in time in a git repository means that you leave the current ‘branch‘ in your repository and you need to move back to the branch you left when you want to continue working. Branch is gitlingo for a specific track of “point in times”. You can have several branches in one git repository where each branch reflects a unique set of file contents and a unique set of “points in time”.
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Illidium-Q36: benc$ git log
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
Illidium-Q36: benc$ git checkout afcf
Note: checking out 'afcf'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b <new-branch-name>
HEAD is now at afcfe80... Initial commit, HelloWorld class created.
As you can see in our IDE the source code is changed to the point in time for the initial commit:
If we want to move back to where we were and continue working with our source code we do a new ‘git checkout‘ this time we need to move back to our only branch ‘master’
Illidium-Q36: benc$ git status
HEAD detached at afcfe80
nothing to commit, working tree clean
Illidium-Q36: benc$ git checkout master
Previous HEAD position was afcfe80... Initial commit, HelloWorld class created.
Switched to branch 'master'
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Illidium-Q36: benc$ git log
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
And now we are back and continue developing our source code and place the changes under source control.

Undoing changes
Reverting to a previous point in time for our source code
When you have created different states in time (commits) for your files it is not very easy to remove these changes, and I think it should not be easy, the point of committing is that the states are kept. You should not think of your different commits in terms of undoing or deleting them instead what you should do is think of them as potential points in time to move back to or even better potential point in time to revert to a new HEAD. In gitlingo this means that you want to ‘revert‘ back to a previous point in time and making that point in time the current (latest) point in time. In this process you want to revert all changes made to recreate the state of the files for that point of time you want to go back to.
You should only do this when your working directory is clean. And by reverting you can actually always go back to the state you had before you decided to use another point in time. If we actually deleted a commit we would not be able to do that. So imagine we want to go back to the state of our files we had in the first commit we made we would do that using the command ‘git revert‘.
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Illidium-Q36: benc$ git log
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
Illidium-Q36: benc$ git revert --no-commit afcf..HEAD
Illidium-Q36: benc$ git status
On branch master
You are currently reverting commit 58286f4.
(all conflicts fixed: run "git revert --continue")
(use "git revert --abort" to cancel the revert operation)
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: src/HelloWorld.java
Now as we can see git instructs us to run an additional ‘git revert‘ command to complete the revert so we do that:
Illidium-Q36: benc$ git revert --continue
[master cce58b1] Revert "Created a printMessage method that accepts a String and prints it."
1 file changed, 1 insertion(+), 4 deletions(-)
Illidium-Q36: benc$ git log
commit cce58b17dbfde586f5f2bca509116bd52ee014c9
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 14:19:43 2017 +0200
Revert "Created a printMessage method that accepts a String and prints it."
This reverts commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf.
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
As you can see we have actually recorded a new point in time (a new commit) representing the “going from the current point of time back to a previous point in time”. This means that we can revert the revert if we want to. The point is that we do not remove changes made to our version controlled source code, we revert back to them if we need to, hence keeping everything in our history.
The state of our source code is now:

And we have a new commit to revert to if needed.
Deleting unstaged changes to working directory
This means that we have made changes to our source controlled files but we have not added them to our git repository and we want to delete the changes we made and go back to HEAD (latest point in time). We do that by running the command ‘git checkout — filename-with-changes-to-undo‘
So imagine we write some code and realise that this is not any good and we want to remove it completely and go back to the state we hade previously we do that like this:
Illidium-Q36: benc$ git status
On branch master
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: src/HelloWorld.java
no changes added to commit (use "git add" and/or "git commit -a")
Illidium-Q36: benc$ git status
On branch master
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: src/HelloWorld.java
no changes added to commit (use "git add" and/or "git commit -a")
Illidium-Q36: benc$ git checkout -- src/HelloWorld.java
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
Now we are back at the latest committed point in time for our source code.
Deleting staged changes
This means that we have made changes to our source controlled files and added them for source control but we have not yet committed them and we want to delete the changes we made and go back to HEAD (latest point in time). We do that by running the command ‘git reset –hard head‘
NOTE: git reset is a dangerous command that actually lets you delete points in time in your git repo.
So imagine we write some code add the changes to source control and realise that this is not any good and we want to remove it completely and go back to the state we hade previously we do that like this:
Illidium-Q36: benc$ git status
On branch master
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: src/HelloWorld.java
no changes added to commit (use "git add" and/or "git commit -a")
Illidium-Q36: benc$ git add .
Illidium-Q36: benc$ git status
On branch master
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: src/HelloWorld.java
Illidium-Q36: benc$ git reset --hard head
HEAD is now at cce58b1 Revert "Created a printMessage method that accepts a String and prints it."
Illidium-Q36: benc$ git status
On branch master
nothing to commit, working tree clean
And now the changes we made and added to source control are removed and we are back at the latest point in time for our source code.
Comparing source code at different point in time
When files are placed under source control it is usually very easy to compare the files from different point in time. This is called diffing to do that using git you use the command ‘git diff‘ and provide the two commits you want to compare:
Illidium-Q36: benc$ git log
commit cce58b17dbfde586f5f2bca509116bd52ee014c9
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 14:19:43 2017 +0200
Revert "Created a printMessage method that accepts a String and prints it."
This reverts commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf.
commit 58286f4146349fe2d889f90f3b5a4b7a724f2cdf
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:20:57 2017 +0200
Created a printMessage method that accepts a String and prints it.
commit afcfe80967a0431152f7fbb7640e77bc5f50014b
Author: benc <benc@redpill-linpro.com>
Date: Sun Apr 23 13:11:13 2017 +0200
Initial commit, HelloWorld class created.
Illidium-Q36: benc$ git diff 5828 afcf
diff --git a/src/HelloWorld.java b/src/HelloWorld.java
index 61a0c5a..d9511f1 100644
--- a/src/HelloWorld.java
+++ b/src/HelloWorld.java
@@ -3,10 +3,7 @@ public class HelloWorld {
public static void main(String[] args) {
// TODO Auto-generated method stub
- printMessage("Hello Source-code management World!");
- }
- public static void printMessage(String m) {
- System.out.println(m);
+ System.out.println("Hello Source-code management World!");
}
}
The command only shows differences and not similarities so everything not listed here is exactly the same in the both commits, except a couple of lines before and and after the differences, to enhance readability. A minus sign indicates a row existing in the first commit and missing in the latter. A plus sign indicates the lack of the row in the first commit and the existence of the row in the latter.
Workflow summary
This very simple solo developer workflow is based on no previous version control experience and specifically no previous git experience. To work efficiently I recommend frequent commits. You can not do too many commits just too few. I recommend that you do a commit each time you stop typing source code. You can even streamline the ‘git add .‘ and ‘git commit -m “message here”‘ to just one command ‘git commit -am “message here”‘ using this command will however disable your ability to delete staged changes. You would always need to do a ‘git revert‘ instead.
Natural next steps from here is to include a remote repository location for proper backups and also include branching if you want to do multi-developer projects.