(IMPORTANT) The `master` branch of "Arcanist" is currently more unstable than usual. This task describes ongoing changes in `master`. You can switch to `stable` until the dust settles if these changes are impacting your workflow.
**The minimum PHP version required to run Arcanist is now PHP 5.5**, which was released seven years ago in 2013. Requiring this version of PHP allows Arcanist to use a few new language features, including: traits; `yield`; and `finally`. See T11968 for some details.
**libphutil is no longer required.** All the code in "libphutil/" which Arcanist requires has been merged into "arcanist/". "libphutil/" is now an empty repository with a README file. See T13395 for discussion. You can safely delete the "libphutil/" directory if it is empty and everything is working for you.
These flags to common `arc` workflows have been removed:
| **arc diff** | `--plan-changes` | {icon times color=red} Removed, see T13010. Try `--draft`.
|---|
| | `--preview` | {icon times color=red} Removed, see T13010. Try `--draft`.
| | `--no-diff` | {icon times color=red} Removed, see T13010. Legacy flag.
| | `--cache` | {icon times color=red} Removed, see T13010. Legacy flag.
| **arc lint** | `--only-changed` | {icon times color=red} Removed. Try "warning" severity.
|---|
| | `--only-new` | {icon times color=red} Removed. Almost never worked correctly.
| | `--cache` | {icon times color=red} Removed. Legacy flag.
**The way shell completion is configured has changed.** If you use this feature, see below for update instructions.
---
These workflows have been **removed**.
In some cases, these workflows were added a long time ago (circa 2012-2013) by a contributor, do something trivial, and have never been improved by later patches. This is likely to indicate that no one (or almost no one) uses them.
In the case of Phrequent workflows, Phrequent was contributed, has remained a prototype, and has no interest from current customers. It's not likely to move forward any time soon and isn't worth the effort to maintain the CLI integration, given the unclear argument for the value it's providing.
| **arc backout** | Trivial wrapper around backout/revert. |
| **arc close** | Closes a task. |
| **arc flag** | Flags objects, or lists flagged objects. |
| **arc start** | Starts time tracking in Phrequent. |
| **arc stop** | Stops time tracking in Phrequent. |
| **arc time** | Lists time tracking in Phrequent. |
| **arc revert** | Alias of "backout". |
---
These minor behaviors have also changed:
**Reduced Compatibility with Ancient Phabricator**
Some workflows which previously used last-generation APIs or fell back to last-generation APIs now require modern APIs. These APIs include:
- `paste.edit`, introduced in D14393 in Nov 2015.
- `user.search`, introduced in D15959 in May 2016.
- `differential.revision.search`, introduced in D16089 in June 2016.
- `diffusion.commit.search`, introduced in D17194 in Jan 2017.
- `file.search`, introduced in D17612 in April 2017.
If you have not upgraded Phabricator in several years, this is a great time to upgrade.
**CLI/Scripting Behaviors**
- Configuration flags must now be specified before workflows. For example, `arc --config x=y diff` is valid, but `arc diff --config x=y` is not valid.
- When stdout is not a TTY (usually, this means you're running `arc` in a script/non-interactive environment), command line flags must now be explicitly terminated with `--` (the "end of flags" argument), even if there are no flags, or no arguments, or the command you are executing can not take flags or arguments or is otherwise completely unambiguous. See T13491 for more discussion.
- `arc` no longer exits with error code 77 to indicate invalid flags.
**Workflow: Alias**
- `arc alias` will no longer remove redundant flags. Previously, you could define `arc draft -> arc diff --draft`, then run `arc draft --draft` (which would naively resolve to `arc diff --draft --draft`) and have your duplicate flag cleaned up. This isn't safe in the general case and deviates from the explicit approach we generally prefer elsewhere.
- Shell aliases (like `arc alias ls -- '!ls'`) are now stored as individual arguments, so existing aliases may need to be redefined by running `arc alias ...` again. In particular, `arc alias x -- '!y z'` now defines an alias `x` which runs the shell command `'y z'` (i.e., a binary name with a space in it), not the binary `y` with argument `z`.
- Shell aliases now escape their arguments, and thus no longer support inline shell code. (You can put shell code in a shell script on disk and have `arc alias` execute that, or perhaps define an `!sh -c ...` alias).
- You //can// now define aliases that resolve to other aliases, creating alias chains. Exceptionally useful! Thousands of users have demanded this feature!
- `alias` is now a global workflow for any toolset.
- Note that only "modern" workflows can be resolved by "arc alias".
**Workflow: Download**
- The `--show` flag (which printed the file to stdout) has been removed. Use `--as -` to achieve the same effect.
- `arc download` can now download files which are too large to fit into memory, although see T13352 if you are downloading files larger than 20GB.
**Workflow: Help**
- The `arc help --full` flag no longer exists. `arc help` is more verbose than it was before.
- `help` is now a global workflow for any toolset.
- Note that only "modern" workflows appear in "arc help".
**Workflow: Liberate**
- `arc liberate` now liberates all libraries under the current working directory if given no arguments.
- The flags `--library-name`, `--force-update`, `--remap`, and `--verify` no longer exist.
- The flag `--upgrade` no longer exists. v1 libraries can no longer be upgraded to v2. If you have a library which is 5+ years old, remove all the `__init__.php` files and then just do a clean liberate on it.
- The flag `--all` has been renamed to `--clean` (like `make clean`), for consistency with other commands and to disambiguate the new default behavior of rebuilding all libraries in subdirectories.
**Workflow: Paste**
- The `--json` flag has been removed. Modern programs can interact with Paste more flexibly by calling the API directly, or by calling the API via `arc call-conduit`.
**Workflow: Shell Complete**
- `arc shell-complete` now installs itself (when you run `arc shell-complete`).
- You should edit anywhere you stuck the old `source path/to/arcanist/.../bash-completion.sh` line (like `~/.profile`) and remove it. Then, run `arc shell-complete` to install the updated hook. Finally, start a new shell to pick up the changes.
- The behavior of completion has changed somewhat, but probably not in any meaningful ways for most users.
- Support for ZSH has been removed. This was contributed and I wasn't able to figure out how to make it work on `master`, so I suspect it may never have worked for more than one person in 2012. I'm open to restoring support if you're a ZSH wizard and can convince me that your implementation is correct and supportable, //and// it works out of the box for me by magic. See <https://github.com/phacility/arcanist/pull/11> for the heady days of an upstream with low contribution barriers.
- `arc shell-complete` is now a global workflow for any toolset.
- Note that only "modern" workflows can be completed by `arc shell-complete`.
**Workflow: Version**
- `version` is now a global workflow for any toolset. (But it isn't useful for other toolsets yet.)
**.arcrc**
- The internal format of this file has changed, and it will now be written with keys at top level (instead of inside a "config" key). The old format will still be read. This only impacts you if you're manually reading `.arcrc` files, which you probably should not be.
**Global Flags**
- Removed `--conduit-version`. We do capability testing, now.
- Removed `--conduit-timeout`. Not clear this ever really had any callers.
- Removed `--skip-arcconfig`. Unclear what this was for. FB only option because someone created an invalid file at `/home/.arcconfig`?
**Configuration**
- Removed the `arc.lint.cache` configuration setting.
- Removed the `arcanist_configuration` configuration setting. This is a legacy/FB-only option which doesn't fit into the roadmap.
- The `http.basicauth.user` and `http.basicauth.pass` configuration options are no longer supported. These served a very niche use case. If you're a customer and need this, we can provide some similar capability via `PhutilHTTPEngineExtension`; file a support request.
- The `https.blindly-trust-domains` configuration option is no longer supported. It's 2020, legitimate SSL is completely free now, and you should configure it properly. If you "need" this, you can implement it via `PhutilHTTPEngineExtension`.
---
Some internal APIs have also changed. This list is not exhaustive, but some of the most important changes are:
- `Future->resolve()` no longer accepts a timeout. If you need to return execution to the caller after a certain amount of time, wrap the future in a `FutureIterator` and use `setUpdateInterval()`.
---
And:
- The `preg_quote()` lint rule has been removed. This had false positives on safe/correct use of `preg_quote()` with `(` and `)` as the expression delimiters, which is the modern coding style in this codebase.
- The "use `__CLASS__` instead of hard-coding a class name" lint rule no longer raises a warning if you use the class name as part of a longer string. So the string `"Filesystem"` (class name hard-coded as a string literal) still raises a warning if it appears in the class `Filesystem`, but the string `"Filesystem path X does not exist."` (class name used as an English word in a longer string) no longer raises this warning.