GitHub Best Practices - lukasvarhol/crypto-fpga-trader GitHub Wiki

Git Reference Guide

Basic Commands

Initial Setup

Set the default branch to main (CLion uses master by default):

git config --global init.defaultBranch main

Tracking and Committing Files

Track a specific file:

git add <filename>

Track all files in current directory:

git add ./

Commit tracked files:

git commit -m "your commit message"

View commit history:

git log

Understanding HEAD

The HEAD is a pointer that references the latest commit. When you checkout a specific commit:

git checkout <commit-hash>

This creates a "detached HEAD" state where HEAD points to an older commit instead of the most recent one.

To return to the latest commit:

git checkout main

To forcefully discard changes made in detached HEAD state:

git checkout -f main  # -f flag forces the checkout

Working with Remotes

Adding Remotes

Add a remote repository:

git remote add origin <repository-url>

For multiple remotes, use different names:

git remote add gitlab <gitlab-url>
git remote add github <github-url>

Pushing to Remote

Push committed files to remote repository:

git push -u origin main  # -u sets upstream tracking

Branching

Creating and Switching Branches

Create a new branch:

git branch <branch-name>

Switch to an existing branch:

git checkout <branch-name>

Create and switch to a new branch in one command:

git checkout -b <branch-name>

Publishing Branches

Push a branch to remote repository:

git push --set-upstream origin <branch-name>
# OR
git push -u origin <branch-name>

Commit Message Best Practices

Writing Style

Write commit messages in imperative tense. Think: "If applied, this commit will..."

  • ✅ "Fix login bug"
  • ✅ "Implement user authentication"
  • ❌ "Fixed login bug"
  • ❌ "Implementing user authentication"

Conventional Commit Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

  • feat: New feature or functionality
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code formatting (no logic changes)
  • refactor: Code restructuring (no behavior change)
  • test: Adding or updating tests
  • chore: Maintenance tasks (dependencies, build, etc.)
  • perf: Performance improvements
  • ci: CI/CD pipeline changes

Example Commit Messages

git commit -m "feat(setup): Add CMakeLists.txt with C++20 and M1 optimizations"
git commit -m "docs(wiki): Create initial project documentation structure"
git commit -m "chore(deps): Add Google Test integration via FetchContent"
git commit -m "feat(structure): Add src, include, tests directory structure"

Resolving Merge Conflicts

Steps to Resolve

  1. Checkout to the main branch
  2. Pull the latest changes from remote
  3. Edit the conflicted file

Conflict Markers

When you encounter conflicts, you'll see markers like this:

<<<<<<< HEAD
## Welcome to Git!
=======
## Hi, welcome to git
>>>>>>> main

Edit the file to resolve conflicts, then commit the resolution.

Advanced Git Commands

Git Reset

Revert to a previous commit with different behaviors:

Soft Reset - Move commits to staging area:

git reset --soft <commit-hash>

Mixed Reset (default) - Unstage commits, keep changes in working directory:

git reset <commit-hash>

Hard Reset - Remove commits and delete all changes:

git reset --hard <commit-hash>

Git Revert

Create a new commit that undoes changes from a previous commit (preserves history):

git revert <commit-hash>

If conflicts arise, resolve them and continue:

git revert --continue

Tip: To exit vim editor, type :qa!

Git Stash

Save uncommitted changes temporarily without committing:

git stash

View all stashes:

git stash list

Apply a specific stash:

git stash apply <stash-name>  # e.g., stash@{0}

Use Case: You're working on a feature but need to quickly switch to fix an urgent bug. Stash your current work, fix the bug, then return to your feature by applying the stash.

⚠️ **GitHub.com Fallback** ⚠️