{"id":13724058,"url":"https://github.com/benbjohnson/genesis","last_synced_at":"2025-04-09T19:20:38.907Z","repository":{"id":57491689,"uuid":"125231683","full_name":"benbjohnson/genesis","owner":"benbjohnson","description":"A simple tool for embedding assets in a Go binary.","archived":false,"fork":false,"pushed_at":"2018-10-05T22:04:00.000Z","size":57,"stargazers_count":298,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T13:01:51.944Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/benbjohnson.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}},"created_at":"2018-03-14T15:10:42.000Z","updated_at":"2025-02-07T12:44:05.000Z","dependencies_parsed_at":"2022-08-31T01:50:58.635Z","dependency_job_id":null,"html_url":"https://github.com/benbjohnson/genesis","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbjohnson%2Fgenesis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbjohnson%2Fgenesis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbjohnson%2Fgenesis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benbjohnson%2Fgenesis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benbjohnson","download_url":"https://codeload.github.com/benbjohnson/genesis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094991,"owners_count":21046770,"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":[],"created_at":"2024-08-03T01:01:49.375Z","updated_at":"2025-04-09T19:20:38.887Z","avatar_url":"https://github.com/benbjohnson.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"genesis [![Go Report Card](https://goreportcard.com/badge/github.com/benbjohnson/genesis)](https://goreportcard.com/report/github.com/benbjohnson/genesis) [![](https://godoc.org/github.com/benbjohnson/genesis?status.svg)](http://godoc.org/github.com/benbjohnson/genesis)\n=======\n\nGenesis is a utility for embedding static file assets into Go files to be\nincluded in static compilation. Genesis includes support for `http.FileSystem`\nas well versioning via SHA256 hashes.\n\n\n## Installation\n\nTo install `genesis`, first install [Go](https://golang.org/) and then run:\n\n```sh\n$ go get -u github.com/benbjohnson/genesis/...\n```\n\nYou should now have a `genesis` binary in your `$GOPATH/bin` directory.\n\n\n## Usage\n\n### Command line usage\n\nThe `genesis` command includes a few basic options available from the CLI:\n\n```\nusage: genesis [options] path [paths]\n\nEmbeds listed assets in a Go file as hex-encoded strings.\n\nThe following flags are available:\n\n\t-pkg name\n\t\tPackage name of the generated Go file. Required.\n\n\t-o output\n\t\tOutput filename for generated code. Optional.\n\t\t(default stdout)\n\n\t-C dir\n\t\tExecute genesis from dir. Optional.\n\n\t-tags tags\n\t\tComma-delimited list of build tags. Optional.\n\n```\n\nYou can generate a new Go file with your embedded assets by specifying the\npackage name and the list of files or directories you want to include. By\ndefault the output will go to `STDOUT` so you can redirect to the file of your\nchoice.\n\n```sh\n$ genesis -pkg mypkg file1 file2 dir1 \u003e assets.gen.go\n```\n\n\n#### Specifying the output file\n\nYou can also specify the output file using the `-o` flag. This is useful if you\nare running via `//go:generate` and file redirection is not available:\n\n```sh\n$ genesis -pkg mypkg -o assets.gen.go file1 file2 dir1\n```\n\n\n#### Working directory\n\nOne common approach to asset organization is to create a separate `assets`\npackage that includes your asset files and your generated embedded file. You\ncan use the `-C` flag to change the present working directory to this package\nand then execute relative to this directory:\n\n```sh\n$ genesis -C assets -pkg mypkg -o assets.gen.go file1 file2\n```\n\n\n#### Including build tags\n\nFinally, you can optionally include build tags to optionally include assets\nin your final build. Tags should be comma separated for each individual build\ntag line:\n\n```\n$ genesis -pkg mypkg -o assets.386.gen.go -tags \"linux darwin,386\" file1 file2 dir1\n```\n\nThis will output the following build tag comments at the top of the file:\n\n```go\n// +build linux darwin\n// +build 386\n```\n\n\n### HTTP File System\n\nYour generated embedded assets Go file will include an implementation of\n[`http.FileSystem`](https://golang.org/pkg/net/http/#FileSystem) that can be\npassed to [`http.FileServer`](https://golang.org/pkg/net/http/#FileServer) to automatically serve your embedded assets\nthrough an [`http.Handler`](https://golang.org/pkg/net/http/#Handler):\n\n```go\nhttp.Handle(\"/\", http.FileServer(assets.FileSystem()))\n```\n\n#### Cache control\n\nYour embedded assets Go file also includes a method for returning the filename\nwith an included SHA256 hash. This hash will change whenever the contents of the\nfile changes so the `http.FileSystem` will tell the browser to cache the file\nindefinitely using the `Cache-Control` header.\n\nTo use this feature, simply use the `AssetNameWithHash()` function when writing\nyour URLs that reference embedded assets:\n\n\n```go\nfmt.Fprintf(w, `\u003cscript src=\"%s\"\u003e\u003c/script\u003e`, assets.AssetNameWithHash(\"bundle.js\"))\n```\n\nThis will output something like the following:\n\n```html\n\u003cscript src=\"/bundle-c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.js\"\u003e\u003c/script\u003e\n```\n\nWhen a file is requested with a SHA256 hash it will be cached indefinitely which\nleads to improved web site latency on return visits.\n\n\n### Programmatic API\n\nThe generated embedded assets Go file includes several types and utility\nfunctions. You can view this information via the `godoc` for your package.\nA list of some of these types and functions are included below.\n\n\n#### `File`\n\nOne `File` is generated for every asset you embed. This struct provides the\nname, content hash, size, last modification time, and raw data.\n\n```go\ntype File struct {}\n\nfunc (f *File) Name() string\nfunc (f *File) Hash() string\nfunc (f *File) ModTime() time.Time\nfunc (f *File) Data() []byte\n```\n\n\n\n#### Asset functions\n\nSeveral utility functions are provided for accessing asset information. The\n`Asset()` function simply returns the underlying asset data while `AssetFile()`\nreturns the entire `File` object. To retrieve a sorted list of all asset names,\nuse the `AssetNames()` function.\n\n```go\nfunc Asset(name string) []byte\nfunc AssetFile(name string) *File\nfunc AssetNames() []string\n```\n\n\n#### Content hash functions\n\nThe `AssetNameWithHash()` function will return a given asset name with its SHA256\ncontent hash included. This is useful for embedding in HTML source names when\ncombining with the included `http.FileSystem` implementation.\n\n```go\nfunc AssetNameWithHash(name string) string\n```\n\nThere are also utility functions for working with asset names and hashes. The\n`JoinNameHash()` function will build an asset name hash with the given name\nand hash. The `SplitNameHash()` function will return the base asset name and\nan asset name hash. The `HasNameHash()` returns true if a given name\nincludes an asset hash.\n\n```go\nfunc JoinNameHash(name, hash string) string\nfunc SplitNameHash(name string) string \nfunc HasNameHash(name string) bool\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenbjohnson%2Fgenesis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenbjohnson%2Fgenesis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenbjohnson%2Fgenesis/lists"}