{"id":18474184,"url":"https://github.com/usmanhalalit/gost","last_synced_at":"2025-10-05T12:24:39.763Z","repository":{"id":141626272,"uuid":"136718996","full_name":"usmanhalalit/gost","owner":"usmanhalalit","description":"Filesystem Abstraction Layer for Go, supports S3, Local filesystem \u0026 your own","archived":false,"fork":false,"pushed_at":"2020-10-29T09:56:53.000Z","size":77,"stargazers_count":74,"open_issues_count":1,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-08T12:47:06.638Z","etag":null,"topics":["aws","filesystem","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","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/usmanhalalit.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"usmanhalalit"}},"created_at":"2018-06-09T11:51:49.000Z","updated_at":"2024-08-28T07:43:22.000Z","dependencies_parsed_at":"2023-07-05T06:16:07.986Z","dependency_job_id":null,"html_url":"https://github.com/usmanhalalit/gost","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/usmanhalalit/gost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmanhalalit%2Fgost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmanhalalit%2Fgost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmanhalalit%2Fgost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmanhalalit%2Fgost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usmanhalalit","download_url":"https://codeload.github.com/usmanhalalit/gost/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usmanhalalit%2Fgost/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260672629,"owners_count":23044831,"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":["aws","filesystem","golang"],"created_at":"2024-11-06T10:28:25.466Z","updated_at":"2025-10-05T12:24:39.650Z","avatar_url":"https://github.com/usmanhalalit.png","language":"Go","funding_links":["https://github.com/sponsors/usmanhalalit"],"categories":[],"sub_categories":[],"readme":"# Gost\n\n[![Build Status](https://travis-ci.org/usmanhalalit/gost.svg?branch=master)](https://travis-ci.org/usmanhalalit/gost)\n[![Coverage Status](https://coveralls.io/repos/github/usmanhalalit/gost/badge.svg?branch=master)](https://coveralls.io/github/usmanhalalit/gost?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/usmanhalalit/gost)](https://goreportcard.com/report/github.com/usmanhalalit/gost)\n\nFilesystem abstraction layer for Golang, that works with Local filesystem \nand Amazon S3 with a unified API. You can even copy-paste files from different sources.\nFTP, Dropbox etc. will follow soon.\n\n\n#### Quick Example\n\n```go\nimport \"github.com/usmanhalalit/gost/s3\"\n\n// Initialize a filesystem\nfs, err := s3.New(s3.Config{ your-aws-credentials })\n\n// Read\nnote, err := fs.File(\"my-note.txt\").ReadString()\n//Write\nerr := fs.File(\"another-note.txt\").WriteString(\"another note\")\n\n// Traverse naturally\nmovies := fs.Directory(\"movies\")\nfiles := movies.Files()\nmovies.File(\"Pirated-movie.mp4\").Delete()\n\n// Copy file from one source to another\nlocalFile := lfs.File(\"photo.jpg\")\ns3Dir := fs.Directory(\"photos\")\nerr := localFile.CopyTo(s3dir)\n```\n\n\n## Initialize\n\nGet the library:\n```\ngo get github.com/usmanhalalit/gost\n``` \n\nYou just initialize the S3 and Local adapters differently, **everything else in the API is same**.\n\n#### Amazon S3\n\n```\nimport \"github.com/usmanhalalit/gost/s3\"\n\nfs, err := s3.New(s3.Config{\n\tID: \"aws-id\",\n\tKey: \"aws-key\",\n\tRegion: \"es-west-1\",\n\tBucket: \"your-bucket\",\n})\n```\n\n#### Local\n```go\nimport \"github.com/usmanhalalit/gost/local\"\n\nfs, err := local.New(local.Config{\n\tBasePath: \"/home/user\",\n})\n```\n\n## Read and Write\n\n#### Read\nSimple read, suitable for small files.\n\n```go\nfileContent, err := fs.File(\"test.txt\").ReadString()\n```\n\nBytes read, compatible with `io.Reader`, so you can do buffered read.\n```go\nb := make([]byte, 3)\nn, err := fs.File(\"test.txt\").Read(b)\n```\n\n#### Write\nSimple write\n```go\nfs.File(\"test.txt\").WriteString(\"sample content\")\n```\n\nBytes write\n```go\nn, err := file.Write(bytes)\n// n == number of bytes written\n```\n\n## Traversing\n\nYou can explore the filesystem like you in your desktop file explorer.\nFile and directories are chained in a natural way. \n\n```go\ndirs, err := fs.Directory(\"Parent\").Directory(\"Child\").Directories()\nfiles, err := fs.Directory(\"Parent\").Directory(\"Child\").Files()\n```\n\n```go\ndirs, err := fs.Directory(\"Parent\").Directory(\"Child\").Files()\n```\n\n## Listing\n\nGet all files and loop through them\n```go\nfiles, err := fs.Files()\nfor _, file := range files {\n    fmt.Println(file.ReadString())\n}\n```\n\nGet all directories and loop through them\n```go\ndirs, err := fs.Directories()\nfor _, dir := range dirs {\n    files := dir.Files()\n    fmt.Println(files)\n}\n```\n\nGet the directory which contains a file\n```go\ndir := fs.File(\"test.txt\").Directory()\n```\n\n## Stat\n\nGet file size and last modified timestamp:\n\n```go\nstat, _ := fs.File(\"test.txt\").Stat()\nfmt.Println(stat.Size)\nfmt.Println(stat.LastModified)\n```\n\nYou can get stat of directories too, but it's not available on S3.\n\n```go\nfs.Directory(\"Downloads\").File(\"test.txt\").GetPath()\n```\n\n\n## Create and Delete\nDelete a file and directory:\n```go\nfs.File(\"test.txt\").Delete()\n// Delete an entire directory, beware please!\nfs.Directory(\"Images\").Delete()\n```\n\nCreate a new directory:\n```go\nfs.Directory(\"Images\").Create()\n```\n\nTo create a new file simply write something to it:\n```go\nfs.File(\"non_existent_file\").WriteString(\"\")\n```  \n\n## Copy and Paste Between Different Sources\n\nYou can copy a file to any Directory, be it in in the same filesystem or not(local or S3)\n\n```go\nlocalFile := lfs.File(\"photo.jpg\")\ns3Dir := s3fs.Directory(\"photos\")\nerr := localFile.CopyTo(s3dir)\n``` \n\nFun, eh? \n\nYou can optionally provide a new filename too:\n```go\nerr := localFile.CopyTo(anotherDir, \"copied_file.jpg\")\n```\n\nAlso there is a helper to copy file in the same Directory:\n```go\nfile.Copy(\"copied_file.jpg\")\n``` \n \n\n## Custom Adapter\n\nYes, you can write one and it'll be appreciated if you contribute back.\n. `gost.go` file has all the interfaces defined. Basically you've to implement\n`gost.File` and `gost.Directory` interfaces. Check the `local` adapter to get an idea.\n\n## API Documentation\n\nPlease follow the Go Doc: [https://godoc.org/github.com/usmanhalalit/gost](https://godoc.org/github.com/usmanhalalit/gost)\n\nAlso check the `_test` files [here](https://github.com/usmanhalalit/gost/tree/master/local) to get more idea about the usage.\n\n\n___\nYou can follow me on [Twitter](https://twitter.com/halalit_usman) 🙂\n\n\n\u0026copy; [Muhammad Usman](http://usman.it/). Licensed under MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusmanhalalit%2Fgost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusmanhalalit%2Fgost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusmanhalalit%2Fgost/lists"}