Document behavior of create_dir_all wrt. empty path

[tbu-]

The behavior makes sense because Path::new("one_component").parent() == Some(Path::new("")), so if one naively wants to create the parent directory for a file to be written, it simply works.

Closes #105108 by documenting the current behavior.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Mark-Simulacrum]

r? dtolnay - technically a new stable guarantee, I think? So probably needs libs-api FCP.

[dtolnay]

@rust-lang/libs-api:
@rfcbot fcp merge

fs::create_dir_all("") does not try to create the current directory, even if the current directory does not exist. Is this the intended behavior? Can it be documented?

fn main() {
    let tempdir = tempfile::tempdir().unwrap();
    let repro = tempdir.path().join("repro");
    std::fs::create_dir(&repro).unwrap();
    std::env::set_current_dir(&repro).unwrap();
    std::fs::remove_dir(&repro).unwrap();
    std::fs::write(&repro, "").unwrap();
    std::fs::create_dir_all(&repro).unwrap_err(); // FAIL
    std::fs::create_dir_all("").unwrap(); // ok
}

https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=39a021f969f8b24a38bd729535041664

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[dtolnay]

Our previous empty paths topic: #114149. In that case we decided not to regard the empty path as current dir for read_dir.

[dtolnay]

Interestingly fs::create_dir_all(".") does not try to create the current dir either, and fs::create_dir_all("./x") fails with "No such file or directory" if the current dir does not exist.

[tbu-]

Our previous empty paths topic: #114149. In that case we decided not to regard the empty path as current dir for read_dir.

I'd add that this case is a bit different, because create_dir_all creates all the directories present in the given parameter. The empty string contains no directories to be created, so it can immediately return. This is different from e.g. create_dir which creates exactly one directory.

[tbu-]

Interestingly fs::create_dir_all(".") does not try to create the current dir either, and fs::create_dir_all("./x") fails with "No such file or directory" if the current dir does not exist.

On Linux, mkdir . also seems to fail even when the current directory was unlinked:

$ mkdir .
mkdir: cannot create directory ‘.’: File exists

[BurntSushi]

I think the wording here is a little vague. It says that it always "succeeds," but doesn't say what "succeeds" means. Can we elaborate on what success means for this case?

[tbu-]

I think the wording here is a little vague. It says that it always "succeeds," but doesn't say what "succeeds" means. Can we elaborate on what success means for this case?

Done.