{"id":15048249,"url":"https://github.com/github/libprojfs","last_synced_at":"2025-10-04T08:31:06.442Z","repository":{"id":65974856,"uuid":"165317757","full_name":"github/libprojfs","owner":"github","description":"Linux projected filesystem library","archived":true,"fork":false,"pushed_at":"2023-06-18T15:48:17.000Z","size":899,"stargazers_count":92,"open_issues_count":6,"forks_count":14,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-09-25T21:09:37.510Z","etag":null,"topics":["filesystems","fuse-filesystem","git","vfsforgit"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-01-11T22:10:57.000Z","updated_at":"2024-07-31T03:14:18.000Z","dependencies_parsed_at":"2023-02-19T18:15:25.501Z","dependency_job_id":null,"html_url":"https://github.com/github/libprojfs","commit_stats":{"total_commits":381,"total_committers":5,"mean_commits":76.2,"dds":0.4409448818897638,"last_synced_commit":"224e0542820f67175a6532d77aaf8c4a957481a4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Flibprojfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Flibprojfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Flibprojfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Flibprojfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/libprojfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219876581,"owners_count":16554769,"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":["filesystems","fuse-filesystem","git","vfsforgit"],"created_at":"2024-09-24T21:09:49.103Z","updated_at":"2025-10-04T08:31:05.984Z","avatar_url":"https://github.com/github.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libprojfs\n\nA Linux projected filesystem library, similar in concept to the Windows\n[Projected File System][winprojfs] and developed in conjunction with the\n[VFSForGit][vfs4git] project.\n\nWhile the libprojfs C library may also be used independently of VFSForGit,\nour primary goal is to enable users to run the VFSForGit client\non a Linux system.\n\n**PLEASE NOTE:**\nAt present libprojfs is undergoing rapid development and its design\nand APIs may change significantly; some features are also incomplete,\nand so we do not recommend libprojfs for any production environments.\n\nHowever, we wanted to share our progress to date, and we hope others\nare as excited as we are at the prospect of running the VFSForGit\nclient on Linux in the not-too-distant future!\n\n## Current Status\n\n| Branch     | Functional Tests                                          |\n| :--------: | :-------------------------------------------------------: |\n| **master** | [![CI status: master][ci-master-status]][ci-master-redir] |\n\nThe library is under active development and supports basic\ndirectory projection, with additional features added regularly.\n\nWe will only make a first, official versioned release once initial\ndevelopment is complete.\n\nA libprojfs filesystem can currently be used to mount a VFSForGit\n[`MirrorProvider`][vfs4git-mirror] test client; we expect to continue our\npre-release development until the VFSForGit client proper is also\nfunctional with libprojfs, at which point we may make an initial\ntagged release.\n\n## Design\n\nThe libprojfs library is designed to function as a stackable Linux\nfilesystem supporting a \"provider\" process which implements custom\ncallbacks to populate files and directories on demand.  This is\nillustrated in the context of a VFSForGit provider below:\n\n![Illustration of libprojfs in provider context](docs/images/phase1.png)\n\nActual file storage is delegated to a \"lower\" storage filesystem,\nwhich may be any Linux filesystem, e.g., ext4.  At the time\nwhen a libprojfs filesystem mount is created, there may be no\nfiles or directories in the lower filesystem yet.\n\nAs normal filesystem requests are made within the libprojfs mount\n(e.g., by `ls` or `cat`), libprojfs intercepts the requests\nand queries the provider process for the actual contents of the\nfile or directory.  The provider's response is then written to\nthe lower filesystem so future accesses may be satisfied without\nquerying the provider again.\n\nSee our [design document][design-linux] for more details.\n\nWe anticipate that whether libprojfs remains a [FUSE][fuse-man]-based\nlibrary, or becomes a [libfuse][libfuse]-like interface to a Linux kernel\nmodule, it may be useful for purposes other than running a VFSForGit\nclient.\n\nFor this reason, we have tried to ensure that our native\n[event notification API](include/projfs_notify.h)\nis aligned closely with the Linux kernel's\n[fanotify][fanotify]/[inotify][inotify]/[fsnotify][fsnotify] APIs.\n\n## Getting Started\n\nPlease see our detailed [Build and Installation][build]\npage for step-by-step instructions on how to build and install\nlibprojfs and its dependencies on Linux, and (optionally) also build and\nrun the VFSForGit `MirrorProvider` test utility with libprojfs.\n\nSo long as libprojfs remains based on [FUSE][fuse-man], the primary\ndependency for libprojfs is the user-space [libfuse][libfuse] library,\nas well as having the Linux [`fuse`][fuse-mod] kernel module installed.\n\nSupport for [`user.*` extended attributes][xattr] must also be enabled\non the \"lower\" storage filesystem.  Your Linux kernel should have\nbeen compiled with the necessary configuration options (e.g.,\n`CONFIG_EXT2_FS_XATTR` for [ext2/3/4][ext2]) and the underlying filesystem\nyou use for libprojfs should be mounted with appropriate settings\n(e.g., [user_xattr][xattr-ext2] for ext2/3/4).\n\nIf you are using a [Docker](https://www.docker.com) container, you\nmay need to ensure the `fuse` kernel module is installed on your\nhost OS, and `user.*` extended attributes are supported on your host's\nfilesystem.  See the [Using Docker containers][build-docker] section for\nmore details.\n\nTo test libprojfs with the Microsoft VFSForGit `MirrorProvider`\n(as we do not support the primary VFSForGit GVFS provider yet), .NET Core\nmust be installed and parts of the VFSForGit project built.  See the\n[Building and Running MirrorProvider][build-mirror] section for details.\n\n## Contributing\n\nThank you for your interest in libprojfs!\n\nWe welcome contributions; please see our [CONTRIBUTING](CONTRIBUTING.md)\nguidelines and our contributor [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md).\n\n## Licensing\n\nThe libprojfs library is licensed under the [LGPL v2.1](COPYING).\n\nSee the [NOTICE](NOTICE) file for a list of other licenses used in the\nproject, and the comments in each file for the licenses applicable to them.\n\n## Development Roadmap\n\nWe are developing the libprojfs library first, using FUSE to prototype and\ntest its performance, before migrating functionality into a Linux kernel\nmodule (assuming that proves to be necessary to meet our performance\ncriteria).\n\nFor more details on the planned development phases, see our\n[design document][design-process].\n\n## Authors\n\nThe libprojfs library is currently maintained and developed by\nseveral members of GitHub's Engineering organization, including:\n\n* [@chrisd8088](https://github.com/chrisd8088)\n* [@kivikakk](https://github.com/kivikakk)\n* [@wrighty](https://github.com/wrighty)\n\nYou can also contact the GitHub project team at\n[opensource+libprojfs@github.com](mailto:opensource+libprojfs@github.com).\n\n[build]: docs/build-install.md\n[build-docker]: docs/build-install.md#using-docker-containers\n[build-mirror]: docs/build-install.md#building-and-running-mirrorprovider\n[ci-master-redir]: https://dev.azure.com/asconnor/asconnor/_build/latest?definitionId=1\u0026branchName=master\n[ci-master-status]: https://dev.azure.com/asconnor/asconnor/_apis/build/status/github.libprojfs?branchName=master\n[design-linux]: docs/design.md#vfsforgit-on-linux\n[design-process]: docs/design.md#development-process\n[ext2]: https://www.kernel.org/doc/Documentation/filesystems/ext2.txt\n[fanotify]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/fanotify.h\n[fsnotify]: https://github.com/torvalds/linux/blob/master/include/linux/fsnotify_backend.h\n[fuse-man]: http://man7.org/linux/man-pages/man4/fuse.4.html\n[fuse-mod]: https://www.kernel.org/doc/Documentation/filesystems/fuse.txt\n[inotify]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/inotify.h\n[libfuse]: https://github.com/libfuse/libfuse\n[winprojfs]: https://docs.microsoft.com/en-us/windows/desktop/api/_projfs/\n[vfs4git]: https://github.com/Microsoft/VFSForGit\n[vfs4git-mirror]: https://github.com/Microsoft/VFSForGit/tree/features/linuxprototype/MirrorProvider\n[xattr]: http://man7.org/linux/man-pages/man7/xattr.7.html\n[xattr-ext2]: http://man7.org/linux/man-pages/man5/ext4.5.html#MOUNT_OPTIONS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Flibprojfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Flibprojfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Flibprojfs/lists"}