Introduction

Git is a distributed version-control system designed to manage changes to text files (e.g. source code). Rather than making backups of entire files, Git works by maintaining a history of changes to particular lines in a source file. In this manner, it is able to track a long history on a code library without wasting memory to keep track of sections of code that haven't changed. Each time a piece of code is changed, those changes are 'committed' to Git with a 'commit message' and a 'diff' - a visualization of exactly what changes were made. These changes can be tracked on several 'branches' which act as specialized historians - one to keep a history of working, publishable code (releases); and others to keep a history of changes during the implementation of bug-fixes or features. By convention, each commit comprises one context/action which can be summarized in 50 characters (see Atomic Commits and Why Atomic Commits), and each branch comprises one complete feature or bug-fix.

Git histories can be shared/distributed amongst multiple developers by setting up a 'remote'. This is a central server which holds the code's history. Others can access that server to get a copy of the code, and they can push their contributions to the remote in order to share with others. This allows for multiple people to work on the same code project without waiting on each other, and it keeps the versioning history backed up in several places - on each user's machine, as well as on the remote server. More advanced users can take advantage of features in git and remotes that allow them to test code before allowing it to be committed or pushed, enforce style guidelines for code, and cleanly manage work being done in several different areas of a code base.

Gitlab is one such server, and it is the one MOST will use for storing code. Best practices for managing git repositories are not covered here, but many of the links in this page offer useful information in that regard.

Create an Account

Go to Gitlab to create an account. When asked who will be using Gitlab, select 'My Organization or Company'.

To gain access to the group on Gitlab, contact Dr. Pearce.

Security

It is recommended that you enable 2-Factor Authentication on your account. In the upper right, click on your gravatar and go to `Settings > Account` to enable 2fA.

When interacting with Gitlab using Git on your computer, you can either provide your credentials (username and password) to git, or use an SSH key. SSH keys are basically credentials generated by an algorithm, stored on and specific to your device. You provide half the key to Gitlab (`Settings > SSH Keys`), then your computer uses the other half to verify itself with Gitlab. This means you don't have to remember your password, but your key could get stolen if a hacker accesses your computer. Read more on credentials versus SSH keys here.

Linux users create an SSH key by following Gitlab's instructions directly in the Terminal. Windows users (those more prone to prefer a GUI than a command line) should use Sourcetree, which can generate an SSH key (`Tools > Create or Import SSH Keys`) or store credentials. After creating a key, provide the public half to gitlab according to their instructions.

Creating a Repository

To get started on a repository for MOST, go to our group on Gitlab and create a new project. Gitlab nicely provides prompts for all of the pieces of information to create, including a `LICENSE`, `README.md`, `CHANGELOG` and more. To get a local copy of the repository, clone it. There will be a button on the top right to help you get the necessary information.

Standards or repository templates for the MOST group have not been created at this time.

Transferring a Repository

Whether moving an existing local repository onto Gitlab, or transferring from Github or the likes, the process is essentially the same. First, follow the steps in #Creating a Repository, making sure to not generate any files (Gitlab will offer to create a README). Then, the empty repository will explain exactly what commands to use in the terminal in order to set the new repository as your `origin`. To do this in Sourcetree, follow their instructions.

Linking to OSF Integrations

To link a repository to OSF, you need to grant OSF 'application access' to your Gitlab account. To do this:

1. Go to Gitlab
2. Go to your user settings and select 'Access Tokens'
3. Type in a name specific to the OSF repository you are granting access to.
4. Leave the expiration date empty, unless you have a reason to want OSF to lose access.
5. Check the following permissions:
   • `read_user`
   • `read_api`
   • `read_repository`
   • The others should not be necessary, as OSF isn't capable of modifying your repository, nor should it be. Check other boxes only if you and Dr. Pearce deem it necessary. Checking these boxes will grant permission to OSF to access public *and* private repositories.
6. Create the token. You'll have to copy the code right then and there.
7. Provide the access token to the OSF repository according to their procedure (Check the `Add Ons` tab in the repo if that link is broken).
   • At time of writing, you must provide access to `gitlab.com` as opposed to a specific repository. This connects your Gitlab account to your personal OSF account, which you then grant the OSF repository access to. After saving, you select which repository the OSF page can access. The scope of users allowed to change what repository OSF can access has yet to be tested.

Good Resources

• On Git workflow
• On Git commits
• On (semantic) versioning