{"title":" Commit Best Practices","description":null,"content":"Understanding how to create effective commits in Git is crucial for maintaining a clean and manageable project history. Well-crafted commits not only make it easier to understand the evolution of a codebase, but they also facilitate collaboration among team members. In this chapter, we'll explore best practices for writing commits that enhance clarity, context, and collaboration.\n\n---\n\n# Meaningful Commit Messages\n\nA commit message serves as a log entry that describes changes made in a project. A good message should explain *why* the changes were made, not just *what* was changed. Here are some best practices for writing effective commit messages:\n\n### Structure of a Commit Message\n\nA well-structured commit message typically consists of three parts: a summary line, a body, and a footer.\n\n1. **Summary Line**: This should be a concise description of the change, limited to about 50 characters. Use the imperative mood (“fix bug” instead of “fixed bug”).\n2. **Body**: This section offers a more detailed explanation of the changes and the reasoning behind them. Aim for around 72 characters per line. Use this space to describe:\n 1. The motivation for the change\n 2. Any side effects or potential issues\n 3. References to issues or tickets (e.g., “Fixes #123”)\n3. **Footer**: If applicable, you can include references to related issues, breaking changes, or metadata.\n\n### Example\n\n\n```javascript\nAdd user authentication feature\n\nThis commit introduces a new user authentication system using JWT tokens. \nIt improves security by ensuring that only authorized users can access \nprotected routes. \n\nFixes #234\n```\n\n\n---\n\n# Commit Granularity\n\nThe size and scope of a commit are critical. Strive for **atomic commits** that encapsulate a single logical change. This makes it easier to review changes, revert specific features, or identify the source of bugs.\n\n### Why Atomic Commits Matter\n\nAtomic commits enhance code review efficiency. When a commit contains multiple unrelated changes, it becomes difficult to understand the intent and context. This can confuse reviewers and complicate the process of bisecting commits to find the source of a bug.\n\n### Guidelines for Atomic Commits\n\n- Each commit should represent one complete, logical change.\n- Avoid combining multiple features or fixes in a single commit.\n- If you find a commit has grown too large, consider splitting it into multiple smaller commits.\n\n### Example\n\nInstead of a commit combining multiple changes:\n\n\n```javascript\nFix bug in user login, update documentation, and refactor code\n```\n\n\nYou should have three separate commits:\n\n1. Fix bug in user login\n2. Update documentation for user login\n3. Refactor user login code\n\n---\n\n# Use of Commit Hooks\n\nGit offers hooks that can automate tasks and enforce standards. By leveraging commit hooks, you can validate commit messages, enforce coding standards, or even run tests before allowing a commit.\n\n### Setting Up a Commit Hook\n\nTo set up a commit message hook, create a file named `commit-msg` in the `.git/hooks/` directory. Here’s a simple example that ensures commit messages follow a specific format.\n\n### Example Hook Script\n\n\n```shell\n#!/bin/sh\nCOMMIT_MSG_FILE=$1\nCOMMIT_MSG=$(cat \"$COMMIT_MSG_FILE\")\n\nif ! echo \"$COMMIT_MSG\" | grep -qE \"^\\[JIRA-[0-9]+\\]\"; then\n echo \"Commit message must start with a JIRA ticket reference (e.g., [JIRA-123])\"\n exit 1\nfi\n```\n\n\nMake the script executable:\n\n\n```shell\nchmod +x .git/hooks/commit-msg\n```\n\n\nThis hook checks that every commit message begins with a JIRA ticket reference. It helps ensure that messages are informative and contextually relevant.\n\n\n> **TIP**\n>\n> Consider using tools like `husky` to manage Git hooks more conveniently, especially in collaborative projects.\n\n\n---\n\n# Avoiding WIP Commits\n\nWork-in-progress (WIP) commits can clutter your history and confuse collaborators. While it's tempting to commit frequently for backup, these interim commits can obscure the final product's clarity.\n\n### Strategies for Managing WIP\n\nInstead of committing unfinished work, consider using the following strategies:\n\n**Stashing**: Use `git stash` to temporarily save changes without committing. This allows you to switch branches or pull updates without losing your current progress.\n\n\n```shell\ngit stash save \"WIP: working on feature X\"\n```\n\n\n**Feature Branches**: Develop new features or fixes in a separate branch. This keeps your main branch clean while you work on changes.\n\n\n```shell\ngit checkout -b feature/my-new-feature\n```\n\n\nBy keeping your main branch free of WIP commits, you maintain a clear and understandable history.\n\n---\n\n# Leveraging Amend and Squash\n\nSometimes, you may find that a commit needs to be adjusted or combined with others. Git provides commands like `git commit --amend` and `git rebase -i` for modifying commit history.\n\n### Using `git commit --amend`\n\nThis command allows you to modify the most recent commit. You can change the commit message or add additional changes. \n\n#### Example\n\n\n```shell\n# Stage changes\ngit add \n\n# Amend the last commit\ngit commit --amend -m \"Updated commit message\"\n```\n\n\nThis is useful for quickly correcting mistakes without creating additional commits.\n\n### Squashing Commits\n\nDuring a rebase, you can squash multiple commits into one, which is beneficial for cleaning up commit history before merging.\n\n#### Example\n\n\n```shell\ngit rebase -i HEAD~3\n```\n\n\nIn the interactive rebase interface, change the word “pick” to “squash” for the commits you want to combine. This results in a single commit that encapsulates the changes from those squashed commits.\n\n\n> **WARNING**\n>\n> Be cautious when amending or squashing commits that have been pushed to a shared repository; it can rewrite history and cause confusion.\n\n\n---\n\n# Consistent Commit Practices Across Teams\n\nWhen working in a team, adopting a consistent commit message style and strategy is vital. Establishing team conventions can improve collaboration and maintain clarity in the project's history.\n\n### Establishing Guidelines\n\nCreate a document that outlines your team's commit message conventions, encompassing:\n\n- Formatting rules (e.g., imperative mood, structure)\n- Prefixes for categorizing commits (e.g., feat, fix, docs)\n- Guidelines on commit frequency and granularity\n\nEncourage team members to review each other's commits regularly. Code reviews can help maintain these standards and provide an opportunity to discuss best practices.\n\n---\n\nNow that you understand how to create meaningful and effective commits, you are ready to explore branching strategies. In the next chapter, we will look at how to structure your branches for optimal collaboration and project management.","pageType":"git"}

Commit Best Practices

Get Premium