GitHub Best Practices

Git rewards a small amount of discipline out of all proportion to the effort. The commands below are the ones you will use every day, followed by the conventions — commit messages, branching, review — that keep a repository readable once more than one person is working in it.

Basic Git Commands

Pull

The git pull command fetches changes from a remote repository and merges them into your current branch. This is often used to update your local branch with changes from a remote repository.

git pull origin main

Push

The git push command uploads your local commits to a remote repository. This is how you send your changes to a repository for others to see and use.

git push origin main

Commit

The git commit command records changes to the repository. Commits are snapshots of your project at specific points in time.

git commit -m "Add feature X"

Commit Message Best Practices:

  • Be Descriptive: Clearly describe what the commit does.
  • Use the Present Tense: Use present tense to describe the changes (e.g., "Add feature" instead of "Added feature").
  • Limit the Subject Line: Keep the subject line under 50 characters.
  • Include a Body if Necessary: If the change is complex, include a detailed body explaining why the change was made and any additional context.

Merge

The git merge command integrates changes from different branches. Merging combines the contents of the specified branch with the current branch.

git merge feature-branch

Merge Best Practices:

  • Resolve Conflicts: Address any conflicts that arise during the merge.
  • Test Before Merging: Ensure the code works correctly before merging it into the main branch.
  • Use Pull Requests: Use pull requests for merging to facilitate code review and discussion.

Squash

The git rebase command with the -i flag allows you to combine multiple commits into one. This is useful for cleaning up commit history.

git rebase -i HEAD~n

Squash Best Practices:

  • Use Squash for Clean History: Squash commits to create a cleaner, more understandable commit history.
  • Rebase Instead of Merge: Use rebase to apply your changes on top of the latest changes from the main branch.

Branches

Branches allow you to work on different features or issues in isolation. The git checkout command with the -b flag creates a new branch and switches to it.

git checkout -b new-branch

Branching Best Practices:

  • Use Descriptive Names: Name branches clearly to indicate their purpose (e.g., feature/add-login, bugfix/fix-login-error).
  • Keep Branches Short-lived: Merge branches back into the main branch as soon as the work is complete to avoid divergence.
  • Regularly Sync with Main: Regularly pull changes from the main branch to keep your branch up-to-date and reduce merge conflicts.

Merge Conflicts

What Are Merge Conflicts?

Merge conflicts occur when Git is unable to automatically reconcile differences between two commits. This typically happens when changes are made to the same line of a file or when one branch deletes a file that another branch modifies.

How to Resolve Merge Conflicts

  1. Identify the conflicts. Git marks them in the file with conflict markers:

    <<<<<<< HEAD
your changes
=======
changes from the branch being merged
>>>>>>> branch-name

  2. Edit the conflicts. Manually edit the marked sections to resolve them. Remove the conflict markers and make sure the code is as it should be.

  3. Stage the resolved files.

    git add <filename>

  4. Complete the merge.

    git commit

  5. Test thoroughly. Ensure that your changes work as expected and that the merge did not introduce any issues.

Best Practices for Avoiding Merge Conflicts

  • Communicate: Coordinate with your team to avoid working on the same parts of the code simultaneously.
  • Frequent Pulls: Regularly pull changes from the main branch to minimize divergence and potential conflicts.
  • Small, Frequent Commits: Make small, incremental changes rather than large, sweeping changes to reduce the chance of conflicts.
  • Use Feature Branches: Isolate work in feature branches and merge back into the main branch frequently.

Best Practices

Peer Review

  • Code Reviews: Conduct thorough reviews to maintain code quality. Look for logic errors, code consistency, and adherence to best practices.
  • Comments: Provide constructive feedback. Focus on the code, not the person, and offer suggestions for improvement.
  • Approval: Ensure that changes are approved by at least one reviewer before merging. This helps catch potential issues early.
  • Review Process: Establish a standard review process to ensure consistency. Use checklists to ensure all aspects of the code are reviewed.

Commit Messages

  • Clarity: Write clear and descriptive commit messages. Avoid vague messages like "fix" or "update."
  • Format: Follow the convention: type(scope): subject. For example, feat(login): add user authentication.
  • Types: Use types like feat (feature), fix (bug fix), docs (documentation), style (formatting), refactor (code changes), test (adding or modifying tests), and chore (maintenance).

Branching Strategy

  • Feature Branches: Create a new branch for each feature or bugfix. This isolates work and makes it easier to manage and review.
  • Merge Requests: Use pull requests for merging. This facilitates discussion, review, and documentation of changes.
  • Trunk-Based Development: Keep the main branch stable and release-ready at all times. Regularly merge changes from feature branches into the main branch.

Continuous Integration

  • Automate Testing: Ensure that all tests pass before merging. Use CI tools to automate the testing process and catch issues early.
  • Linting: Use linters to maintain code consistency. Linting tools can catch syntax errors and enforce coding standards.
  • Build Automation: Automate the build process to ensure that the code can be compiled and deployed successfully.

Collaboration

  • Regular Pulls: Regularly pull changes from the main branch to stay up-to-date. This helps reduce merge conflicts and ensures your branch is in sync.
  • Communication: Communicate changes and issues promptly. Use issue tracking and project management tools to keep the team informed.
  • Documentation: Document your code and processes. Good documentation helps new team members get up to speed and makes it easier to maintain the codebase.

More reference topics

  • Infrastructure as Code — Three ways to define servers, networks and cloud resources in version-controlled text, and the sweet spot of each.
  • Learning to Script — The six things that reliably stall a new scripter, with worked examples of how to get past them.
  • Hypervisors — Comparing the three hypervisors you are most likely to run, plus optimisation and live video handling.
  • Linux — Choosing between the three most common server distributions, and the system knowledge that applies whichever you pick.
  • CI/CD Pipelines — The case for automating your build and deploy, the common ways it goes wrong, and what good practice looks like.
  • IoT — The open-source platforms worth knowing, and an honest look at what IoT delivers and what it risks.
  • AI Practices — How to use AI coding assistants so they multiply what you can build, rather than handing you code you cannot debug.
  • Cookies & Storage — Two browser storage mechanisms, constantly confused: what each is for, and how both get abused.
  • Browser Stats — A live read-out of what this page can see about your browser — the same things every other site can.

Support Me

If you find my work interesting, please consider supporting me.