Skip to content

Git, GitLab, and SSH Setup Documentation

Overview

This document covers the process of setting up Git, connecting to GitLab using SSH authentication, and successfully pushing a local Fab Academy repository to GitLab.

Initial Setup: Adding .DS_Store to .gitignore

What We Did

Added .DS_Store files to .gitignore to prevent macOS system files from being tracked by Git.

Commands Used

echo ".DS_Store" >> .gitignore
echo "**/.DS_Store" >> .gitignore

Why

  • .DS_Store files are macOS system files that store folder display settings
  • They're created automatically by macOS in every folder
  • They shouldn't be tracked in version control as they're system-specific and not part of the project

First Push Attempt: Upstream Branch Issue

What Happened

When trying to push with git push, we got an error: 

fatal: The current branch main has no upstream branch.

What We Did

Used the command to set the upstream branch: 

git push -u origin main
or equivalently: 
git push --set-upstream origin main

Why

  • -u is shorthand for --set-upstream
  • This creates a tracking relationship between your local main branch and the remote origin/main branch
  • After setting this once, future pushes only need git push
  • The upstream connection tells Git where to push and pull from by default

Authentication: Switching from HTTPS to SSH

Initial Problem

Authentication failed with HTTPS, requiring a Personal Access Token.

What We Did

  1. Verified existing remote: 

    git remote -v
    Output showed HTTPS URL: 
    origin  https://gitlab.fabcloud.org/dorian-fritze/fab-academy-2026.git

  2. Found existing SSH key: 

    ls -la ~/.ssh
    Discovered id_ed25519 already existed (when prompted to overwrite, we chose no)

  3. Retrieved public key: 

    cat ~/.ssh/id_ed25519.pub

  4. Added SSH key to GitLab:

  5. Navigated to: Profile → Preferences → SSH Keys

  6. Added the public key from step 3

  7. Changed remote URL to SSH: 

    git remote set-url origin git@gitlab.fabcloud.org:dorian-fritze/fab-academy-2026.git

Why SSH Instead of HTTPS

  • More secure: Uses cryptographic key pairs instead of passwords/tokens
  • More convenient: No need to enter credentials for each push/pull
  • Better for Fab Academy: Standard practice for frequent Git operations
  • No token management: Don't need to create, store, or refresh access tokens

SSH vs Personal Access Token

  • SSH Key: Cryptographic authentication using public/private key pairs
  • URL format: git@gitlab.fabcloud.org:username/repo.git

  • Setup once, use forever (until revoked)

  • Personal Access Token: Password-like string for HTTPS

  • URL format: https://gitlab.fabcloud.org/username/repo.git
  • Must be entered or stored in credential manager
  • Can expire or need rotation

Merging Remote and Local Repositories

What Happened

When pushing, we got an error: 

! [rejected]        main -> main (fetch first)
error: failed to push some refs
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

What We Did

  1. Pulled remote changes with merge strategy: 

    git pull origin main --allow-unrelated-histories --no-rebase

  2. Completed the merge message in vim:

  3. Pressed Esc
  4. Typed :wq

  5. Pressed Enter

  6. Pushed merged changes: 

    git push

Why This Happened

  • GitLab repository had files that weren't in the local repository
  • Local repository had files that weren't on GitLab
  • Git saw these as two unrelated histories

Why These Flags

  • --allow-unrelated-histories: Allows Git to merge two repositories that don't share a common commit history
  • --no-rebase: Uses merge strategy instead of rebase (creates a merge commit)

Vim Editor Navigation

  • Esc: Enter command mode
  • :wq: Write (save) and quit
  • :q!: Quit without saving (if needed)

Cleaning Up Deleted Files

What Happened

Google Docs HTML files and associated assets needed to be removed from Git tracking.

What We Did

  1. Removed individual file: 

    git rm "public/assignments/week01/10-Git commands-&-how-to-make-shortcuts - Google Docs.html"

  2. Removed entire folder recursively: 

    git rm -r "public/assignments/week01/10-Git commands-&-how-to-make-shortcuts - Google Docs_files"

  3. Committed deletions: 

    git commit -m "Remove Google Docs files"

  4. Pushed changes: 

    git push

Why Quotes and -r Flag

  • Quotes: Necessary when filenames contain spaces or special characters like &
  • -r flag: "Recursive" - removes entire directory and all contents

Key Git Commands Summary

Command Purpose
git status Check current state of repository
git add <file> Stage files for commit
git commit -m "message" Commit staged changes with message
git push Push commits to remote repository
git pull Fetch and merge remote changes
git remote -v View remote repository URLs
git remote set-url Change remote repository URL
git rm <file> Remove file from Git tracking
git rm -r <folder> Remove folder recursively

Common Issues and Solutions

Spaces in Filenames

Problem: Commands fail with spaces in filenames
Solution: Use quotes around the entire path 

git rm "path/to/file with spaces.html"

Stuck in Command Prompt

Problem: Terminal not responding after a command
Solution: Press Ctrl + C to cancel the current operation

Vim Editor Confusion

Problem: Stuck in vim merge message editor
Solution: 1. Press Esc 2. Type :wq 3. Press Enter

Authentication Failures

Problem: Can't push/pull from GitLab
Solution: Use SSH authentication instead of HTTPS (covered in detail above)

Final Repository Structure

After all operations, the repository successfully synced: - Local changes pushed to GitLab - Remote GitLab files merged locally - Unnecessary files removed - SSH authentication configured for future operations

Best Practices Learned

  1. Always use .gitignore for system files like .DS_Store
  2. SSH is better than HTTPS for regular Git work
  3. Use quotes around filenames with spaces or special characters
  4. Set upstream branch on first push with -u flag
  5. Pull before pushing when remote has changes
  6. Commit regularly with descriptive messages

Resources

  • GitLab SSH Keys: https://gitlab.fabcloud.org/-/user_settings/ssh_keys
  • Fab Academy GitLab: https://gitlab.fabcloud.org
  • Git Documentation: https://git-scm.com/doc

Documentation created: February 4, 2026 For: Fab Academy 2026 - Dorian Fritze