Skip to content

TD-StorageBay_introduction
TD-StorageBay_introduction

setting up git

Last edited by Jackson W
Page history

Using Git on TD-StorageBay

First off: I will already assume that you know the basics of how to use Git, covered here.

Normally, Git on TD-StorageBay is handled through the GitLab interface, which should tell you most everything you need to start using Git. However, a few things are worth mentioning here:

Connection methods

TD-StorageBay Git has support for SSH and HTTPS connections to repos for pull and push connections, and both have a few unique characteristics.

  • When connecting via SSH, projects follow the form git@tdstoragebay.com:namespace/project.git where the namespace, by default, is your username.

  • When connecting via HTTPS, projects follow the form https://tdstoragebay.com/namespace/project.git, where again, the namespace, by default, is your username.

SSH

Using SSH to connect to your Git repo requires you have an SSH key associated with your GitLab account. If you have a Linux machine, then this is trivial to generate, though do make sure that you set the key size to the maximum of 4096 bits, otherwise there is a chance that you will be denied access. SSH is inherently secure, and requires no password entry.

HTTPS

Using HTTPS to connect to your Git repo only requires that you have the password for your GitLab account for you to be able to write to the repo, you can read without needing to supply anything. On a windows machine, HTTPS is probably easier to use as it doesn't require generating SSH keys, SSH being more of a Linux thing, and you are guarenteed to have the nessecary firewall ports open for HTTPS since that is the same method used to access normal webpages.

Alternatively, a Personal Access Token can be used instead of your password, create one of these through the GitLab interface. When you are asked for your password when pushing to the repo, specify the token instead.

NOTE: a Personal Access Token is the only way to authenticate over HTTPS when using Two-Factor Authentication (2FA) on your account.

Special files:

In the top level of your Git repo, there are a few special files that do special things when they are present. These files are:

  • .gitattributes
  • .gitignore
  • README (or README.md)
  • ChangeLog (or CHANGELOG)
  • CONTRIBUTING (or CONTRIBUTING.md)
  • .gitlab-ci.yml

.gitattributes

A .gitattributes file specifies certain attributes, or options, that this specific repo is using. A few programs may make changes to this file automatically. Info on the types of settings these files can modfy can be found here.

.gitignore

A .gitignore file species a list of patterns, and if a file matches one of these patterns, it will be ignored (hence the name) by Git and will not show up as a tracked or untracked file. More info on .gitignore files can be found here.

README

The README (or README.md as GitLab generates by default) is the first file that will appear in the GitLab page for your repo, shown in full, and formatted using GitLab Flavored Markdown.

ChangeLog

The ChangeLog (or CHANGELOG as GitLab generates by default) is a file that logs changes to the repo. In theory. ChangeLog files can either follow the GNU format, laid out here, although they do not have to be. This page contains more detailed information about writing good changelogs.

An example GNU format ChangeLog entry would look something like this:

2018-05-19 Jackson W <jack@mail.tdstoragebay.com>

    * git.md: Add content

CONTRIBUTING

Ideally, a CONTRIBUTING file specifies the rules for public contributions to a project.

.gitlab-ci.yml

When using GitLab CI/CD services, the .gitlab-ci.yml file specifies the actions that need to be taken to build, test, and deploy the project.

Configuring Git for GitLab

Configuring Git really only consists of two steps, setting your name and email.

Let's say you have the account named John Doe, email is jdoe@gmail.com. You would need to issue two commands to git to configure it:

$ git config --global user.name "John Doe"
$ git config --global user.email "jdoe@gmail.com"

Now, when attempting to commit changes, your user on GitLab will be attributed with said changes.

Optional: Adding a GPG key

If you want to sign your commits with a GnuPG (GPG) key, you will first have to generate one (covered here) before you can use it. But when configured your signed commits will show as "verified", and a commit signed incorrectly will display as "unverified" to warn you that something doesn't seem right. GitLab itself has instructions on how to configure Git to use a GPG key.