Page MenuHomePhabricator

Document the special syntax you can use in commit messages to cause effects
Open, NormalPublic

Assigned To
None
Authored By
epriestley
May 20 2014, 1:37 PM
Referenced Files
None
Tokens
"Like" token, awarded by Taffer."Love" token, awarded by florianb."Like" token, awarded by Jacksgong."The World Burns" token, awarded by renannp."Like" token, awarded by vinzent."Like" token, awarded by carlsverre."Orange Medal" token, awarded by chad.

Description

Particularly, "Auditors", "Fixes" and "Depends on".

Event Timeline

epriestley raised the priority of this task from to Normal.
epriestley updated the task description. (Show Details)
epriestley added a project: Diffusion.
epriestley added a subscriber: epriestley.

Special commands in comments can cause various effects, like closing a related task when a commit is pushed.

Attaching to Tasks

Summary: Attach a revision or a commit to a task with Ref T123 in the summary.

Attach to a task with "Ref", "Refs", "References" or "cf." These are hard-coded and case insensitive. This works in Differential and commits. For example, writing Ref T123 in a revision summary will attach that revision to task T123.

You can specify several tasks, optionally using commas: Ref T123 T124, or Ref T123, T124.

You can optionally add a noun, like Ref task T123. See "Close Related Task", below, for details.

Attaching to Tasks using Branch Names

Summary: Attach a revision to a task by diffing it from a branch name like T123-newfeature with arc.

In Differential, revisions updated with a diff from a branch starting with T123 (for example, T123 or T123-colors) will be attached to the corresponding task. This requires you to use arc (not just copy/paste diffs) so that branch information is preserved.

Close Related Task

Summary: Close a task when pushing a commit with Fixes T123 in the summary.

Close a related task with syntax specified in maniphest.statuses. Each task status can specify prefixes and suffixes. These are used in the form <prefix> <optional noun> Txxx [optional more Txxx] <optional suffix>. For example, Closes T123 or Closes T123 as Wontfix.

By default, the prefixes are: closed, closes, close, fix, fixes, fixed, resolve, resolves, resolved, wontfix, wontfixes, wontfixed, invalidate, invalidates, invalidated, spite, spites, spited.

By default, the suffixes are: out of spite, as spite, as invalid, as wontfix, as resolved, as fixed.

The prefix (and, optionally, the suffix) select which status the task will be closed with. For example, Invalidates T123 closes T123 as Invalid. When a phrase has both a prefix and a suffix, the suffix wins. For example, Invalidates T123 as wontfix closes T123 as Wontfix. The intent is to allow common prefixes like "closes" to be bound to a generic closed status while still allowing the relatively natural construction "closes X as invalid" to work as expected.

You can change these in maniphest.statuses. They are case-insensitive.

You can optionally use a noun after the prefix. The supported nouns are: task, tasks, issue, issues, bug, bugs. These are hard-coded and case insensitive. These also work with the "Ref" syntax. For example, Fixes bugs T123, T124.

These phrases work in commits. In Differential, they are recognized, but just work like "Ref". The intent is to allow you to write Fixes T123 in a commit message, have it reviewed, and then have the task automatically close on commit.

Depends On

Summary: Mark a revision as depending on another revision with Depends on D123 in the summary.

Only the "depends on" prefix is recognized. This is hard-coded and case insensitive.

These nouns are recognized. They are hard-coded and case insensitive: diff, diffs, change, changes, rev, revs, revision.

You can specify a list of revisions, like Depends on D123, D124.

Reverts

Summary: Mark a commit as reverting something with Reverts rXabcdef.

This doesn't do much right now, but is recognized.

These hard-coded, case insensitive prefixes are supported: revert, reverts, reverted, backout, backsout, backedout, back out, backs out, backed out, undo, undoes.

These hard-coded, case insensitive nouns are supported: commit, commits, change, changes, changeset, changesets, rev, revs, revision, revisions, diff, diffs.

Not Working?

See T4767 for status on making these easier to debug.

See Also

  • T4036 will make mentioning objects (as T123) anywhere generate a lightweight crosslink.

This will move into the real docs eventually, but it spans a bunch of applications and will change a bit after T4767 / T4036 and some other things (maybe T5117).

This might be nice to move to the new-ish help dropdown.

Hey guys, where should I hook my custom parser if I need to add any additional behaviour on 'CodeReviewed' keyword in commit message due to parsing from repository?
Actually I need to mark commit as audited when commit message contains previously specified string.

Many thanks in advance.

Is the information from above (T5132#69200) also available in the documentation in this comprehensive form?

No. This task covers documenting this syntax.

Is there a syntax to close audits? Something like "Fixes: <commit-hash>"?

Does this work without using arc and just normal git commit?

One possible approach for this is:

  • Implement T11934.
  • Implement !fixes T123 as alternative syntax for all the magic supported here.
  • Add a "command reference" button to the remarkup area.
  • List both the !fixes T123 and Fixes T123 variations in the help.

Beyond that, T13057 is likely to add a "resurrects" syntax shortly, and expand the existing "reverts" syntax to accept revisions.

Are colons (:) supported between the keywords and the objects? E.g. Fixes: adcbdef or Depends On: D123?