Add the FileSystemFileHandle.move method

[valadaptive]

An earlier version of this was proposed in #10, but stalled out due to complications around moving directories.

When looking into it, I was therefore surprised to find that this method (at least, a subset of it) has shipped in browsers since late 2021!

Apparently, Firefox and WebKit both shipped (early versions of) this method without a flag, and have kept them ever since. Chromium added and has shipped these methods to the public IDL of FileSystemFileHandle. They did so in a commit that claimed only to remove them from FileSystemHandle. (A slightly-later update changed the single-argument version from rename to move.)

I've taken #10 and adjusted it to match what Chrome has actually been shipping, in the hope that it can be standardized and documented. In particular, directory entries can no longer be moved, and the move method has been moved from FileSystemHandle to FileSystemFileHandle.

Aside from just moving things around in the spec, there are a couple other changes:

• I've reworded the non-normative sections slightly, since Bikeshed now warns if you use the word "may" in a non-normative section.

• I've removed a couple steps in the algorithm that only exist to handle edge cases around moving directories. These steps were ensuring a directory could not be moved within itself, and ensuring the root of a bucket file system could not be moved.

The rewording is in its own commit, to make it easier to review that diff specifically.

• At least two implementers are interested (and none opposed):
  • Firefox has already implemented these methods, but on FileSystemHandle.
  • Chromium has already implemented these methods.
  • WebKit has already implemented the two-argument version of this method, but on FileSystemHandle.
• Tests are written and can be reviewed and commented upon at:
  • https://github.com/web-platform-tests/wpt/blob/master/fs/script-tests/FileSystemFileHandle-move.js
• Implementation bugs are filed:
  • Chromium: N/A
  • Gecko: … (Needs to move the existing methods from FileSystemHandle to FileSystemFileHandle)
  • WebKit: … (Needs to move the existing method from FileSystemHandle to FileSystemFileHandle, and add the other two overload signatures)
• MDN issue is filed: …
• The top of this comment includes a clear commit message to use.

---

💥 Error: 422 Unprocessable Entity 💥

PR Preview failed to build. (Last tried on Jul 27, 2026, 11:49 AM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Spec Generator - Spec Generator is the web service used to build bikeshed/ReSpec specs

🔗 Related URL

Error output:

[
    {
        "lineNum": "113",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "247",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "358",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "767",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "793",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "811",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "890",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "984",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "1125",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "1206",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "1277",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": "1713",
        "messageType": "fatal",
        "text": "Saw numeric issue markup, but can't find either a GitHub repo or manual Issue Tracker Template to format it."
    },
    {
        "lineNum": null,
        "messageType": "failure",
        "text": "Did not generate, due to errors exceeding the allowed error level."
    }
]

This seems to be an issue with the Spec Generator service. PR Preview doesn't manage this service and so has no control over it. If you've identified an issue with it, you can report the issue to the maintainers of Spec Generator directly. Please be courteous. Thank you!

If you don't have enough information above to solve the error by yourself or if the issue doesn't seem related to Spec Generator, you can file an issue with PR Preview.

[annevk]

Thank you for tackling this! I hope @a-sully can review this. I left a couple of editorial nits.

[annevk]

We don't list the types here. This should maybe also use <p> as in the output all these algorithms look squished together.

[valadaptive]

Removed the types from the algorithm headers (hopefully I didn't miss any).

I chose not to use <p> since it currently only appears twice in the entire document, at the footer. If we want to use <p> in more places for clarity, I think it's better to do that consistently as a separate change than to introduce it here.

[annevk]

Initialize this variable in the outer scope once for clarity as you need it later. And then overwrite it for this non-null case. We usually keep "null" without markup btw, not null, just null.

[valadaptive]

Initialized it to "not taken", overwriting it inside the conditional.

I also changed all the uses of null in the new section to plain "null". There are some other pre-existing areas that use null; maybe another editorial change for later.

[saschanaz]

We in Mozilla found that the API form is easy to fire a footgun, see: whatwg/webidl#1604

[valadaptive]

@saschanaz My phrasing in the initial writeup was a bit unclear. All three major browsers currently ship the move method on file handles already; Chromium simply doesn't ship it on directory handles. Chromium's IDL is a bit misleading; the move method is marked "experimental" on FileSystemHandle, but their FileSystemFileHandle IDL has its own non-experimental move method.

Un-shipping the move method therefore seems untenable for any major browser at this point, especially since I (and presumably other developers as well) have been using it to rename and move files. Removing the only way to rename a file, an extremely basic and useful operation in basically every filesystem API under the sun, would be very unfortunate.

[saschanaz]

We found the usage of move is very very low at 0.00003%, I think that's an ok level to try renaming it. (I'm not saying we should remove the feature.)

Blink's telemetry names also say "rename" and "reparent" so the current overloading is unfortunate.

[saschanaz]

BTW, Blink just landed move support for directory handles, should we go back to #10 ?