Creating a Commit (git commit)

In version control systems, the git commit command serves as the bridge connecting daily code modifications to the historical record. Every commit not only records a snapshot of the current working directory files but also encapsulates the developer's intent regarding that code, along with timestamps and reasons for changes. A standardized commit acts as both the cornerstone of the codebase and the core vehicle for communication and collaboration within teams. Understanding and mastering how to create high-quality commits is a fundamental skill that every Git user must master.
Before executing git commit, developers typically need to use git add to modify files into the staging area (Staging Area). This step is critical because Git's commit mechanism operates on a three-phase model ranging from "working directory" to "staging area," and then to "local repository."

If you attempt to commit un-staged changes directly, Git will error out with messages like "nothing to commit, working directory clean" or list all changes for your selection. Therefore, the standard operating procedure is as follows:

  1. Check Change Status: Run git status to see which files have been modified and which are staged.
  2. Add Files: Use git add <filename> or the batch command git add . to put changes into the staging area.
  3. Verify Staged Content: Run git status again to confirm that the "Changes to be committed" section includes the files you expect to commit, while "Untracked files" does not contain code needing to be submitted.

Constructing High-Quality Commit Messages

The quality of commit message writing directly determines future code maintainability. Git commit records are part of the project history; clear information allows other developers to quickly understand the background, scope, and impact of changes. The industry-standard best practice is to adopt a format similar to "Commit Message Convention," which typically includes the following four elements:

  • Type: Describes the nature of the change, such as feat (new feature), fix (bug fix), docs (documentation update), etc.
  • Scope: Indicates the module or file affected, such as api, auth, or specific filenames.
  • Short Description: Summarize the core content of the change in one or two sentences, avoiding lengthy sentences.
  • Detailed Explanation: Provide technical details, the affected user groups, and testing methods in subsequent lines (separated by a blank line).

An example of an excellent commit message is as follows:

feat(auth): Add user password encryption storage functionality

- Introduce bcrypt library for hashing passwords
- Update database migration scripts to support new fields
- Fix compatibility issues with old version login interfaces

Related PR: #102
Tests passed, coverage increased to 95%

Executing Commit Commands and Parameter Details

Once the staging area is ready and the message is conceived, you can execute the final commit command. The basic syntax is simple, but mastering optional parameters can significantly improve work efficiency.

Basic Command

The core command is:

git commit -m "Short Description"

The -m parameter allows entering commit messages directly in the command line, avoiding potential context loss that might occur when opening an editor.

Common Advanced Options

In actual development, developers often need to combine other parameters to handle complex scenarios:

  • Ignore Conflict Resolution: If there are unresolved merge conflicts in the staging area, Git will prevent the commit. In this case, you can use --no-verify (skip hook checks) or manually resolve conflicts before committing.
  • Include Unstaged Changes: Sometimes developers want to package all modifications in the working directory into a single commit; you can use the -a parameter (i.e., --all), which adds both tracked and untracked changes simultaneously.
    git commit -m "Description" -a
  • Undo Last Step: If incorrect information was committed or files were accidentally modified, you can use git reset --soft HEAD~1 to undo the commit while keeping changes in the working directory, or use git commit --amend to modify the metadata of the previous commit.

Best Practices and Precautions

To ensure the health of the codebase, it is recommended to follow these operational standards:

  • One Thing Per Commit Principle: Try to keep each commit focused on solving a specific problem or implementing a single feature. This aids subsequent Code Review and rollback operations.
  • Avoid Large Blocks of Text: Do not include large blocks of Markdown-formatted text, long strings, or detailed comments in commit messages; this information should be reflected in the code changes themselves or recorded through documentation.
  • Maintain Chronological Order: Although Git supports rewriting history, avoid casually using git rebase or git cherry-pick to rewrite history to prevent breaking the collaboration chain.

By following the above steps and principles, developers can construct clear, transparent, and easily maintainable code histories. This not only improves individual development efficiency but also provides valuable technical assets for the entire team.