Skip to main content

Git Guide

Overview​

At publica.la, we use Git as our distributed version control system. Git enables our team to collaborate, manage different branches, and handle complex workflows such as rebasing and resolving conflicts. This guide contains essential Git commands and practices tailored for our workflow.

General Workflow Tips​

  1. Avoid merge conflicts when possible: Prefer resolving conflicts in a rebase operation rather than merging. This ensures a cleaner and more linear project history. When you rebase, Git applies your changes on top of the latest commit from the base branch, minimizing merge conflicts down the line.

  2. Rebasing workflow: When working on branches that require updating from the base branch, follow this process:

    • Rebase: Before merging, rebase your branch on top of the latest base branch (e.g., master or dev). 
      git rebase <base-branch>
    • Push after rebasing: Use the --force-with-lease option when pushing to the remote branch after a rebase to prevent overwriting others' work. 
      git push --force-with-lease

How rebase works: This is what Git actually does during a rebase:

  1. Pause your changes: Git temporarily sets your changes aside.
  2. Update to the latest version: Git updates your branch to match the latest version of the branch you're working from (like master or dev).
  3. Reapply your changes: Git then applies your changes on top of this new version. This means Git commits them again, as if you were manually redoing your changes on the updated code. This is where conflicts can arise, and you can solve them commit by commit.

Essential Git Commands​

Resetting a Local Branch to the Remote​

If you want to reset your local branch to match the remote branch exactly, discarding any local changes (commits, WIP, etc.), use the following command:

git reset --hard origin/<branch>

This is useful when a rebase or other local changes have caused issues, and you want to start fresh from the remote branch state.

Careful, this will permanently delete all local changes in the branch.

Abort a Rebase​

If you are in the middle of a rebase and encounter problems, you can abort it and return to the state before the rebase started:

git rebase --abort

This command is useful when you've hit conflicts or mistakes during a rebase, and you'd like to start over.

This won't cause you to lose any changes; Git will return you to the state before you started the rebase.

Additional Tips​

Handling Merge Conflicts​

While rebasing helps minimize conflicts, they still happen. When you encounter a conflict during a rebase, Git will pause and give you the chance to resolve it. After resolving conflicts in the files, use the following commands to continue the rebase:

git add <file>
git rebase --continue

Alternatively, if you decide to cancel the rebase, use the abort command:

git rebase --abort

Force Push Warnings​

Remember that using --force without --force-with-lease can overwrite remote history, leading to data loss for other team members. Always double-check if you need to force push, and prefer --force-with-lease to protect the work of others. This ensures that no one else has updated the branch you're about to force push to.

Soft Reset to Undo the Last Commit​

If you need to undo your last commit but keep the changes in your working directory (staged for commit), you can use the following command:

git reset --soft HEAD~1

Summary​

  • Reset to remote: git reset --hard origin/<branch>
  • Soft reset to undo the last commit: git reset --soft HEAD~1
  • Abort a rebase: git rebase --abort
  • Rebase onto a new base: git rebase --onto <new-base> <old-base> <current-branch>
  • Force push after a rebase: git push --force-with-lease
  • Avoid merges: Prefer git rebase <branch> over merge to maintain clean history

For more detailed information on advanced Git workflows, including the nuances of rebasing, see Atlassian's Git Rebase Documentation.

X

Graph View