Understand the Core Concepts

“Clean code always looks like it was written by someone who cares.” - Michael Feathers

Introduction

Through hands-on experience collaborating on open-source projects and team development, I've developed a practical Git workflow that enhances code quality and team efficiency. This guide shares lessons learned and specific practices for maintaining clean, manageable codebases.

Note that this is not for any specific project but to build on open-source projects. Also, this article only covers the essentials of git.

What is Git?

Git is a distributed version control system that tracks changes in your code over time

Collaboration in Git

  1. Fork repo on GitHub or create a repository for people to work on
  2. Create a codespace
  3. Invite collaborators
  4. Create a branch as the owner
  5. Decide on an issue in the repository or collaborate on a team member’s project
  6. Use the code above as often as possible to avoid merging conflicts

When you finished making changes on your end:

git add .         # Stage changes
git commit -m "message"
git diff         # view unstaged changes

git log        # view branch logs

The collaborators must use this in git:

git pull origin <branch-name>
  • Note: before pushing the commit, make sure the message is clear, here is a short guide on how to make a commit I learned
  • If you already committed a message, here is how to change it:
git commit --amend -m "New message"

Commit naming convention

There are essentially 5 parts to a commit to easily communicate its intent to consumers of the library

<type>[optional scope]: <description> [optional body] [optional footer(s)]

<type>

  • feat - new feature
  • bug - bug fix
  • docs - documentation changes
  • style - styling that does not affect the code at all
  • refactor - no bug fix or new feature
  • perf - performance improvements
  • test - execute tests for code
  • build - build system or external dependency changes
  • ci - CI configuration files and script changes
  • chore - do not modify src or test files

[optional scope]

  • Can be anything specifying the place of the commit change
  • Ex: feat(parser):, fix(database):, docs(readme):

<description>

  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • the first letter not capitalized
  • no “.” at the end and limit to 50 characters

[optional body]

  • Include motivation for the change and contrasts with previous behavior

[optional footer(s)]

  • Breaking changes should start with BREAKING CHANGE:
  • Close issues with Closes #123, #456
  • Describe large changes or issues attempted

Ex: feat(auth): implement JWT authentication

Here are even more git commands that will make your workflow faster that I have used or have seen used:

git branch                  # List all branches
git branch <branch-name>    # Create new branch
git checkout <branch-name>  # Switch to branch
git merge <branch-name>     # Merge branches
git stash                   # Temporarily store changes
git stash pop              # Restore stashed changes
git reset --hard HEAD~1     # Undo last commit
git remote -v              # View remote repositories
git restore <file>         # Discard changes in file
git reset --soft HEAD~1    # Undo commit, keep changes staged
git reset --mixed HEAD~1   # Undo commit, unstage changes
git revert <commit>        # Create new commit that undoes changes
git tag <tagname>          # Create lightweight tag
git tag -a <tag> -m "msg"  # Create annotated tag
git push origin <tag>      # Push tag to remote
git tag -d <tagname>       # Delete local tag
git cherry-pick <commit>   # Apply commit to current branch
git rebase <branch>        # Rebase current branch
git bisect start          # Binary search for bugs
git clean -n              # Show what will be cleaned
git clean -f              # Remove untracked files
git pull origin <branch-name>            # Pulls changes from branch
git push origin <branch-name>            # Pushes changes to branch

Best Practices

  • Commit often
    • Even with the smallest changes, like adding text/button
  • Branch Management
    • Make sure to delete branches when you are done with them to avoid clutter
  • Code review
    • Review before merging with a teammate/friend before committing
    • Provide constructive feedback
    • Make sure anyone can read it
  • Documentation
    • READ.ME
    • Contributing.md
    • Installation/Setup steps

Conclusion

Git is more than just a version control system - it's a collaborative tool that enables teams to work efficiently and maintain code quality. By following these practices and understanding Git's capabilities, teams can:

  • Minimize conflicts and confusion
  • Allow you to even mark versions when you're working individually
  • Maintain history
  • Scale development
  • Recover mistakes
  • Build large software together

Remember that these practices should be adapted to your team's needs and project requirements. The key is consistency and clear communication within the team.

What I like to use to communicate

  • discord
  • slack
  • GitHub
  • but any messaging function works!

Happy coding/writing

Author Of article : Johnny Santamaria Read full article