= Commit Messages = Commit messages are a form of communication with other developers. As such, they should be understandable and informative, providing context for the changes that have been made. Since we use Git for version control, messages should also adhere to certain formatting conventions that make it easier to work with Git and related tools. [[PageOutline(2)]] == Guidelines == #guidelines 1. **Subject.** Summarize your changes in the first line of the commit message. For very straightforward commits, this one line could be the entire message. - **Include the most important information.** Don't assume that readers can see the entire commit message; subjects often appear in isolation (e.g., GitHub history listings, `git log --oneline`, `git shortlog`). - **Be specific.** Avoid vague subjects like "Update to latest version" or "Fix the build". For example, if you are updating a port to a new upstream version, mention the version number. - **List any modified ports.** A good way to do this is to put their names first, followed by a colon (e.g., "autoconf, libtool:"). To save space, you can use glob notation (e.g., "[[span(py3*-numpy:, style=white-space: nowrap)]]", "[[span(clang-3.![6-9]:, style=white-space: nowrap)]]") or describe the ports' commonality (e.g., "boost dependents:"). - **Try to use no more than 50–55 characters**, and treat 60 characters as a hard maximum. Feel free to shunt minor changes down to the message body. If you are having serious trouble meeting these limits, consider breaking up the commit into smaller pieces that are easier to describe. 1. **Blank line.** Separate the subject from the body with a blank line; otherwise tools that parse Git history will get confused. Plus, it looks better. 1. **Body.** Use the rest of the commit message to provide context for your changes. - **Say what the commit itself cannot.** What was the previous behavior, and why was it incorrect or suboptimal? How does your commit change that, and why did you choose this particular approach? Don't just translate the commit diff into English. (However, some context is understood and need not be pointed out. For example, we assume that updating a port to a new upstream version is beneficial. You do not have to describe the deficiencies of the old version and benefits of the new one.) - **Use full URLs.** TracLinks do not work on GitHub (obviously), so refer to Trac tickets by URL instead of number (e.g., "!https://trac.macports.org/ticket/12345" instead of "!#12345"). To refer to GitHub resources, you may use the [https://help.github.com/articles/autolinked-references-and-urls shorter syntax] such as "#//n//" for pull requests, but the full URL is less ambiguous and makes it easier to follow when viewing `git log` on the command line. The GitHub web interface will always display links to its own resources in the short syntax anyway. For references to commits, use [[span(SHA-1, style=white-space: nowrap)]] hashes. - **Wrap body text at 72 characters.** Git does not do this automatically, so hard-wrap the body to prevent text from overflowing standard-width terminal emulators. This also ensures that the output of `git format-patch` adheres to [http://www.openbsd.org/mail.html#Netiquette good email etiquette]. (You can't do much about very long URLs, unfortunately.) [https://github.com/macports/macports-ports/commit/26b47fe841eb3ce024882dacac49bfdf1e442b53 An example]: {{{ get_iplayer: update to version 3.0.0 * update to version 3.0.3 * add maintainer's github handle * remove creation of perl variants Closes: https://trac.macports.org/ticket/54100 Closes: https://github.com/macports/macports-ports/pull/461 }}} For more detail on general conventions for Git commit messages: - [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html A Note About Git Commit Messages] by Tim Pope - [http://chris.beams.io/posts/git-commit How to Write a Git Commit Message] by Chris Beams == Keywords == #keywords Commit messages can include keywords that trigger certain Trac actions. The keywords are case-insensitive and must be followed by the URL of a Trac ticket. - **"References", "refs", "addresses", "re", "see":** A comment is added to the referenced ticket, containing the commit message and a link to the commit. {{{ See https://trac.macports.org/ticket/12345. }}} {{{ Re: https://trac.macports.org/ticket/98765 }}} - **"Close", "closed", "closes", "fix", "fixed", "fixes":** Same as above, and the ticket is closed as "fixed". Similar keywords can be used to [https://help.github.com/articles/closing-issues-via-commit-messages automatically close GitHub pull requests]. {{{ Maintainer fixed https://trac.macports.org/ticket/2468. }}} {{{ Closes: https://trac.macports.org/ticket/13579 }}} This functionality is provided by Clemens Lang's [https://github.com/neverpanic/trac-configurable-ctu trac-configurable-ctu], an extension of Trac's [https://trac.edgewall.org/wiki/CommitTicketUpdater Commit Ticket Updater]. == Corrections == #corrections Unlike Subversion, which stores changeset logs as mutable [http://svnbook.red-bean.com/en/1.7/svn.advanced.props.html properties], Git commit messages are integral parts of [https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#Commit-Objects commit objects], which are immutable. Correcting a commit's message replaces the commit and all its descendants with new commits (because every commit contains the [[span(SHA-1, style=white-space: nowrap)]] hashes of its parents). This may or may not be a problem. - You can correct any commit you have not pushed to GitHub by [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-the-Last-Commit amending it] or doing an [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages interactive rebase]. It's good practice to review local commits before pushing them. - You cannot correct commits that you have already pushed to the master branch. Comment on the commit's GitHub page instead. (Modifying your local history causes it to diverge from the public history. Publishing this alternate history would require force-pushing, which we [https://help.github.com/articles/about-protected-branches disallow] because it's [https://git-scm.com/book/en/v2/Git-Branching-Rebasing#The-Perils-of-Rebasing bad practice].) - On the other hand, its acceptable to modify commits made to a feature branch, for instance as part of the review of the GitHub PR where changes are requested and thus the commits need to be squashed to maintain a single clean commit for the PR changes. In this case you will need to force push the changes back to the feature branch on GitHub, at which point the PR will automatically pick up those changes. If you have a relatively recent Git, you can easily check whether a commit `deadb33f` is already in the history of a remote branch: {{{ #!sh $ git fetch origin master $ git merge-base --is-ancestor deadb33f origin/master }}} == Text editors == #editors When Git requires a text editor, it chooses one from [https://git-scm.com/docs/git-var#_variables the following sources], in order: 1. the `GIT_EDITOR` environment variable 1. the `core.editor` Git configuration variable 1. the `VISUAL` environment variable 1. the `EDITOR` environment variable 1. the compile-time default (usually vi) It is best to modify your shell startup files to set the `VISUAL` or `EDITOR` environment variables. Git requires no configuration to use them, and they can be used by other programs too. {{{ #!sh # Bourne shell (sh) and relatives export VISUAL VISUAL=nano }}} {{{ #!csh # C shell (csh) and relatives setenv VISUAL nano }}} If for some reason you want to override `VISUAL`/`EDITOR` and use a different editor with Git, you can specify it in `$HOME/.gitconfig`: {{{ #!sh $ git config --global core.editor ed }}} In case you're using {{{vim}}} as your favorite editor you might want to enable colorizing the commit messages according to the required formatting rules w.r.t. characters in the first and subsequent lines like this: {{{ filetype plugin indent on hi def link gitcommitOverflow Error autocmd BufEnter COMMIT_EDITMSG \ if &textwidth > 0 | \ exec 'match Overlength /\%>' . &textwidth . 'v.\+/' | \ endif hi def link Overlength Error " or customize it with other colors "hi OverLength ctermbg=LightRed guibg=LightRed }}} which needs to be saved in {{{~/.vimrc}}}.