{"id":20501971,"url":"https://github.com/weyhan/filestuff","last_synced_at":"2026-04-19T11:35:25.681Z","repository":{"id":259052508,"uuid":"875708083","full_name":"weyhan/Filestuff","owner":"weyhan","description":"Filestuff framework: easy management of directories and files listing","archived":false,"fork":false,"pushed_at":"2024-11-07T17:04:04.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-16T07:15:48.681Z","etag":null,"topics":["file-browser","filesystem-library","ios","macos","macos-finder","swift","swift-framework","tvos"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weyhan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-10-20T16:42:10.000Z","updated_at":"2024-11-07T17:04:08.000Z","dependencies_parsed_at":"2024-10-22T03:08:00.038Z","dependency_job_id":null,"html_url":"https://github.com/weyhan/Filestuff","commit_stats":null,"previous_names":["weyhan/filestuff"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weyhan%2FFilestuff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weyhan%2FFilestuff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weyhan%2FFilestuff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weyhan%2FFilestuff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weyhan","download_url":"https://codeload.github.com/weyhan/Filestuff/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234163888,"owners_count":18789409,"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":["file-browser","filesystem-library","ios","macos","macos-finder","swift","swift-framework","tvos"],"created_at":"2024-11-15T19:18:27.477Z","updated_at":"2025-12-05T11:03:05.903Z","avatar_url":"https://github.com/weyhan.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Filestuff\n\nA Swift framework for reading and managing directory trees that is suitable for building a Finder-style file browser interface.\n\n## Overview\n\nA Filestuff object lets you read the contents of a directory along with the metadata for the directory and its contents. To build a Finder-style file browser interface, the `Directory` object could be used directly as your data source for the `UITableView` or `UICollectionView` or, if desired, you can create a wrapper around the `Directory` object to format the data for display or manipulate the data in any way necessary. \n\nIf the directory loader is not extended, the default set of metadata will be loaded upon reading the directory's content. To load metadata not included in the default set, you can add additional metadata to be loaded and extend the `FilestuffContainer` to expose the extra metadata for your consumption.\n\n## Getting Started\n\n### Installation\n\n_Note: There are no plans to support Carthage or CocoaPods package managers._\n\n#### Swift Package\n\n[Swift Package Manager](https://swift.org/package-manager/) is a tool for managing the distribution of Swift code.\n\n##### For Swift Package Project\n\nAfter you set up your Package.swift manifest file in your project, you can add Filestuff as a dependency by adding it to your Package.swift dependencies value.\n\n```\ndependencies: [ .package(url: \"https://github.com/weyhan/Filestuff.git\", from: \"1.0.0\") ]\n```\n\n##### For Xcode Project\n\n1. Using Xcode 11 or above, go to `File` \u003e `Add Package Dependencies…`.\n1. Paste the project URL: `https://github.com/weyhan/Filestuff.git` in the search field.\n1. Select the project target from the search result list if not already selected.\n1. Configure the dependency rules to your preferences.\n1. Click `Add Package` to add Filestuff to your project.\n\n_Note: The `Add Package Dependencies` interface could change from version to version of Xcode._\n\n#### Git Submodule\n\nOn the `Terminal.app`, go to the root folder of the git repository you want to add the Filestuff framework and then add the submodule folder.\n\n```\ngit submodule add https://github.com/weyhan/filestuff.git\ngit submodule init\ngit submodule update\n```\n\nTo add Filestuff to your project, locate the project file `Filestuff.xcodeproj` on Finder and drag it into your project's Xcode Project Navigator pane.\n\n#### Build From Source\n\nOn the `Terminal.app`, type the following command to clone the Filestuff repository and build:\n\n```\ngit clone https://github.com/weyhan/filestuff.git\ncd filestuff\nsource build-xcframework.sh\n```\n\nThe resulting framework file `Filestuff.xcframework` will be placed in the `build` directory.\n\nTo add Filestuff to your project, locate the framework file `Filestuff.xcframework` on Finder and drag it into your project's Xcode Project Navigator pane.\n\n## Usage\n\n#### Importing Filestuff\n\nTo start using Filestuff, import the Filestuff framework in the source file.\n\n```\nimport Filestuff\n```\n\n#### Reading Directory Content\n\nThere are two modes of reading directories.\n\n* Shallow read (default):\n\n```\nlet homeUrl = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.deletingLastPathComponent()\n\ndo {\n\tlet directory = try Directory.load(url: homeUrl)\n} catch {\n\t// Handle error\n}\n```\n\nExample result of shallow read where \"…\" is not read:\n\n```\n.\n├── Documents\n│   └── …\n├── Library\n│   └── …\n├── SystemData\n└── tmp\n```\n\n* Deep read:\n\n```\nlet homeUrl = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.deletingLastPathComponent()\n\ndo {\n\tlet directory = try Directory.load(url: homeUrl, shallow: false)\n} catch {\n\t// Handle error\n}\n```\n\nExample result of deep read where the whole tree is loaded:\n\n```\n.\n├── Documents\n│   ├── mytext.txt\n│   ├── presentation.pdf\n│   └── settings.json\n├── Library\n│   ├── Caches\n│   ├── Preferences\n│   └── Saved Application State\n│       └── com.myapp.savedState\n│           └── KnownSceneSessions\n│               └── data.data\n├── SystemData\n└── tmp\n```\n\nThe deep read will load the whole directory tree with the following exception:\n\n1. Will not follow into Symbolic link to a directory.\n2. Will not descend into bundle or package type directories.\n\n#### Iterating Over the Content of a Directory\n\nPrint all files and directories in the `Directory` container at the specific `URL`.\n\n```\ndirectory.forEach { file in \n\tprint(\"filename: \\(file.name)\")\n}\n```\n\n#### File / Directory Attributes\n\n* url: URL\u003cbr/\u003e The URL value pointing to the file or directory on the filesystem where this `FilestuffContainer` represents.\n\n* attribute: URLResourceValues\u003cbr/\u003eThe file's metadata represented as [`URLResourceValues`](https://developer.apple.com/documentation/foundation/urlresourcevalues)\n\n* size: Int?\u003cbr/\u003eThe file’s size, in bytes.\n\n* type: URLFileResourceType?\u003cbr/\u003eThe filesystem type as [`URLFileResourceType`](https://developer.apple.com/documentation/foundation/urlfileresourcetype).\n\n* created: Date?\u003cbr/\u003eThe file's creation date.\n\n* modified: Date?\u003cbr/\u003eThe file's last modified date.\n\n* name: String\u003cbr/\u003eThe file's name.\n\n* ext: String\u003cbr/\u003eThe file's extension.\n\n* displayName: String\u003cbr/\u003eThe file's name without the file extension.\n\n* path: String\u003cbr/\u003eThe file's path on the filesystem.\n\n* isRegularFile: Bool?\u003cbr/\u003eA `Boolean` value indicating whether the file is a regular file.\n\n* isDirectory: Bool?\u003cbr/\u003eA `Boolean` value indicating whether the file is a directory.\n\n* isSymbolicLink: Bool?\u003cbr/\u003eA `Boolean` value indicating whether the file is a symbolic link.\n\n* contentType: UTType?\u003cbr/\u003eThe resource’s type of the file as [`UTType`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype).\n\n* contentTypeIdentifier: String?\u003cbr/\u003eA `String` value representation of the file's resource type.\n\n\n#### Loading More Attribute\n\nThere are two ways to ask Filestuff to load additional resources from the filesystem when available.\n\n##### Adding resource keys to the whole session\n\nTo load additional attributes while reading directories, add `URLResourceKey` using `addFileResourceKey` convenience method. e.g.:\n\n```\nFilestuffUtils.add(resourceKeys: .totalFileAllocatedSizeKey)\n\n```\n\n_Note: The additional keys will persist in the same session but not across sessions. In other words, the keys once added, will immediately take effect and continue to be in effect until the app quits. Any subsequent read will include the additional keys._\n\n##### Adding resource keys to a one-time load method\n\nTo load additional attributes on a one-time basis, pass the corresponding keys to the `load` convenience method as the optional argument `extraResourceKeys`. e.g.:\n\n```\n\tlet homeUrl = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.deletingLastPathComponent()\n\n\tdo {\n\t\tlet directory = try Directory.load(url: homeUrl, extraResourceKeys: [isAliasFileKey])\n\t} catch {\n\t\t// Handle error\n\t}\n```\n_Note: See below to add access to added extra resource keys_\n\n##### Accessing resource values loaded by adding resource keys\n\nTo access the value of the additional attributes, it is necessary to extend the `FilestuffContainer ` by adding computed properties to retrieve the value. e.g.:\n\n```\n\textension FilestuffContainer {\n\t\tvar totalFileAllocatedSize: Int? { attribute.totalFileAllocatedSize } \n\t}\n```\n\nIt's also possible to extend `FilestuffContainer` by adding functions that accept arguments and manipulate attribute values to suit your needs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweyhan%2Ffilestuff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweyhan%2Ffilestuff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweyhan%2Ffilestuff/lists"}