Skip to content

Commiting to Git

Jump to bottom
Chloe edited this page May 9, 2024 · 16 revisions

Branching Model & Workflow details

+---------+       +-------------------+
|  Main   |<------+   Hotfix Branch   |
+----^----+       +--------^----------+
     |                     |
     |                     |
     |               +-----+------+
     +-------------> |   Feature  |
                     |   Branch   |
                     +------------+
  • Main Branch: As the name says, the main branch, which is to be stable, tested version → main/
  • Feature Branch: Derived from the main branch. For ongoing development, connected sets of changes, merged back into main once reviewed. These branches should preferably be short lived to minimise divergence from the main branch. → feature/
  • Hotfix Branch: Used for critical bug fixes on main. After the fix, they should be merged back into both the main and feature branches to ensure that the fix is added into the ongoing development process. → hotfix/

Branch Management

Creating Branches

  • Always create a new branch for each new feature or bug fix, so the code stays organized and isolated from the main codebase.

Life Cycle of Branches

  • Feature Branches: Merge feature branches back into the main branch once the feature is complete, tested, and reviewed.
    • Ideally we want to avoid long lived branches, which can accumulate a significant number of changes, making merging difficult to do.
  • Hotfix Branches: These branches should be merged back as soon as the fix is complete and verified.

Deleting Branches

  • After a branch has been successfully merged into main, it should be deleted to keep the repository clean and manageable.

Regular Maintenance

  • Every now and then to go back and check on the unused braches and review them to see if they should be deleted as this can make the repository a lot cleaner.

Version Control Best Practices

  • Consistent Pulls: Regularly pull from the main branch to keep your feature branches up-to-date.
  • Protect Main Branch: We do not allow direct pushes to the main branch, insteas we use pull requests to merge changes, making sure that they are reviewed and tested before integration.
  • Atomic Commits: Make sure each commit is self-contained and can be understood on their own.
  • Branch Deletion: As mentioned above, regularly delete old branches that have been merged or abandoned to keep your repository organized.

Making Good Commits

  • Try to make smaller, but more frequent commits throughout the day, as it's easier to fix and review
  • Add a descriptive message of what kind of changes were made, and why they were neccessary

- Use prefixes in commit messages:

  • When ADDING a new function

    ADD: < what has been added >

  • When FIXING an error

    FIX: Bug < [what bug] > [description]

  • When REMOVING code, files

    DEL: < what has been removed >

  • When UPDATING something

    UPD: < what has been updated >

  • Committing not fully-functional additions is possible if all tests pass and nothing breaks because of it.
  • Every commit should be logically connected to one another, if it contains the word and, split it into multiple commits
  • Use the git add -p command to prepare and verify the contents of the commit before finalizing it and git diff --cached to review
  • Avoid force push unless really neccessary

Good vs. Bad Commit Examples

  • Some tips about writing helpful commit messages:
    • Separate the title from the body with a blank line
    • Subject line <= 50 characters + imperative mood
    • Use the body to explain what and why vs. how.
    • Body <= 72 characters + why and how

Good Commit Example:

Why it’s good:

  • Clear Prefix: Uses a prefix "UPD" to indicate that it's an update, which is part of the standard convention.
  • Descriptive: Clearly describes what was done (updating a YAML file) and why (to include an update option).
  • Scope Limited: Focuses on a single change which makes it easier to understand the purpose and impact of the commit.

Bad Commit Example:

Why they’re bad:

  • Non-descriptive Messages: The commit messages are vague, do not convey the purpose of the changes.
  • Inconsistent Naming: They do not follow a clear or agreed-upon naming convention which makes them harder to track in the version history. (granted this did not exist back then, but it is the best example I have now, sorry Julius)
  • Should Have Been Squashed: We have opted to squash merge to maintain a clean history, however this was merged as singular commits, making it more difficult to maintain a clean history.

Handling Merge Conflicts

  • Merge conflicts can arise when multiple branches have edited the same part of the same file. Here's how to resolve them:
    • Use git mergetool: This will opens a GUI that you can use to resolve conflicts manually. Configure your preferred tool in your Git configuration with git config --global merge.tool <toolname>.
    • Manual Resolution: Open the conflict and look for the lines marked with conflict markers (<<<<<<<, =======, >>>>>>>). Edit the file to fix the conflicts, then click git add the file to mark it as resolved.
    • Command Line: Alternatively, you can solve the conflict through the command line

Rebasing vs. Merging

  • Know when to rebase and when to merge to maintain a clean and efficient project history:
    • Use git rebase for Feature Branches: Before creating a pull request (PR), rebase your feature branch onto the latest commit of the Main branch. This practice helps create a nicer history, which simplifies both navigation and troubleshooting in the project history. Also when updates from Main branch are added into the feature branch you can spare merge conflicts.
    • Use Pull Requests for Integrating Completed Features and Hotfixes: Once the feature or hotfix branch is fully tested and approved, squash merge it back into the Main branch using a pull request.

Interactive Rebasing

  • Cleaning Up Commits: You can use git rebase -i for interactive rebasing, which allows you to modify commits: rewrite, delete, and squash commits before they are merged into main.

Additional Tips:

  • Rebasing Best Practices: Always pull and rebase (git pull --rebase) your feature branches before pushing your changes to remote repositories to minimize conflicts and ensure your branch is up to date with the Main branch. This step should always be completed before opening a new pull request.

Using git stash

  • Managing Changes: If you need to quickly switch between branches but you don't want to commit your current work:
    • Stash Your Changes: git stashs to save your current state. You can always go back to your previous branch without committing half-done work.
    • Apply Stashed Changes: Use git stash pop to apply the saved changes after switching back or to another branch.

Helpful Resources

Clone this wiki locally