in src/workflow/ArcanistStackWorkflow.php [51:168]
public function getCommandHelp() {
return phutil_console_format(<<<EOTEXT
Supports: git
Submits an accepted stack of diffs after review to Submit Queue for landing. This command is the last
step in the standard Differential pre-publish code review workflow.
This command also supports landing stack of diffs to repositories which do not use Submit Queue. Changes
are pushed to repository atomically as one pack. Only changes present in Phabricator will be applied! Make
sure your changes are synced to Phabricator otherwise you might loose them!
FAQS:
1. What are the Submit Queue guarantees for Stacked-Diffs ?
(a) Submit Queue guarantees atomicity for landing all diffs within a single stack. Either all diffs in the
stack gets pushed to the remote together (in one single git push) or none of them is pushed.
(b) Submit Queue will preserve the commit points at each diff in the stack. Currently, arc land uses one
commit-message if there are many commits corresponding to a differential. Arc stack will retain that
behavior (one commit per diff in the stack) but will NOT squash the commits for
different diffs in the stack to one commit.
(c) Submit Queue will run build validations at each diff in the stack to ensure each commit point keeps
the master green.
2. How does arc-stack detect the list of revisions in the stack ?
arc-stack treats all the arcanist-revisions (DXX) between HEAD and base-revisions as a single-stack.
It collects the revisions from git commit log. There is no need to specify explicit stack dependency.
3. Do my diffs need to have explicit dependency in phab?
No, there is no need to specify dependency in phab. arc-stack automatically figures it from commit-log
of your current branch.
4. If I have diffs 1-8 on my branch can I just land 1-5?
Yes, it is possible. You just have to create a named-branch with 5 as your HEAD commit and run "arc stack".
git checkout -b <branch_name> <commit-id-of-5>
arc stack
5. What validations are done as part of arc-stack ?
Apart from general validations done in "arc land" (like diff and buildable status), arc stack
ensures each revision in the stack is stacked against the latest diff of its parent.
6. Will arc-stack do auto-rebase if it detects inconsistencies ?
If arc stack detects rebase inconsistencies, Users will be prompted to rebase. Arcanist can also try to
auto rebase and arc-diff on behalf of user but this is ONLY BEST EFFORT. If there are merge-conflicts,
it would exit and users would need to fix the conflicts and cleanup branches themselves.
Users are still expected to do rebase the first diff in the stack against the target branch before
running arc stack. Otherwise, Submit Queue may reject the request during Merge-Validation Check.
7. What are the requirements for a repo to be stack-diff ready ?
arc stack for Submit Queue relies on tag-based patching (git tags in staging repos) to ensure any arbitrary
revision in the stack can be patched for running merge-conflict and build-checking validations. For this case,
arc patch has a new flag "uber-use-staging-git-tags". In other words, the 2 requirements are:
(a) Staging repository must be enabled for the repo.
(b) Jenkins jobs that runs validations as part of Submit Queue MUST use the above flag during arc patch.
arc stack for usual repositories is simply patching Revisions it detected on top of each other, also it is
checking each Differential Revision build status.
8. How to contact support team with arc-stack questions ?
Please ping us at "submitqueue" slack channel.
If you have issue with `arc stack` while landing changes to non Submit Queue enabled repository, please ping us at
"Phabricator" slack channel.
For any error reporting, please run arc-stack command in verbose mode with ARCANIST_TRACE enabled as below
ARCANIST_TRACE=1 arc stack --trace
DESCRIPTION:
The workflow selects a target branch to land onto and a remote where
the change will be pushed to.
Under Git: branches, tags, and arbitrary commits (detached HEADs)
may be landed.
A target branch is selected by examining these sources in order:
- the **--onto** flag;
- the upstream of the current branch, recursively (Git only);
- the __arc.land.onto.default__ configuration setting;
- or by falling back to a standard default:
- "master" in Git;
- "default" in Mercurial.
A remote is selected by examining these sources in order:
- the **--remote** flag;
- the upstream of the current branch, recursively (Git only);
- or by falling back to a standard default:
- "origin" in Git;
- the default remote in Mercurial.
After selecting a target branch and a remote, the commits which will
be landed are printed.
With **--preview**, execution stops here, before the change is
merged.
The resulting commit will be given an up-to-date commit message
describing the final state of the revision in Differential.
In Git, the merge occurs in a detached HEAD. The local branch
reference (if one exists) is not updated yet.
With **--hold**, execution stops here, before the change is pushed.
The change is pushed into the remote.
Consulting mystical sources of power, the workflow makes a guess
about what state you wanted to end up in after the process finishes
and the working copy is put into that state.
The branch which was landed is deleted, unless the **--keep-branch**
flag was passed or the landing branch is the same as the target
branch.
EOTEXT
);
}