Aalto Version: Quick guide

Centrally managed version control system is available for all Aalto users at https://version.aalto.fi

• Info & Login to the system
• Creating a new project
• Configuring the client for use
• Login with SSH
• Size limit of a repository
• More information regarding the usage of GIT

Info & Login to the system

Aalto users are able to login to the system with Haka authentication (Picture 1, red circle). External users with HAKA account can also use the same method to access the system. External users with locally configured credentials will have to type their credentials to the dedicated fields within the Standard tab (Picture 1, blue circle).

Creating a new project

After a successful login, new user will see a welcome page, where a new project can be created or an existing project can be browsed.

External users cannot create new projects.

1. Click the New project button.
2. In the new project window (Picture 3) enter the name of the project, description and the privacy-settings (visibility level). You can also import repositories from external systems, such as Github.
3. Click Create Project. The new project is done.

Configuring the client for use

In order to obtain a local copy of a repository, you will need to install a Git-client on your computer.

For centrally managed Aalto computers, the Software Self-service portal has one available, SW_Git_Aalto.

To login with Git-client (https) to a repository, use Aalto-credentials:

• Username: username@aalto.fi
• Password: Aalto password

Local copy of the repository

There are two copies of the repository: local copy on the computer and remote copy on the version control system. Use local computer drive or Aalto network drive (home / work / teamwork) to store the local copy of the repository. Don't use folder synchronized with OneDrive, as there are known issues with git that may corrupt your repository. You might not need backups from the local folder, as there is a remote copy of the repository on the version control system.

Git global setup:

Configuring your username, the information can be found inside the site of a repository (https://version.aalto.fi/your_username/repository_name).

git config --global user.name "your.username"

git config --global user.email "Aalto email-address"

Create a new repository:

git clone https://version.aalto.fi/your_username/Testproject.git

cd Testproject

touch README.md

git add README.md

git commit -m "add README"

git push -u origin master

Existing folder or Git repository:

cd existing_folder

git init

git remote add origin https://version.aalto.fi/your_username/Testproject.git

git add .

git commit -m "Initial commit"

git push -u origin master

Login with SSH

You can use SSH to login to Aalto Version Control System. Use your normal Aalto password or create a SSH key as instructed here: https://version.aalto.fi/gitlab/help/user/ssh.md

NOTE: The server authentication keys have changed on 20 Dec 2021. You will need to remove old entry from ssh configuration file (.ssh/known_hosts), for example with one of these methods:

• Use the command:
  ssh-keygen -f "~/.ssh/known_hosts" -R "version.aalto.fi"
  You might need to change the path of the known_hosts file for the -f parameter.
• Or use a text editor to open known_hosts file and remove the line for version.aalto.fi

To verify the authentication to the server version.aalto.fi, the SSH host key fingerprints are:

Proper use of large files with Git

This service is not a storage for large files. Maximum file size allowed for single push operation is 100 MB. If you have to store large files in your repository, use Git LFS tool for best performance. This tool does not add binary files to the commit history, but uses a pointer instead, saving resources and disk space resulting in efficient user experience for everyone.

# Install Git LFS (once per machine)
git lfs install

# Track typical large binaries (examples)
git lfs track "*.zip" "*.mp4" "*.pdf" "*.h5" "*.pt" "*.onnx" "*.pickle"

# Commit the updated .gitattributes
git add .gitattributes
git commit -m "Track large files with Git LFS"
git push
 

How to remove large files from commit history

If you have stored large files in your commit history, please remove them. Here are three options for you to choose from:

• Git LFS migrate -command. This tool removes large files from commit history and converts them to Git LFS objects. Good option if you have to keep large files together with your code in the service.

# Make a backup or work on a fresh clone
# Migrate selected patterns to LFS (adjust patterns to your needs)
git lfs migrate import --include="*.zip,*.mp4,*.h5,*.pt,*.onnx,*.pdf"

# Force-push updated history (coordinate with collaborators)
git push --force --all
git push --force --tags

• Purge large files from commit history with git-filter-repo tool. This tool removes large files from commit history and reduces the repository size. Recommended option if you can handle large files in the storage services best suited for them, e.g. shared network drives or in Teams.
• Remove file blobs from the service. This method removes the file blobs from the server. To use it, you will have to get blob IDs. You can use command git ls-tree as explained in the link, or command "git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize:disk) %(objectname) %(rest)' | sort -k2n |tail -20". Large files still remain in local repository. If you need to include them, take a fresh clone from the server to another folder, copy the large files you need there, and configure Git LFS before commiting them back to server.

Clean restart with a fresh repository

Easiest way to get a small repository is to start over with a new project. Major downside is that you will lose the previous commit history and may not revert back to any earlier versions. Create a new project, make a new local folder, copy the code files to keep there, and connect to remote project as instructed above under heading "Existing folder or Git repository".

Using Gitlab API

We support GraphQL and REST API endpoints with Gitlab Free tier functionalities. Note: the endpoint address includes /gitlab and is https://version.aalto.fi/gitlab/api/v4/ for REST API and https://version.aalto.fi/gitlab/api/graphql for GraphQL API. For more information, see Gitlab reference for:

REST APIGraphQL API

More information regarding the usage of GIT

For more information, how to use GIT as a version control system, feel free to familiarize yourself with the Pro Git – book composed by Scott Chacon & Ben Straub, link to the book below:

https://git-scm.com/book/en/v2

GitLab also provides comprehensive user guides; feel free to familiarize yourself with them at
https://version.aalto.fi/gitlab/help