Page MenuHomePhabricator

Upgrading: Mid 2020 Changes to "arc feature" / "arc branch" / "arc bookmark"
Open, NormalPublic



Previously, Arcanist had three workflows which were aliases for one another: arc feature, arc branch, and arc bookmark. All three workflows ran the same code internally.

These workflows had two separate modes aimed at accomplishing two different goals:

  • Without arguments, these workflows meant "show me the current working copy state, annotated with revision information".
  • With arguments, these workflows meant "begin or continue work on a change".

These workflows also were not careful about terminology and chose behavior based on the current VCS, so there were cases where arc branch would show or affect bookmarks and arc bookmark would show or affect branches.

I've attempted to make these workflows easier to understand by:

  • clearly separating the two different goals ("show me the working copy"; "begin or continue work") into different commands; and
  • removing all cases where you could run a "branch" command and affect bookmarks, or a "bookmark" command and affect branches.

Changes and Compatibility Breaks

Previously, you invoked "show me the current working copy state" by running arc feature, arc branch, or arc bookmark without arguments.

You invoked "begin or continue work on a change" by running arc feature X, arc branch X, or arc bookmark X (that is, with arguments).

  • "Show me annotated branches in the working copy" is now arc branches. This read-only workflow shows branches in the working copy. It shows branches in every VCS (previously, it showed bookmarks in Mercurial).
  • "Show me annotated bookmarks in the working copy" is now arc bookmarks. This read-only workflow shows bookmarks in the working copy. It shows bookmarks in every VCS (previously, it showed branches in Git).
  • "Being or continue work on a change" is now arc work.

These changes are aimed at simplifying these commands, particularly in Mercurial. See T2928. Previously, it was fairly unpredictable that that arc branch showed bookmarks, and that arc branch X allowed you to create a bookmark, and that there were several different ways to accomplish the same goals, and that arc bookmark X created a branch in Git, which doesn't even have a concept of bookmarks. After these changes, exactly one command is used to accomplish each task regardless of the VCS, and each command always does the same thing and accomplishes the same goal regardless of arguments.

TaskVCSOld CommandNew Command
Show branches.gitarc branch or arc bookmark or arc featurearc branches
hgNot Supportedarc branches
Show bookmarks.gitN/AN/A
hgarc bookmark or arc branch or arc featurearc bookmarks
Work on a change.gitarc feature X or arc branch X or arc bookmark Xarc work X
hgarc feature X or arc branch X or arc bookmark Xarc work X

Because arc automatically corrects the spelling of commands and accepts unique prefixes of commands as short variations, arc branch and arc bookmark will still technically work, but the proper names of these workflows are now branches and bookmarks. You can also use arc alias to redefine these if you've developed muscle memory for the old commands.

  • The arc.feature.start.default configuration option has been removed. Specifying a startpoint is still supported (with arc work --start Y). You can use arc alias to define a convenient alias if you'd like a command which always starts from a particular branch. I don't currently plan to restore a configuration option for this, since this isn't a behavior that impacts other people working on a project and the default behavior (branching from the current state) is generally a desirable one.

View All Unpublished State

arc branches and arc bookmarks now attempt to show all unpublished state in the working copy, not just the heads of branches or bookmarks:

Generally, this should provide a better hint about how local changes are related to one another and what arc land will do. For example, in the screenshot above, xdiff10 is branched from xdiff9, which is branched from xdiff7. If you arc land xdiff10, all three changes will (at least, by default) land. This is now more obvious from the output of arc branches.