Git Cheat-Sheet: Operational Guide and Versioning Best Practices

Git Cheat-Sheet: Operational Guide

Git is the de facto standard for distributed version control, though its extensive command set can be challenging during complex merges or incident resolution.

This guide provides practical commands, recovery procedures, and standard workflows used in day-to-day repository management.

1. Branch Management and Daily Workflow

Our workflow is structured around two primary branches: dev (development, integration, and testing) and main (stable production branch).

Basic Commands to Move Around:

# Show all local branches and indicate which one we are on
git branch

# Create a new branch starting from the current one and switch to it
git checkout -b name-of-new-branch

# Switch to an existing branch (e.g., return to dev)
git checkout dev

Manual Alignment from dev to main (without the merge.sh script):

If we want to merge branches manually, the correct sequence is as follows:

# 1. Save everything on our development branch
git checkout dev
git add .
git commit -m "Description of changes"
git push origin dev

# 2. Switch to main and pull latest from the server
git checkout main
git pull origin main

# 3. Merge dev into main
git merge dev

# 4. Push to production
git push origin main

# 5. Return to dev and realign with the latest changes from main
git checkout dev
git merge main

2. Managing Pull Requests (PR) Locally

If an external contributor opens a Pull Request (PR) to our repository, we should never merge blindly. It is better to download it locally to a temporary branch to test it with zola serve and understand what has been modified.

Forgejo (and Gitea/GitHub) maps PRs with a special reference: pull/[PR_ID]/head.

# 1. Download the PR locally, creating a temporary branch (e.g., pr-12 for PR #12)
git fetch origin pull/12/head:pr-12

# 2. Switch to the newly created temporary branch
git checkout pr-12

# 3. Test the site locally (the changes are active here!)
zola serve

Post-Test Cleanup:

Once the PR has been verified:

# Return to our development branch
git checkout dev

# Delete the temporary PR branch that is no longer needed
git branch -D pr-12

At this point, we can merge by clicking the green button on Forgejo's web interface. Remember to run git pull origin dev to download the approved changes to our local copy.

3. Resolving Merge Conflicts

A conflict is created when we and another user (or a PR) have modified the exact same lines of the same file. Git does not know which version to keep and stops, asking for our intervention.

How to Proceed:

If during a merge (such as git merge dev or git merge pr-12) we receive a CONFLICT (content): Merge conflict in content/article.md error:

1. Open the offending file with our text editor.
2. Look for the conflict markers inserted by Git:

   <<<<<<< HEAD
   This is the code present in the branch we are currently on (the destination).
   =======
   This is the code present in the branch we are trying to merge (the source).
   >>>>>>> dev

3. Resolve the conflict manually: delete the markers (<<<<<<<, =======, >>>>>>>) and edit the text leaving only the correct version (or merging them sensibly).
4. Register the resolution:

   # Add the resolved file to the stage area
   git add content/article.md
   
   # Conclude the merge with a commit
   git commit -m "Resolved merge conflict"

4. Git First Aid (When things go south)

Here are the classic panic situations you find yourself in at least once.

"We made a mistake in the last commit message" (Not yet pushed)

If we made a commit but realized we made a typo in the message text:

git commit --amend -m "Correct and clean message"

"We forgot to add a file to the last commit" (Not yet pushed)

If we made the commit but realized a file or a quick fix was missing:

git add forgotten-file.md
git commit --amend --no-edit

This command inserts the change directly into the last commit, without changing the message.

"We want to undo the last commit but KEEP the changes"

If we made a commit but want to "deconstruct" it to modify the files or make separate commits:

git reset --soft HEAD~1

The commit disappears, but our files remain modified in the stage area.

"We want to undo the last commit and DISCARD all changes" (Point of no return!)

If we want to delete the last commit and restore files to how they were before:

git reset --hard HEAD~1

Warning: this command permanently deletes uncommitted changes.

"We want to discard all unsaved local changes"

If we modified files, they suck, and we want to go back to the last clean commit:

# Restore modified tracked files
git restore .

# Remove any new untracked files or directories
git clean -fd

5. The Time Machine: git reflog

If we executed a git reset --hard in the wrong place, or deleted a branch believing it was no longer needed, we might think we have lost everything. Fortunately, Git doesn't delete anything immediately.

The reflog is Git's internal log that tracks every single movement of the HEAD.

1. View the history of our steps:

   git reflog

   You will see a list similar to this:

   ab12cd3 HEAD@{0}: reset: moving to HEAD~1
   ef45gh6 HEAD@{1}: commit: Added article on cryptography
   ij78kl9 HEAD@{2}: checkout: moving from dev to main

2. Find the point where everything was working: for example HEAD@{1} (before the wrong reset).
3. Go back in time:

   git reset --hard HEAD@{1}

   The files will return to the exact state they were in at that moment.

Discussion & Support

Discussion and support channel. To discuss configurations or other topics, join us on fluxer.dreadful.work.