{"id":13562177,"url":"https://github.com/winfsp/hubfs","last_synced_at":"2025-05-16T09:06:17.921Z","repository":{"id":39867950,"uuid":"349221212","full_name":"winfsp/hubfs","owner":"winfsp","description":"File system for GitHub \u0026 GitLab","archived":false,"fork":false,"pushed_at":"2022-05-12T23:44:04.000Z","size":10694,"stargazers_count":1642,"open_issues_count":5,"forks_count":62,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-05T06:31:55.641Z","etag":null,"topics":["filesystem","git","github"],"latest_commit_sha":null,"homepage":"https://winfsp.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/winfsp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-18T21:26:02.000Z","updated_at":"2025-03-12T11:18:44.000Z","dependencies_parsed_at":"2022-07-17T01:46:15.157Z","dependency_job_id":null,"html_url":"https://github.com/winfsp/hubfs","commit_stats":null,"previous_names":["billziss-gh/hubfs"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fhubfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fhubfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fhubfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/winfsp%2Fhubfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/winfsp","download_url":"https://codeload.github.com/winfsp/hubfs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501558,"owners_count":22081528,"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":["filesystem","git","github"],"created_at":"2024-08-01T13:01:05.423Z","updated_at":"2025-05-16T09:06:12.914Z","avatar_url":"https://github.com/winfsp.png","language":"Go","funding_links":[],"categories":["Go","github"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\u003cimg src=\"art/hubfs-glow.png\" width=\"256\"/\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\nHUBFS \u0026middot; File System for GitHub\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/winfsp/hubfs/releases\"\u003e\n\u003cimg src=\"https://img.shields.io/github/release/winfsp/hubfs/all.svg?label=Download\u0026colorB=e52e4b\u0026style=for-the-badge\"/\u003e\n\u003c/a\u003e\n\nHUBFS is a file system for GitHub and Git. Git repositories and their contents are represented as regular directories and files and are accessible by any application, without the application having any knowledge that it is really accessing a remote Git repository. The repositories are writable and allow editing files and running build operations.\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cimg src=\"doc/cap1.gif\" width=\"75%\"/\u003e\n\u003c/p\u003e\n\n## How to use\n\nHUBFS is a command-line program with a usage documented below. On Windows there is also good desktop integration so that you can use HUBFS without the command line.\n\nHUBFS supports both authenticated and non-authenticated access to repositories. When using HUBFS without authentication, only public repositories are available. When using HUBFS with authentication, both public and private repositories become available; an additional benefit is that the rate limiting that GitHub does for certain operations is relaxed.\n\nIn order to mount HUBFS issue the command `hubfs MOUNTPOINT`. For example, `hubfs H:` on Windows or `hubfs mnt` on macOS and Linux.\n\nThe first time you run HUBFS you will be prompted to authorize it with GitHub:\n\n```\n\u003e ./hubfs H:\nFirst, copy your one-time code: XXXX-XXXX\nThen press [Enter] to continue in the web browser...\n```\n\nHUBFS will then open your system browser where you will be able to authorize it with GitHub. HUBFS will store the resulting authorization token in the system keyring (Windows Credential Manager, macOS Keychain, etc.). Subsequent runs of HUBFS will use the authorization token from the system keyring and you will not be required to re-authorize the application.\n\nTo unmount the file system simply use \u003ckbd\u003eCtrl-C\u003c/kbd\u003e. On macOS and Linux you may also be able to unmount using `umount` or `fusermount -u`.\n\n### Full command-line usage\n\nThe full HUBFS command line usage is as follows:\n\n```\nusage: hubfs [options] [remote] mountpoint\n\n  -auth method\n        method is from list below; auth tokens are stored in system keyring\n        - force     perform interactive auth even if token present\n        - full      perform interactive auth if token not present (default)\n        - required  auth token required to be present\n        - optional  auth token will be used if present\n        - none      do not use auth token even if present\n        - token=T   use specified auth token T; do not use system keyring\n  -authkey name\n        name of key that stores auth token in system keyring\n  -authonly\n        perform auth only; do not mount\n  -d    debug output\n  -filter rules\n        list of rules that determine repo availability\n        - list form: rule1,rule2,...\n        - rule form: [+-]owner or [+-]owner/repo\n        - rule is include (+) or exclude (-) (default: include)\n        - rule owner/repo can use wildcards for pattern matching\n  -o options\n        FUSE mount options\n        (default: uid=-1,gid=-1,rellinks,FileInfoTimeout=-1)\n  -version\n        print version information\n```\n\n(The default FUSE mount options depend on the OS. The `uid=-1,gid=-1` option specifies that the owner/group of HUBFS files is determined by the user/group that launches the file system. This works on Windows, Linux and macOS.)\n\n### File system representation\n\nBy default HUBFS presents the following file system hierarchy: / *owner* / *repository* / *ref* / *path*\n\n- *Owner* represents the owner of repositories under GitHub. It may be a user or organization. An *owner* is presented as a subdirectory of the root directory and contains *repositories*. However the root directory cannot be listed, because there are far too many owners to list.\n\n- *Repository* represents a repository owned by an *owner*. A *repository* is presented as a directory that contains *refs*.\n\n- *Ref* represents a git \"ref\". It may be a git branch, a git tag or even a commit hash. A *ref* is presented as a directory that contains repository content. However when listing a *repository* directory only branch *refs* are listed.\n\n- *Path* is a path to actual file content within the repository.\n\nHUBFS interprets submodules as symlinks. These submodules can be followed if they point to other GitHub repositories. General repository symlinks should work as well. (On Windows you must use the FUSE option `rellinks` for this to work correctly.)\n\nWith release 2022 Beta1 HUBFS *ref* directories are now writable. This is implemented as a union file system that overlays a read-write local file system over the read-only Git content. This scheme allows files to be edited and builds to be performed. A special file named `.keep` is created at the *ref* root (full path: / *owner* / *repository* / *ref* / `.keep`). When the edit/build modifications are no longer required the `.keep` file may be deleted and the *ref* root will be garbage collected when not in use (i.e. when no files are open in it -- having a terminal window open with a current directory inside a *ref* root counts as an open file and the *ref* will not be garbage collected).\n\n### Windows integration\n\nWhen you use the MSI installer under Windows there is better integration of HUBFS with the rest of the system:\n\n- There is a \"Start Menu \u003e HUBFS \u003e Perform GitHub auth\" shortcut that allows you to authorize HUBFS with GitHub without using the command line.\n\n- You can mount HUBFS drives using the Windows Explorer \"Map Network Drive\" functionality. To dismount use the \"Disconnect Network Drive\" functionality. (It is recommended to first authorize HUBFS with GitHub using the above mentioned shortcut.)\n\n    \u003cimg src=\"doc/mapnet.png\" width=\"50%\"/\u003e\n\n- You can also mount HUBFS with the `net use` command. The command `net use H: \\\\hubfs\\github.com` will mount HUBFS as drive `H:`. The command `net use H: /delete` will dismount the `H:` drive.\n\n## How to build\n\nIn order to build HUBFS run `build/make`. The build prerequisites for individual platforms are listed below:\n\n- Windows: [Go 1.16](https://golang.org/dl/), [WinFsp](https://github.com/winfsp/winfsp), gcc (e.g. from [Mingw-builds](http://mingw-w64.org/doku.php/download))\n\n- macOS: [Go 1.16](https://golang.org/dl/), [FUSE for macOS](https://osxfuse.github.io), [command line tools](https://developer.apple.com/library/content/technotes/tn2339/_index.html)\n\n- Linux: Prerequisites: [Go 1.16](https://golang.org/dl/), libfuse-dev, gcc\n\n## How it works\n\nHUBFS is a cross-platform file system written in Go. Under the hood it uses [cgofuse](https://github.com/winfsp/cgofuse) over either [WinFsp](https://github.com/winfsp/winfsp) on Windows, [macFUSE](https://osxfuse.github.io/) on macOS or [libfuse](https://github.com/libfuse/libfuse/) on Linux. It also uses [go-git](https://github.com/go-git/go-git) for some git functionality.\n\nHUBFS interfaces with GitHub using the [REST API](https://docs.github.com/en/rest). The REST API is used to discover owners and repositories in the file system hierarchy, but is not used to access repository content. The REST API is rate limited ([details](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting)).\n\nHUBFS uses the git [pack protocol](https://git-scm.com/docs/pack-protocol) to access repository content. This is the same protocol that git uses during operations like `git clone`. HUBFS uses some of the newer capabilities of the pack protocol that allow it to fetch content on demand. HUBFS does not have to see all of the repository history or download all of the repository content. It will only download the commits, trees and blobs necessary to back the directories and files that the user is interested in. Note that the git pack protocol is not rate limited.\n\nHUBFS caches information in memory and on local disk to avoid the need to contact the servers too often.\n\n### Git pack protocol use\n\nHUBFS uses the git pack protocol to fetch repository refs and objects. When HUBFS first connects to the Git server it fetches all of the server's advertised refs. HUBFS exposes these refs as subdirectories of a repository.\n\nWhen accessing the content of a ref for the first time, the commit object pointed by the ref is fetched, then the tree object pointed by the commit is fetched. When fetching a tree HUBFS will also fetch all blobs directly referenced by the tree, this is required to compute proper `stat` data (esp. size) for files.\n\nHUBFS fetches objects with a depth of 1 and a filter of `tree:0`. This ensures that the git server will only send objects whose hashes have been explicitly requested. This avoids sending extraneous information and speeds up communication with the server.\n\n## Security issues\n\n- Consider a program that accesses files under `/COMMON-NAME/DIR`. The owner of the `COMMON-NAME` GitHub account could create a repository named `DIR` and inject arbitrary file content into the program's process. This problem is particularly important when mounting the file system as a drive on Windows. To fix this problem:\n\n    - Run HUBFS with the `-filter` option. For example, running HUBFS with `-filter ORG` will make available the repositories in `ORG` only. Files within the file system will be accessible as / `ORG` / *repository* / *ref* / *path*. (The `-filter` option allows the inclusion/exclusion of multiple repositories and supports wildcard syntax. Please see the HUBFS usage for more.)\n\n\t- Run HUBFS with a \"prefix\". For example, the (Windows) command line `./hubfs github.com/ORG H:` will place the root of the file system within `ORG` and thus make available the repositories in `ORG` only. Files within the file system will be accessible as / *repository* / *ref* / *path*.\n\n## Potential future improvements\n\n- The file system does not present a `.git` subdirectory. It may be worthwhile to present a virtual `.git` directory so that simple Git commands (like `git status`) would work.\n\n- Additional providers such as GitHub Enterprise, BitBucket, GitLab, etc.\n\n## License\n\nThis project is licensed under the [GNU Affero General Public License version 3](License.txt).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinfsp%2Fhubfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwinfsp%2Fhubfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwinfsp%2Fhubfs/lists"}