Git Workflow Reference

Introduction

Git is a distributed version control system that allows multiple developers to work on a project simultaneously without interfering with each other's changes. It tracks changes in source code during software development, enabling collaboration and maintaining a history of changes. Git is widely used in open-source and commercial projects, and it integrates well with platforms like GitHub, GitLab, and Bitbucket.

In this guide, we will cover the basic commands, branching strategies, commit best practices, pull requests, resolving merge conflicts, and advanced Git operations. Git is a powerful tool, and understanding its workflow is essential for effective collaboration in software development.

For more information on Git, visit the official documentation at git-scm.com

Basic Git Commands

These are the fundamental commands you'll use in everyday Git operations.

Command Description
git initInitialize a new Git repository in the current directory.
git clone [url]Download a project and its entire version history.
git statusShow the working tree status (changes, untracked files).
git add [file]Add file changes to the staging area. Use . for all changes.
git commit -m "[message]"Record staged changes to the repository with a descriptive message.
git logShow commit history. Add --oneline for brevity.
git diffShow changes between commits, commit and working tree, etc.
git pullFetch changes from the remote repository and merge them into the current branch. (git fetch + git merge)
git pushUpload local repository content to a remote repository.
git remote -vList configured remote repositories.

Branching Strategies

Branching allows parallel development without affecting the main codebase.

Common Branching Commands

  • git branch: List all local branches. Add -a for all remote branches.
  • git branch [branch-name]: Create a new branch.
  • git checkout [branch-name]: Switch to the specified branch.
  • git checkout -b [branch-name]: Create a new branch and switch to it immediately.
  • git merge [branch-name]: Merge the specified branch's history into the current branch.
  • git branch -d [branch-name]: Delete a local branch (only if merged). Use -D to force delete.
  • git push origin --delete [branch-name]: Delete a remote branch.

Simple Feature Branch Workflow (Flowchart)

Start on main branch
git pull origin main (Update local main)
git checkout -b feature/new-thing (Create feature branch)
Work on feature (Edit, git add, git commit)
git push origin feature/new-thing (Push feature branch)
Create Pull Request (GitHub/GitLab etc.)
Review & Merge PR
Switch back to main: git checkout main
Update local main: git pull origin main
Delete local feature branch: git branch -d feature/new-thing

Other Strategies

  • Gitflow: More structured, uses feature, develop, release, hotfix, and main branches. Suitable for projects with scheduled releases.
  • GitHub Flow: Simpler, main is always deployable, features are developed in branches and merged via PRs. Good for CI/CD.
  • GitLab Flow: Similar to GitHub Flow but can include environment branches (e.g., production, staging).

Commit Best Practices

Writing good commit messages is crucial for understanding project history.

feat: Add user authentication endpoint

Implement the /api/auth/login route using JWT for session management.
This endpoint accepts username and password, validates credentials
against the database, and returns a JWT token upon success.

Addresses issue #45.

Pull Requests (PRs) / Merge Requests (MRs)

PRs are used to propose changes, discuss them, and integrate them into the main codebase.

  1. Create a Feature Branch: As described in the Branching section.
  2. Push the Branch: git push origin [branch-name].
  3. Open a PR: Use the GitHub/GitLab/Bitbucket interface to create a PR from your feature branch to the target branch (e.g., main or develop).
  4. Describe Your Changes: Write a clear title and description explaining the purpose and scope of the changes. Reference related issues.
  5. Review Process: Team members review the code, provide feedback, and request changes if necessary.
  6. Address Feedback: Make necessary changes on your feature branch and push them. The PR updates automatically.
  7. Merge: Once approved, the PR is merged into the target branch.
  8. Clean Up: Delete the feature branch locally (git branch -d [branch-name]) and remotely (usually an option when merging).

Resolving Merge Conflicts

Conflicts occur when Git cannot automatically merge changes from different branches.

  1. Identify Conflicts: Git will notify you during a git merge or git pull if conflicts exist. git status will show conflicted files.
  2. Open Conflicted Files: Files with conflicts will contain markers: 
    <<<<<<< HEAD
Your changes (current branch)
=======
Incoming changes (branch being merged)
>>>>>>> [other-branch-name]
  3. Edit Files: Manually edit the files to resolve the differences. Remove the conflict markers (<<<<<<<, =======, >>>>>>>) and keep the desired code.
  4. Stage Resolved Files: Use git add [resolved-file-name] for each file you fixed.
  5. Complete the Merge: Once all conflicts are resolved and staged, run git commit. Git usually provides a default commit message; you can keep it or modify it. If you were rebasing, use git rebase --continue instead.

Advanced Git Operations

More sophisticated Git commands for experienced users.

CommandDescription
git rebase -i [commit-ref]Interactive rebase: allows squashing, editing, reordering commits before a reference.
git cherry-pick [commit-hash]Apply the changes introduced by a specific commit onto the current branch.
git stashTemporarily store modified, tracked files to switch branches or pull updates.
git stash popRe-apply the most recently stashed changes and remove them from the stash list.
git stash listShow all stashed changesets.
git reset [commit-ref]Unstage files or reset the current branch head to a specified commit. Use with caution (--soft, --mixed, --hard options).
git revert [commit-hash]Create a new commit that undoes the changes made in a previous commit. Safer than reset for shared history.
git tag [tag-name]Create a lightweight tag pointing to the current commit (often used for releases, e.g., v1.0.0).
git log --graph --oneline --decorateDisplay commit history as a text-based graph.

Reset Options Explained

  • git reset --soft [commit]: Moves HEAD to the specified commit, but keeps changes in staging area. Useful when you want to recommit with different changes grouped together.
  • git reset --mixed [commit]: (Default) Moves HEAD and updates staging area. Changes are preserved in working directory but unstaged.
  • git reset --hard [commit]: Moves HEAD, updates staging area, and overwrites working directory. All changes are lost - use with extreme caution!

Git Reflog - Your Safety Net

The reflog records all changes to branch tips and other references, creating a log of your local repository's history:

  • git reflog: Shows a log of all references (HEAD@{0}, HEAD@{1}, etc.)
  • Useful for recovering lost commits after a hard reset or branch deletion
  • Example recovery: git checkout -b recovery-branch HEAD@{2}

Advanced Workflow Examples

Squashing Multiple Commits into One

git rebase -i HEAD~3  # Interactive rebase for last 3 commits
# In the editor, change "pick" to "squash" or "s" for commits to combine
# Save and edit the resulting commit message

Removing a Sensitive File from History

git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch PATH-TO-SENSITIVE-FILE' \
--prune-empty --tag-name-filter cat -- --all
git push origin --force --all  # Force push to overwrite history (use with caution!)

Creating and Pushing a Tag for Releases

git tag -a v1.0.0 -m "Version 1.0.0 release"  # Create annotated tag
git push origin v1.0.0                      # Push specific tag
git push origin --tags                      # Push all tags

Git Hooks

Git hooks are scripts that run automatically at certain points in the Git workflow (e.g., before committing, after merging).

Back to Top