Proper Use of Git and GitHub in Projects – Best Practices

Git and GitHub are integral parts of modern programming. They not only help manage code versions but also serve as the best tools for team collaboration and project structure organization. In this blog, we will discuss best practices that will help you use Git and GitHub correctly and efficiently.

1. Fundamental Git Rules

✅ Regular Commits

It is recommended to make code changes in small, logical commits to keep history clear and understandable. Frequent, meaningful commits make it easier to track changes, identify issues, and revert specific modifications when needed.

Example:

git add .
git commit -m "Fixed login bug and improved UI"

✅ Meaningful Commit Messages

Commit messages should be short and informative. It is preferable to write them in the first person so that the message clearly reflects the change. Avoid generic messages like "update" or "fix." Instead, describe what was fixed, updated, or improved.

Bad Example:

git commit -m "Update"

Good Example:

git commit -m "Fixed issue with incorrect password validation"

✅ Keeping Commits Atomic

Each commit should contain a single logical change. Avoid bundling multiple unrelated changes in a single commit. This makes debugging and code review easier.

2. Git Branching Strategy

✅ Using Main Branches

• main/master: Stable code that is ready for production.
• develop: The development stage where new features are implemented.
• feature branches: Separate branches for specific features that are merged into "develop" upon completion.
• hotfix branches: Used for urgent fixes in production.

Example:

git checkout -b feature/user-authentication

✅ Importance of Pull Requests (PR) and Code Review

GitHub’s Pull Requests make code review within a team easier.

• Code review is essential to avoid mistakes and maintain high code quality.
• Use Draft PRs if the change is still in progress.
• Encourage peer review, where at least one other team member reviews the code before merging.
• Provide detailed descriptions in PRs to explain the purpose and impact of changes.

3. Best Practices for GitHub

✅ Using a README File

A README.md file must be present in the project’s root directory, describing:

• The purpose of the project
• Installation process
• Usage instructions
• Contribution guidelines (if applicable)

✅ Using a .gitignore File

To avoid committing unnecessary files, a properly configured .gitignore is essential. Each programming language has common files that should be ignored to prevent cluttering the repository.

Example (.gitignore for a Python project):

__pycache__/
*.pyc
.env
node_modules/
dist/

✅ GitHub Actions and CI/CD

For automatic code testing and deployments, using GitHub Actions or another CI/CD system is recommended. This ensures that the code is tested before merging to the main branch, reducing the risk of bugs.

Example (GitHub Actions YAML Configuration):

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Dependencies
        run: npm install
      - name: Run Tests
        run: npm test

✅ Enforcing Code Standards with Linters and Formatters

To maintain a consistent coding style, integrate tools like ESLint (JavaScript), Prettier, Black (Python), or PHP_CodeSniffer into the workflow.

npm install --save-dev eslint prettier

4. Avoiding Git Mistakes

✅ Rebase vs Merge

Rebase cleans commit history, while Merge preserves commit sequences. Use Rebase to maintain a cleaner Git history.

Using Rebase:

git checkout feature-branch
git rebase main

Using Merge:

git checkout main
git merge feature-branch

✅ Risks of Using Force Push (git push --force)

Force push can disrupt teamwork, so it should be used with caution. This is particularly dangerous when working in a shared repository.

Safer Alternative: Instead of git push --force, use:

git push --force-with-lease

✅ Handling Merge Conflicts

Merge conflicts happen when multiple branches modify the same file. To resolve them effectively:

1. Use git status to identify conflicting files.
2. Open the conflicting files and manually edit the differences.
3. After resolving conflicts, mark them as resolved:

git add conflicted-file.js
git commit -m "Resolved merge conflict in conflicted-file.js"

4. Complete the merge or rebase process.

✅ Using Git Hooks for Automation

Git hooks allow running scripts before or after specific Git events. For example, you can enforce commit message formatting.

Example: Pre-commit Hook for Linting (pre-commit file in .git/hooks/):

#!/bin/sh
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed! Please fix errors before committing."
  exit 1
fi

Make it executable:

chmod +x .git/hooks/pre-commit

5. Documentation and Knowledge Sharing

✅ Using Wiki or Docs for Internal Documentation

For large projects, maintaining internal documentation in a GitHub Wiki or separate /docs directory helps new contributors understand the project quickly.

✅ Writing Clear Contribution Guidelines

If your project is open-source or involves multiple developers, a CONTRIBUTING.md file can outline best practices for submitting changes.

Conclusion

Proper use of Git and GitHub significantly increases productivity and code quality. Pay attention to commit management, branching strategies, and pull requests. Maintain a clean Git history and use automation tools to keep your project organized and secure. Follow best practices for version control, automate repetitive tasks, and document your workflows for future contributors.