{"id":13595201,"url":"https://github.com/camino-rs/camino","last_synced_at":"2026-04-06T03:36:30.448Z","repository":{"id":40417508,"uuid":"277852028","full_name":"camino-rs/camino","owner":"camino-rs","description":"Like Rust's std::path::Path, but UTF-8.","archived":false,"fork":false,"pushed_at":"2025-02-28T10:47:43.000Z","size":7063,"stargazers_count":475,"open_issues_count":5,"forks_count":20,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T18:04:16.930Z","etag":null,"topics":["paths","rust","unicode"],"latest_commit_sha":null,"homepage":"https://docs.rs/camino","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/camino-rs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sunshowers"}},"created_at":"2020-07-07T15:19:20.000Z","updated_at":"2025-03-31T07:01:32.000Z","dependencies_parsed_at":"2023-02-15T14:30:56.686Z","dependency_job_id":"ffdb5a9b-09fc-4b47-b1a7-b72a849866d6","html_url":"https://github.com/camino-rs/camino","commit_stats":{"total_commits":145,"total_committers":6,"mean_commits":"24.166666666666668","dds":0.1103448275862069,"last_synced_commit":"8bec62382e1bce1326ee48f6bf93c46e7a4fde0b"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camino-rs%2Fcamino","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camino-rs%2Fcamino/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camino-rs%2Fcamino/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camino-rs%2Fcamino/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/camino-rs","download_url":"https://codeload.github.com/camino-rs/camino/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248020593,"owners_count":21034459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["paths","rust","unicode"],"created_at":"2024-08-01T16:01:45.610Z","updated_at":"2026-04-06T03:36:30.441Z","avatar_url":"https://github.com/camino-rs.png","language":"Rust","funding_links":["https://github.com/sponsors/sunshowers"],"categories":["Rust","Libraries"],"sub_categories":["Filesystem","Rust libraries"],"readme":"# camino - UTF-8 paths\n\n[![camino on crates.io](https://img.shields.io/crates/v/camino)](https://crates.io/crates/camino)\n[![crates.io download count](https://img.shields.io/crates/d/camino)](https://crates.io/crates/camino)\n[![Documentation (latest release)](https://img.shields.io/badge/docs-latest%20version-brightgreen.svg)](https://docs.rs/camino)\n[![Documentation (main)](https://img.shields.io/badge/docs-main-purple.svg)](https://camino-rs.github.io/camino/rustdoc/camino/)\n[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE-APACHE)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE-MIT)\n\nThis repository contains the source code for `camino`, an extension of the `std::path` module that adds new\n[`Utf8PathBuf`] and [`Utf8Path`] types.\n\n## What is camino?\n\n`camino`'s [`Utf8PathBuf`] and [`Utf8Path`] types are like the standard library's [`PathBuf`] and [`Path`] types, except\nthey are guaranteed to only contain UTF-8 encoded data. Therefore, they expose the ability to get their\ncontents as strings, they implement `Display`, etc.\n\nThe `std::path` types are not guaranteed to be valid UTF-8. This is the right decision for the standard library,\nsince it must be as general as possible. However, on all platforms, non-Unicode paths are vanishingly uncommon for a\nnumber of reasons:\n\n- Unicode is now the dominant encoding for file names. There are still some legacy codebases that store paths in encodings like [Shift JIS], but most have been converted to Unicode at this point.\n- Unicode is the common subset of supported paths across Windows and Unix platforms. (On Windows, Rust stores paths\n  as [an extension to UTF-8](https://simonsapin.github.io/wtf-8/), and converts them to UTF-16 at Win32\n  API boundaries.)\n- There are already many systems, such as Cargo, that only support UTF-8 paths. If your own tool interacts with any such\n  system, you can assume that paths are valid UTF-8 without creating any additional burdens on consumers.\n- The [\"makefile problem\"](https://www.mercurial-scm.org/wiki/EncodingStrategy#The_.22makefile_problem.22) asks: given a\n  Makefile or other metadata file (such as `Cargo.toml`) that lists the names of other files, how should the names in\n  the Makefile be matched with the ones on disk? This has _no general, cross-platform solution_ in systems that support\n  non-UTF-8 paths. However, restricting paths to UTF-8 eliminates this problem.\n\n[Shift JIS]: https://en.wikipedia.org/wiki/Shift_JIS\n\nTherefore, many programs that want to manipulate paths _do_ assume they contain UTF-8 data, and convert them to `str`s\nas necessary. However, because this invariant is not encoded in the `Path` type, conversions such as\n`path.to_str().unwrap()` need to be repeated again and again, creating a frustrating experience.\n\nInstead, `camino` allows you to check that your paths are UTF-8 _once_, and then manipulate them\nas valid UTF-8 from there on, avoiding repeated lossy and confusing conversions.\n\n## Examples\n\nThe documentation for [`Utf8PathBuf`] and [`Utf8Path`] contains several examples.\n\nFor examples of how to use `camino` with other libraries like `serde` and `clap`, see the [`camino-examples`] directory.\n\n## API design\n\n`camino` is a very thin wrapper around `std::path`. [`Utf8Path`] and [`Utf8PathBuf`] are drop-in replacements\nfor [`Path`] and [`PathBuf`].\n\nMost APIs are the same, but those at the boundary with `str` are different. Some examples:\n\n- `Path::to_str() -\u003e Option\u003c\u0026str\u003e` has been renamed to `Utf8Path::as_str() -\u003e \u0026str`.\n- [`Utf8Path`] implements `Display`, and `Path::display()` has been removed.\n- Iterating over a [`Utf8Path`] returns `\u0026str`, not `\u0026OsStr`.\n\nEvery [`Utf8Path`] is a valid [`Path`], so [`Utf8Path`] implements `AsRef\u003cPath\u003e`. Any APIs that accept `impl AsRef\u003cPath\u003e`\nwill continue to work with [`Utf8Path`] instances.\n\n## Should you use camino?\n\n`camino` trades off some utility for a great deal of simplicity. Whether `camino` is appropriate for a project or not\nis ultimately a case-by-case decision. Here are some general guidelines that may help.\n\n_You should consider using camino if..._\n\n- **You're building portable, cross-platform software.** While both Unix and Windows platforms support different kinds\n  of non-Unicode paths, Unicode is the common subset that's supported across them.\n- **Your system has files that contain the names of other files.** If you don't use UTF-8 paths, you will run into the\n  makefile problem described above, which has no general, cross-platform solution.\n- **You're interacting with existing systems that already assume UTF-8 paths.** In that case you won't be adding any new\n  burdens on downstream consumers.\n- **You're building something brand new and are willing to ask your users to rename their paths if necessary.** Projects\n  that don't have to worry about legacy compatibility have more flexibility in choosing what paths they support.\n\nIn general, using camino is the right choice for most projects.\n\n_You should **NOT** use camino, if..._\n\n- **You're writing a core system utility.** If you're writing, say, an `mv` or `cat` replacement, you should\n  **not** use camino. Instead, use [`std::path::Path`] and add extensive tests for non-UTF-8 paths.\n- **You have legacy compatibility constraints.** For example, Git supports non-UTF-8 paths. If your tool needs to handle\n  arbitrary Git repositories, it should use its own path type that's a wrapper around `Vec\u003cu8\u003e`.\n  - [`std::path::Path`] supports arbitrary bytestrings [on Unix] but not on Windows.\n- **There's some other reason you need to support non-UTF-8 paths.** Some tools like disk recovery utilities need to\n  handle potentially corrupt filenames: only being able to handle UTF-8 paths would greatly diminish their utility.\n\n[on Unix]: https://doc.rust-lang.org/std/os/unix/ffi/index.html\n\n## Optional features\n\nBy default, `camino` has **no dependencies** other than `std`. There are some optional features that enable\ndependencies:\n\n- `serde1` adds serde [`Serialize`] and [`Deserialize`] impls for [`Utf8PathBuf`] and [`Utf8Path`]\n  (zero-copy).\n- `proptest1` adds [proptest](https://altsysrq.github.io/proptest-book/) [`Arbitrary`]\n  implementations for [`Utf8PathBuf`] and `Box\u003cUtf8Path\u003e`.\n\n## Rust version support\n\nThe minimum supported Rust version (MSRV) for `camino` with default features is **1.61**. This project is tested in CI\nagainst the latest stable version of Rust and the MSRV.\n\n- _Stable APIs_ added in later Rust versions are supported either through conditional compilation in `build.rs`, or through backfills that also work on older versions.\n- _Deprecations_ are kept in sync with the version of Rust they're added in.\n- _Unstable APIs_ are currently not supported. Please\n  [file an issue on GitHub](https://github.com/camino-rs/camino/issues/new) if you need an unstable API.\n\n`camino` is designed to be a core library and has a conservative MSRV policy. MSRV increases will only happen for\na compelling enough reason, and will involve at least a minor version bump.\n\nOptional features may pull in dependencies that require a newer version of Rust.\n\n## License\n\nThis project is available under the terms of either the [Apache 2.0 license](LICENSE-APACHE) or the [MIT\nlicense](LICENSE-MIT).\n\nThis project's documentation is adapted from [The Rust Programming Language](https://github.com/rust-lang/rust/), which is\navailable under the terms of either the [Apache 2.0 license](https://github.com/rust-lang/rust/blob/master/LICENSE-APACHE)\nor the [MIT license](https://github.com/rust-lang/rust/blob/master/LICENSE-MIT).\n\n[`Utf8PathBuf`]: https://docs.rs/camino/*/camino/struct.Utf8PathBuf.html\n[`Utf8Path`]: https://docs.rs/camino/*/camino/struct.Utf8Path.html\n[`PathBuf`]: https://doc.rust-lang.org/std/path/struct.PathBuf.html\n[`Path`]: https://doc.rust-lang.org/std/path/struct.Path.html\n[`std::path::Path`]: https://doc.rust-lang.org/std/path/struct.Path.html\n[`Serialize`]: https://docs.rs/serde/1/serde/trait.Serialize.html\n[`Deserialize`]: https://docs.rs/serde/1/serde/trait.Deserialize.html\n[`camino-examples`]: https://github.com/camino-rs/camino/tree/main/camino-examples\n[`Arbitrary`]: https://docs.rs/proptest/1/proptest/arbitrary/trait.Arbitrary.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamino-rs%2Fcamino","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcamino-rs%2Fcamino","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamino-rs%2Fcamino/lists"}