- 
                Notifications
    You must be signed in to change notification settings 
- Fork 13.9k
          std: Stabilize the fs module
          #23081
        
          New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
  
    std: Stabilize the fs module
  
  #23081
              
            Conversation
| r? @huonw (rust_highfive has picked a reviewer for you, use r? to override) | 
| r? @aturon | 
| @alexcrichton Would you mind putting the remarks about bits you're keeping as unstable in the stability reason itself? That helps us keep track of what needs to be resolved before stabilization. | 
        
          
                src/libstd/fs/mod.rs
              
                Outdated
          
        
      There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you add in the reason that you have in the commit message here?
| OK, I've left a few nits, but otherwise r=me. | 
57571e3    to
    3684a98      
    Compare
  
    | @bors: r=aturon 3684a98 | 
This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.
The following apis are now marked `#[stable]`:
* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`
The following apis remain `#[unstable]`.
* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket "set all permissions" method.
  This function remains behind the `fs` feature.
The following apis are now `#[deprecated]`
* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.
[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir
The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].
[rfc-issue]: rust-lang/rfcs#939
[breaking-change]
    3684a98    to
    73b0b25      
    Compare
  
     This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.
The following apis are now marked `#[stable]`:
* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`
The following apis remain `#[unstable]`.
* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket \"set all permissions\" method.
  This function remains behind the `fs` feature.
The following apis are now `#[deprecated]`
* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.
[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir
The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].
[rfc-issue]: rust-lang/rfcs#939
Closes rust-lang#22879
[breaking-change]
    | good thing I saw this, now I know that tempdir is a separate crate. sounds good to me :D | 
This commit performs a stabilization pass over the
std::fsmodule now thatit's had some time to bake. The change was largely just adding
#[stable]tags,but there are a few APIs that remain
#[unstable].The following apis are now marked
#[stable]:std::fs(the name)FileMetadataReadDirDirEntryOpenOptionsPermissionsFile::{open, create}File::{sync_all, sync_data}File::set_lenFile::metadataFileand&FileOpenOptions::newOpenOptions::{read, write, append, truncate, create}OpenOptions::open- this function was modified, however, to not attempt toreject cross-platform openings of directories. This means that some platforms
will succeed in opening a directory and others will fail.
Metadata::{is_dir, is_file, len, permissions}Permissions::{readonly, set_readonly}Iterator for ReadDirDirEntry::pathremove_file- like withOpenOptions::open, the extra windows code toremove a readonly file has been removed. This means that removing a readonly
file will succeed on some platforms but fail on others.
metadatarenamecopyhard_linksoft_linkread_linkcreate_dircreate_dir_allremove_dirremove_dir_allread_dirThe following apis remain
#[unstable].WalkDirandwalk- there are many methods by which a directory walk can beconstructed, and it's unclear whether the current semantics are the right
ones. For example symlinks are not handled super well currently. This is now
behind a new
fs_walkfeature.File::path- this is an extra abstraction which the standard libraryprovides on top of what the system offers and it's unclear whether we should
be doing so. This is now behind a new
file_pathfeature.Metadata::{accessed, modified}- we do not currently have a goodabstraction for a moment in time which is what these APIs should likely be
returning, so these remain
#[unstable]for now. These are now behind a newfs_timefeatureset_file_times- like withMetadata::accessed, we do not currently havethe appropriate abstraction for the arguments here so this API remains
unstable behind the
fs_timefeature gate.PathExt- the precise set of methods on this trait may change over time andsome methods may be removed. This API remains unstable behind the
path_extfeature gate.
set_permissions- we may wish to expose a more granular ability to set thepermissions on a file instead of just a blanket "set all permissions" method.
This function remains behind the
fsfeature.The following apis are now
#[deprecated]TempDirtype is now entirely deprecated and is located oncrates.io as the
tempdircrate with its source atrust-lang/tempdir.
The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked
#[stable]. Thestd::fsmodule has a lot of room to grow and thematerial is being tracked in a RFC issue.
Closes #22879
[breaking-change]