When working with Git, crafting comprehensive commit messages is crucial for maintaining a clear project history. Often, a single line commit message might not be sufficient, and you may need to add more detail in multiple lines. Fortunately, Git supports multi-line commit messages from the command line, allowing developers to provide a summary line followed by a more detailed description after a line break.

Creating Multi-line Commit Messages

Using the -m option multiple times

One straightforward method to insert a multi-line commit message via the command line is by using the -m option multiple times. Each usage of -m allows you to add a new line to the commit message:

git commit -m "Summary of the commit" -m "A more detailed explanation of the commit:"

In the example above, the first -m provides a summary of the commit, and the second -m typically includes a detailed explanation that will appear on a new line.

Using an inline approach

Another method is to include newline characters within a single -m argument. This approach can depend on the shell you are using. For bash, you use $'\n' to signify a newline:

git commit -m "Summary of the commit"$'\n\n'"Detailed explanation of the commit"

This commands insert two newlines (\n\n) between the summary and the detailed explanation. Adjust the number of \n characters based on how many lines you want to insert.

Using an External Editor

For those who prefer not to use command line tricks, Git can be configured to use an external text editor (like Vim, Nano, or even VS Code) for commit messages:

1. Set your preferred editor via Git configuration:

   git config --global core.editor "nano"

1. Just use git commit without -m:

   git commit

This will open your configured editor. Here, you can write your commit message, using as many lines as you like, and then save and exit the editor to complete the commit.

Best Practices for Multi-line Commit Messages

When writing multi-line commit messages, it's good to follow a conventional structure:

• First Line: Write a concise summary of the changes, ideally not more than 50 characters.
• Second Line: Leave it blank.
• Third Line and Beyond: Provide a detailed description of the changes. Include motivations for the change, contrast this with previous behavior, mention any side-effects or notable drawbacks.

Summary Table

Additional Tips

Additional considerations when crafting commit messages from the command line:

• You can use the git config --global commit.template <file> command to set a commit message template. This can help ensure that all commit messages follow a predefined format.
• If a commit pertains to a specific issue in your tracking system, include the issue number in the commit. For example, "Fix #42: Correct off-by-one error".
• Review your commit messages with git log before pushing to make sure they're clear and follow your team's conventions.

Conclusion

Multi-line commit messages are essential for detailed documentation of changes in a project's lifecycle. Using either multiple -m options, inline newline characters, or an external editor are all effective ways to format these messages on the command line. By following best practices and setting up a personal or team convention for commit messages, you can enhance both your and your collaborators' understanding of the project history.