Git: Basics¶

How does Git make versions?¶

Versions in Git are based on the contents of the worktree. Worktree consists of files and directories that start from the project’s root-directory with the exception of .git-directory which contains the data of the repository. A version in Git is known as commit. A commit stores a whole version of a file only on the first save or if the file has been heavily modified. Later commits only store line changes that have been made since the previous commmit. This allows reconstruction of the worktree by simply following the chain of commits.

In practice the situation is a bit more complec.

1. The entire contents of the worktree are not stored, only the parts selected.

2. A copy of the directory is not stored in the commits, only the changes made to it since the last commit.

3. Metadata and a reference to an earlier commit are added to the stored changes.

4. When fetching a version the state of the worktree is created by building the files based on the history chain.

Other noteworthy things:

• Everything in the repository is stored in a directory called .git -hakemistoon, which typically is located at the roor of the worktree

• The contents of the .git is what is moved between repositories

• All changed are stored and additions and deletions of character strings

Commit¶

Commit is a version of the contents of the repository. It consists of the following data:

Commit’s creation consists of two phases:

1. Selecting changes to be stored in commit

2. Finalizing the commit and adding a description for it

Commits are prepared in staging area known also known as index. The things added must be working as intended. In a good commit, the changes form a small and easily describable set.

Using Git¶

Git has more functionalities than commands. Commands are overloaded which means that their functions can be altered with different parameters.

GUIs separate these functionalities to own UI-elements, but command line uses switches.

Here are some examples:

• git add <path> adds paths content to index

• git add --all adds all content to index

• git add -p <path> starts interactive addition to index based on path’s content

Git has many security-feature that may block the user from using some of the commands. These features are in place in order to protect version history and local changes from accidental destruction. Never use –force to go aroung these safety features.

For example: You can’t revert to an older commit if you have unsaved changes in the worktree. However you can specify to return certain version of a file even though there are unsaved changes to it.

The main difference between these two cases is that in the latter one user specifies that he wants to change the modified file to something else. In the first one user can’t be sure what files would be overwritten so the change to modified file might be accidental.

* Committed - The files current state is stored in previous commit.
* Modified - The file has changes that aren't stored
* Staged - The file has changes and the changes are staged to index.
* Untracked - The file is created but it's not versioned or staged.

Data preservation in Git¶

Almost evey operation in Git adds data to version history. If you remove a file, Git still stores the previous versions of it and only marks that the file isn’t required in the current version of a worktree. This means that once you store something in Git, it stays there.

It is possible to remove all traces of the file in Git but this requires rewriting the history starting from the version it was first created. DO NOT DO THIS LIGHTLY This isn’t an easy task and it is prone to mistakes. There are even situation where rewriting is practically impossible. So be sure you never store anything unwanted in Git like passwords, private keys or sensitive information. For this reason it is important to have the .gitignore file of the repository in place The role of .gitignore is to make sure that the files commonly in the working tree but totally irrelevant from the point of view of the project do not end up versioned.

Examples to .gitignore:

build-*

Filters out all paths that start with “build-”

*.o

Filters out all paths that end with “.o”

local_configurations.py

Filters out a file called local_configurations.py

html/

Filters out html folder

!build*.py

Allows all paths starting with “build” and end with “.py” if these paths were filtered out with previous rules

Usually you’ll create a single .gitignore to project root folder. You’ll add all your rules to that single file. You’ll commit this file to your repository to be shared with other developers.

What should or shouldn’t be stored in Git?¶

Git handles files in text-format and is only interested in line changes. This means that text-based files - like source-code - can be easily tracked. More complex files like pictures or videos are problematic. Even the smallest changes may seem like a completely different file to Git. This means that Git stores the whole file again which takes more space. This can quickly bloat a simple project to be +100MBs.

Neither should you store any files that are generated directly from the stored files. If they’re generated you are basically storing the same information twice. This forces you to maintain both versions. For example binary-, moc- and object files are generated from the source-code.

It’s even possible that generated files are in conflict with other systems and can make version control a nightmare.

There are some special exceptions where there needs to be saved version from a generated file. (For example release documentation or patch-files)

What you should store:

• Working source-code

• Platform independent configurations and settings

• Documentation

• Required static material

What you shouldn’t store:

• Broken source-code

• Generated content

• Passwords and keys

• Sensitive information

• Videos and graphics*

* Exception with small pictures that are required in the project. You should use some other system to distribute large and non-text-based files