Basic git

Author

Government Analysis Function and ONS Data Science Campus

Git will “track” files that you tell it to track.

It will keep a history of the changes made to those files, but only for the files it has been told to track.

New files created need to be added to the repo or Git will not know the files exist. Just because a file is in the folder with .git does not mean git is aware it exists.

This is a multiple step process:

Once changes have been made to a file such as new lines of code written, or an entirely new file added to the directory, the changes need to be added. This tells Git to track the file, and keep an eye on any further changes that are made.
Once a set of files have been added, they need to be committed. This takes the changes that have been added, and commits them to the official history of the repository.

Commits include a message written by the user, which provides a summary of the changes that have been made within the commit, so the history of the repository can be easily seen, just by looking at the commit log.

We can think of this process like we are sending a parcel:

Items must initially be added to the parcel
Further items can be added or existing ones removed or changed until the parcel is ready to be sent
The parcel can be wrapped using a commit once it is ready to be sent

We can re-wrap the parcel or add more elements to it until it is in the postal system. After this it cannot be changed. How we send it to the postal system (using a push) will be covered later.

1 Status

One of the most useful git commands is status.

This shows the status of the repository, whether any changes have been made, whether there are any new files which haven’t yet been added, or whether any have been deleted or renamed. It’ll also tell you which branch you are on (more on this to come).

$ 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:  preprocessing.py

Untracked files:
  (use "git add <file>..." to include what will be committed)
  
      initialise_pipeline.py
      
no changes added to commit (use "git add" and/or "git commit -a")

This message includes a lot of useful information:

The first line states the branch the repository is currently on.
The next section (Changes not staged for commit: onwards) includes any known changes to any of the files within the repository - anything which has been previously tracked - and has had changes applied to it.
Below (Untracked files: onwards) includes the names of any file which has not been tracked.

Git is also very good at giving you ideas of commands you can use - to add files, undo changes, or commit them.

You may seem the branch names master and main being used interchangeably. Both refer to the “default” branch, i.e. typically the branch that holds the copy of the work that is considered the definitive (i.e. “non-working”) version. Any new features or changes are typically developed in other branches, and merged into main or master when they have been reviewed and are considered complete (more on merging later).
GitHub and other git ecosystem software are moving away from the default branch being called master, and replacing it with main.
For continuity, in the current version of this course we have retained the use of master for the time being, but it should be stressed this could be read as main.

2 Add

To add file modifications, or new files, the command git add is used. This needs to be followed by a parameter specifying what file or files need to be added.

$ git add preprocessing.py      # Add a specific file, preprocessing.py
$ git add directoryname           # Add a directory and its contents

Once a change or changes have been added, git status will show a different result:

$ git status

On branch master
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
  
      modified:  preprocessing.py
...

The different parameters that can be used with git add allows for flexibility in what you add to your code base. When starting out we often just use the . add all parameter for ease.

3 Commit

Once a set of files have been added, they can be committed.

This stores the changes as a permanent item in the history of the repo, with an associated message. It will only commit files that have been added, any untracked changes will not be included.

The -m modifier used below indicates that the following string (in quotes) should be stored as the message for that commit. The message should be succinct and to the point, and state the changes in an impersonal manner made within that commit.

$ git commit -m "Updated preprocessing code to handle column name variance"

[master 398a264] Updated preprocessing code to handle column name variance
 1 file changed, 2 insertions(+), 1 deletion(-)

Adding a commit message is a crucial part in documenting your code. It allows others and your future self to understand what happened at a certain point in the development.

There are a range of different style guides for commit messages, but the main point is that they should be informative and describe what has been done since the last commit.

Without an informative message it will be difficult to trace back to when a bug was added to the code making it difficult to return to before it was introduced.

We should include usful information about the commit such as a description of the type of commit:

fix - a bug fix
feat - a new feature
doc - documentation changes
and more.

An example of a style guide for version control is given in the Data Science Campus’ GitHub.

Adding the -m modifier to the command allows you to add a short message, however we will also want to add longer clear documentation to commits.

By not including the -m "commit message" part of the command this causes Git Bash to enter something called Vim. Vim is a text editor which allows the editing of code with the Git Bash terminal. For beginners it is best to avoid Vim until you are comfortable with the principles of Git.

$ git commit

Produces:


# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch dev
# Your branch is up-to-date with 'origin/dev'.
#
# Changes to be committed:
#   modified:   intro_to_git.Rmd
#   new file:   prep/Feedback.docx
#   new file:   prep/~$edback.docx
#
~
~
~
"Some command things here"

NOTE: You can enter the command section of Vim by pressing Esc. In order to exit Vim type :q, to save then exit Vim type :wq, to exit without saving type :!q the command is then followed by the Enter key.

After committing, the console will tell you how many files have been changed, and the total number of line insertions and deletions.

The seven characters after the word master are a reference to the ID of the commit message. This can be used to step back through previous commits, in case a previous change needs to be undone.

We can also add multiple descriptions to a commit. This allows us to add a brief description, and one in more detail.

$ git commit -m "consice description" -m "longer description with more detail of what has been changed"

We would use the Vim editor for even longer multi-line commit messages to best document our code. For now we will just use the -m method.

4 Log

To view previous commits, the repository log can be accessed.

$ git log --oneline

398a264 Updated preprocessing code to handle column name variance
2faebe6 initial commit of preprocessing
6bb41ce test commit

--oneline is added to make the log more succinct - each commit gets added onto one line. Without the modifer, each commit will be spread over about five lines, but carry far more detail about when it was made, and who it was made by.

Check the status of your newly created repository.
Create a text file within the directory called test_file.txt and add the following line to it:
- This is the first line of the file
- Don’t forget to save the file!
Check the status again.
Add the file to the repository.
Check the status again!
Commit the file with a relevent message
- Often, the initial commit of a new repository will be something like ‘Initial commit’!
- Make sure the commit message is wrapped in quotation marks - either single or double, as long as it’s consistent!
Check the status again.
Check the repository log. Try both looking at the full version, and the version shortened to oneline.

Question 1

Check the status of your newly created repository.

$ git status

On branch master

Initial commit

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

Question 2

Create a text file within the directory called test_file.txt and add the following line to it:
- This is the first line of the file
- Don’t forget to save the file!

Right click within the directory and press New / Text Document. Add the line mentioned in the question to the text document, and then save it.

Question 3

Check the status again.

$ git status

On branch master

Initial commit

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

test_file.txt

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

Question 4

Add the file to the repository.

$ git add test_file.txt

Question 5

Check the status again!

$ git status

On branch master

Initial commit

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

new file:   test_file.txt

We can see that our newly created file has been added. It hasn’t yet been committed.

Question 6

Commit the file with a relevent message
- Often, the initial commit of a new repository will be something like ‘Initial commit’!
- Make sure the commit is wrapped in quotation marks - either single or double, as long as it’s consistent!

$ git commit -m "Initial commit of test_file"

[master (root-commit) 86d7ea6] initial commit of test_file
1 file changed, 1 insertion(+)
create mode 100644 test_file.txt

Question 7

Check the status again.

$ git status

On branch master
nothing to commit, working tree clean

Question 8

Check the repository log. Try both looking at the full version, and the version shortened to one line.

$ git log

commit 86d7ea6cdb88bae51ef68a794a17b622b8b8784e
Author: michael hoskin <michael.hoskin@ons.gov.uk>
  Date:   Wed Feb 26 16:13:43 2020 +0000

initial commit of test_file

$ git log --oneline

86d7ea6 initial commit of test_file

Reuse

Open Government Licence 3.0