🌱 Install and Use Git¶

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance.

This documentation details the following procedures:

basic introduction of git
installation of a git server on linux
creation of an empty git repository
installation/configuration of a git website using gitlist

🧭 Basic Git usage¶

📝 Basic Git commands¶

The default branch of Git were commits are pushed is "master".

git-workflow

Basic Git commands

git status                              # see the current status of files for git
gitk                                    # see status graphicaly
git add files                           # add files to staging (waiting to be committed)
git add -A                              # add all files and folder to staging
git rm files                            # remove files to be committed
git restore files                       # removes the changes that weren't committed
git commit -m "message"                 # commit the files added 
git branch test                         # create a branch "test"
git checkout test                       # switch to the branch test
git branch -D test                      # remove a branch "test"

Tip

To remove permanently everything that is referenced only in the reflog execute the following commands:

git reflog expire --expire-unreachable=now --all && git gc --prune=now

📚 Basic Usage¶

The following section explains how to create a local repository.

Create a local-repository

# quick steps to initialize a local repository
cd source-directory
git init                                        # initialize an empty local git repository
git commit -m "initial release" --allow-empty   # push an empty commit to allow full-rebase afterward
git status                                      # display the status of files in the repos

# mask all object files and binaries for status command
touch .gitignore                                # create .gitignore file
nano .gitignore                                 # edit file
    .vs
    Debug
git add .gitignore                              # add files to be committed
git commit -m "add .gitignore file"             # commit the files
git status                                      # see status

🧠 Advanced Usage¶

🧨 Rewrite History¶

It's possible to rewrite the history of the local repository using git rebase.

Rewrite history

git rebase -i HEAD~3                            # edit history of git with the last 3 commits
git rebase -i commit^                           # edit history of git using the first 7 characters of the git hash
git rebase -i --root                            # edit history since the first commit

Usefull options

Field	Description
`edit` or `e`	rework the commit to allow split/add/remove files
`squash` or `s`	merge the commit
`reword` or `r`	reword the name of the commit

It's possible to add/remove/split files from a commit by resetting it's state to the previous commit:

git reset HEAD^                                 # reset state to the previous commit to allow add/remove/split files

🧩 Create and Apply Patches¶

Create patchApply patch

# create a patch from a commit
git format-patch -1 <sha>

# create n commits (here: 1)
git format-patch -1 HEAD

# apply the patch to a file
git am < file.patch

🗂️ Git LFS¶

🧮 Introduction¶

Git LFS is an open-source project and is an extension to Git. The goal is to work more efficiently with large files and binary files into your repository.

📖 Description¶

git-lfs Git is a distributed version control system, meaning the entire history of the repository is transferred to the client during the cloning process. For projects containing large files, particularly large files that are modified regularly, this initial clone can take a huge amount of time, as every version of every file has to be downloaded by the client. Git LFS (Large File Storage) is a Git extension developed by Atlassian, GitHub, and a few other open source contributors, that reduces the impact of large files in your repository by downloading the relevant versions of them lazily. Specifically, large files are downloaded during the checkout process rather than during cloning or fetching.

Git LFS does this by replacing large files in your repository with tiny pointer files. During normal usage, you'll never see these pointer files as they are handled automatically by Git LFS. When a Git LFS file is pulled to your local repository, the file is sent through a filter which will replace the pointer with the actual file. The actual files are located on the remote server and the pulled actual files are located in a cache in your local repository. This means that your local repository will be limited in size, but the remote repository of course will contain all the actual files and differences.

📦 Installation¶

The Git LFS extension should be automatically installed with Git.

Install Git LS extension

sudo apt install git-lfs

🏷️ Create a Git LFS repository¶

Initialize git-lfsAdding files to trackRemove unreferenced lfs files

# initialize a git repository
mkdir <dir> && cd <dir>
git init
git commit --allow-empty -m "initial release"

# initialize git-lfs in this repository
git lfs install

# tracking binary files
git lfs track '*.exe'
git lfs track '*.dll'

# see a list of all patterns currently being tracked by git-lfs
git lfs track

# see the list of tracked binary files by git-lfs
git lfs ls-files

# push the .gitattributes
git add .gitattributes
git commit -m "activate git-lfs by tracking files and pushing .gitattributes"

# remove permanently everything in git lfs that is referenced only in the reflog
git lfs prune

Important

Don't forget to track files using git lfs track '*.xxx' after the git lfs install then commit the .gitattributes file.

🖧 Install Git server¶

The git-core package needs to be installed. The user git will be added to the system.

Installation

# install git
sudo apt-get install git-core

# add git user
sudo adduser --disabled-password --disabled-login git
sudo passwd git

The git server will be accessible through ssh git@hostname.

🔑 Configure Access with SSH¶

To simplify Git operations and avoid typing your password every time, you can use SSH key-based authentication.

This process involves:
1. Creating a public/private key pair on your local machine.
2. Installing the public key on the remote server.

Once done, you can securely connect without entering your password manually.

For the full procedure, please refer to Install SSH Keys.
Use git for REMOTE_USER.

🏗️ Create empty Git repository¶

Create the git-repository on the folder of the server.

Create git repository

# create a root git-repository
mkdir -p <dir>/git
chown git:debian <dir>/git

# create symbolic links
sudo ln -s <dir>/git/ /git

# login as git user
su git

# create an empty repository
cd <dir>
mkdir -p <project.git> && cd <project.git>
git init --bare

Replace Fields

Replace the following fields:

Field	Description
`<dir>`	the directory where all the git repos will be installed
`<project.git>`	the name of your git project on the server

At this point the git repository has been created on the server and ready to be used by a git client.

📤 Pushing commits¶

The git repository needs to be cloned before pushing the first commits.
Clone the server git repository on a client machine then push a commit to the *server.

Pushing commits

# create git directory on the desktop
mkdir <git-project> && cd <git-project>

# clone the git reposiroty located on the server
git clone ssh://git@<hostname>:<port>/git/<project.git>

# push first empty commit
git commit --allow-empty -m "initial release"
git push origin master

Replace Fields

Replace the following fields:

Field	Description
`<git-project>`	the name of the git project on the desktop
`<hostname>`	the ip address or hostname of the git server
`<port>`	the ssh port of the server (22 by default)
`<project.git>`	the name of the git project on the server

Don't pay attention of the following warning: "You appear to have cloned an empty repository."

🪝 Setup Git Hooks¶

Git hooks are a rather simple concept that was implemented to address a need. Git hooks are event-based. When you run certain git commands, the software will check the hooks directory within the git repository to see if there is an associated script to run.

Info

The goal here consists on building a website everytime a commit has been pushed on the server. A post-update hook will be configured in the server-side bare git repository to execute the script. A build directory which clone locally this repository will be configured to generate the website.

🛠️ Create build directory with ACL rights¶

nginx and git need to have access to the build directory.
The git user will be added to the group www-data.

Add user git to www-data group

sudo adduser git www-data

Tip

When the repository to clone is local and use the file system, the credentials aren't required.
It's usefull for the git hook script: post-update.

Create the build directory

# create and set build directory rights
mkdir <build-directory>
chgrp www-data <build-directory>
chmod g+s <build-directory>
setfacl -m group:www-data:rwx <build-directory>
setfacl -dm group:www-data:rwx <build-directory>

Info

Replace <build-directory> by your build directory).

Setting unix right using ACL

The chgrp www-data set the group of the build directory to www-data.
The command chmod g+s sets the set group ID (setgid) mode bit on the current directory. This means that all new files and subdirectories created within the current directory inherit the group ID of the directory, rather than the primary group ID of the user who created the file.
The setfacl -m group:www-data:rwx set the current group rights to rwx (x allows to enter the directory).
The setfacl -dm group:www-data:rwx set the default group rights for newly created files to rwx.

🧲 Clone the local repository¶

Clone the local repository

# clone the local repository using file system
cd <build-directory>
mkdir <repos> && cd <repos>
su git
git clone </path/to/repos.git> .

Important

Replace </path/to/repos.git> by the bare git repository directory.

🔁 Create Git hook¶

Server-Side Hooks: These hooks are executed on servers that are used to receive pushes. The post-update hook will be used on the server-side, it is run only once after all of the refs have been pushed.

repository.git/hooks/post-update.sampleEnable post-update hook

# add the bash hook script content here

mv post-update.sample post-update

Tip

In order to enable any of the scripts in hook directory, we have to remove the .sample suffix.