Recreate folder structures and files from Go 1.16's `embed.FS` type

# rebed
[![codecov](https://codecov.io/gh/soypat/rebed/branch/main/graph/badge.svg)](https://codecov.io/gh/soypat/rebed)
[![Build Status](https://travis-ci.org/soypat/rebed.svg?branch=main)](https://travis-ci.org/soypat/rebed)
[![Go Report Card](https://goreportcard.com/badge/github.com/soypat/rebed)](https://goreportcard.com/report/github.com/soypat/rebed)
[![go.dev reference](https://pkg.go.dev/badge/github.com/soypat/rebed)](https://pkg.go.dev/github.com/soypat/rebed)
[![Awesome](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go/blob/master/README.md#resource-embedding)
[![Sourcegraph](https://sourcegraph.com/github.com/soypat/rebed/-/badge.svg)](https://sourcegraph.com/github.com/soypat/rebed?badge)

Recreate embedded filesystems from embed.FS type in current working directory. 

Expose the files you've embedded in your binary so users can see and/or tinker with them. See [where is this useful](#where-is-this-useful) for an application example.

Install with (requires Go 1.16+)

```shell-script
go get -u github.com/soypat/rebed
```

## Five actions available:

```go

//go:embed someFS/*
var bdFS embed.FS

// Just replicate folder Structure
rebed.Tree(bdFS, "")

// Make empty files
rebed.Touch(bdFS, "")

// Recreate entire FS
rebed.Write(bdFS, "")

// Recreate FS without modifying existing files
rebed.Patch(bdFS, "")

// Runs Patch if no conflicting file is found, else error.
err := rebed.Create(bdFS, "")

/* Walk allows you operate on each file as you wish */
```

### Where is this useful?
You could theoretically embed your web development assets folder and deploy it. The binary could run from the working directory folder generated by `rebed` and users could modify the assets and change the website's look (to do this run `rebed.Patch` to not overwrite modified files). If asset files are lost or the site breaks, running `rebed.Write` replaces all files with original ones.

## Contributing
I'll look at issues and pull requests. Add a clear explanation when doing so!


rebed

Embeds files into Go programs and provides http.FileSystem interfaces to them.

## DEPRECATED

Stop using this and switch to [embed](https://pkg.go.dev/embed) now in the standard library.

# esc

[![GoDoc](https://godoc.org/github.com/mjibson/esc?status.svg)](https://godoc.org/github.com/mjibson/esc)

esc embeds files into go programs and provides http.FileSystem interfaces
to them.

It adds all named files or files recursively under named directories at the
path specified. The output file provides an http.FileSystem interface with
zero dependencies on packages outside the standard library.

## Installation

`go get -u github.com/mjibson/esc`

## Usage

`esc [flag] [name ...]`

The flags are:

```
-o=""
	output filename, defaults to stdout
-pkg="main"
	package name of output file, defaults to main
-prefix=""
	strip given prefix from filenames
-ignore=""
	regular expression for files to ignore
-include=""
	regular expression for files to include
-modtime=""
	Unix timestamp to override as modification time for all files
-private
	unexport functions by prefixing them with esc, e.g. FS -> escFS
-no-compress
	do not compress files
```

## Accessing Embedded Files

After producing an output file, the assets may be accessed with the FS()
function, which takes a flag to use local assets instead (for local
development).

 * (_esc)?FS(Must)?(Byte|String) returns an asset as a (byte slice|string).
 * (_esc)?FSMust(Byte|String) panics if the asset is not found.

## Go Generate

esc can be invoked by go generate:

`//go:generate esc -o static.go -pkg server static`

## Example

Embedded assets can be served with HTTP using the http.FileServer.
Assuming you have a directory structure similar to the following:

```
.
├── main.go
└── static
    ├── css
    │   └── style.css
    └── index.html
```

Where main.go contains:

```
package main

import (
	"log"
	"net/http"
)

func main() {
	// FS() is created by esc and returns a http.Filesystem.
	http.Handle("/static/", http.FileServer(FS(false)))
	log.Fatal(http.ListenAndServe(":8080", nil))
}

```

1. Generate the embedded data:
	`esc -o static.go static`
2. Start the server:
	`go run main.go static.go`
3. Access http://localhost:8080/static/index.html to view the files.

You can see worked example in [example](example) dir
just run it as
`go run example/main.go example/static.go`


Simple tool to embed files in go with focus on "customization" and ease to use.

fileb0x

Generates a vfsdata.go file that statically implements the given virtual filesystem

vfsgen
======

[![Go Reference](https://pkg.go.dev/badge/github.com/shurcooL/vfsgen.svg)](https://pkg.go.dev/github.com/shurcooL/vfsgen)

Package vfsgen takes an http.FileSystem (likely at `go generate` time) and
generates Go code that statically implements the provided http.FileSystem.

Features:

-	Efficient generated code without unneccessary overhead.

-	Uses gzip compression internally (selectively, only for files that compress well).

-	Enables direct access to internal gzip compressed bytes via an optional interface.

-	Outputs `gofmt`ed Go code.

Installation
------------

```sh
go get github.com/shurcooL/vfsgen
```

Usage
-----

Package `vfsgen` is a Go code generator library. It has a `Generate` function that takes an input filesystem (as a [`http.FileSystem`](https://godoc.org/net/http#FileSystem) type), and generates a Go code file that statically implements the contents of the input filesystem.

For example, we can use [`http.Dir`](https://godoc.org/net/http#Dir) as a `http.FileSystem` implementation that uses the contents of the `/path/to/assets` directory:

```Go
var fs http.FileSystem = http.Dir("/path/to/assets")
```

Now, when you execute the following code:

```Go
err := vfsgen.Generate(fs, vfsgen.Options{})
if err != nil {
	log.Fatalln(err)
}
```

An assets_vfsdata.go file will be generated in the current directory:

```Go
// Code generated by vfsgen; DO NOT EDIT.

package main

import ...

// assets statically implements the virtual filesystem provided to vfsgen.Generate.
var assets http.FileSystem = ...
```

Then, in your program, you can use `assets` as any other [`http.FileSystem`](https://godoc.org/net/http#FileSystem), for example:

```Go
file, err := assets.Open("/some/file.txt")
if err != nil {
	return err
}
defer file.Close()
```

```Go
http.Handle("/assets/", http.FileServer(assets))
```

`vfsgen` can be more useful when combined with build tags and go generate directives. This is described below.

### `go generate` Usage

vfsgen is great to use with go generate directives. The code invoking `vfsgen.Generate` can go in an assets_generate.go file, which can then be invoked via "//go:generate go run assets_generate.go". The input virtual filesystem can read directly from disk, or it can be more involved.

By using build tags, you can create a development mode where assets are loaded directly from disk via `http.Dir`, but then statically implemented for final releases.

For example, suppose your source filesystem is defined in a package with import path "example.com/project/data" as:

```Go
//go:build dev

package data

import "net/http"

// Assets contains project assets.
var Assets http.FileSystem = http.Dir("assets")
```

When built with the "dev" build tag, accessing `data.Assets` will read from disk directly via `http.Dir`.

A generate helper file assets_generate.go can be invoked via "//go:generate go run -tags=dev assets_generate.go" directive:

```Go
//go:build ignore

package main

import (
	"log"

	"example.com/project/data"
	"github.com/shurcooL/vfsgen"
)

func main() {
	err := vfsgen.Generate(data.Assets, vfsgen.Options{
		PackageName:  "data",
		BuildTags:    "!dev",
		VariableName: "Assets",
	})
	if err != nil {
		log.Fatalln(err)
	}
}
```

Note that "dev" build tag is used to access the source filesystem, and the output file will contain "!dev" build tag. That way, the statically implemented version will be used during normal builds and `go get`, when custom builds tags are not specified.

### `vfsgendev` Usage

`vfsgendev` is a binary that can be used to replace the need for the assets_generate.go file.

Make sure it's installed and available in your PATH.

```bash
go get -u github.com/shurcooL/vfsgen/cmd/vfsgendev
```

Then the "//go:generate go run -tags=dev assets_generate.go" directive can be replaced with:

```
//go:generate vfsgendev -source="example.com/project/data".Assets
```

vfsgendev accesses the source variable using "dev" build tag, and generates an output file with "!dev" build tag.

### Additional Embedded Information

All compressed files implement [`httpgzip.GzipByter` interface](https://godoc.org/github.com/shurcooL/httpgzip#GzipByter) for efficient direct access to the internal compressed bytes:

```Go
// GzipByter is implemented by compressed files for
// efficient direct access to the internal compressed bytes.
type GzipByter interface {
	// GzipBytes returns gzip compressed contents of the file.
	GzipBytes() []byte
}
```

Files that have been determined to not be worth gzip compressing (their compressed size is larger than original) implement [`httpgzip.NotWorthGzipCompressing` interface](https://godoc.org/github.com/shurcooL/httpgzip#NotWorthGzipCompressing):

```Go
// NotWorthGzipCompressing is implemented by files that were determined
// not to be worth gzip compressing (the file size did not decrease as a result).
type NotWorthGzipCompressing interface {
	// NotWorthGzipCompressing is a noop. It's implemented in order to indicate
	// the file is not worth gzip compressing.
	NotWorthGzipCompressing()
}
```

Comparison
----------

vfsgen aims to be conceptually simple to use. The [`http.FileSystem`](https://godoc.org/net/http#FileSystem) abstraction is central to vfsgen. It's used as both input for code generation, and as output in the generated code.

That enables great flexibility through orthogonality, since helpers and wrappers can operate on `http.FileSystem` without knowing about vfsgen. If you want, you can perform pre-processing, minifying assets, merging folders, filtering out files and otherwise modifying input via generic `http.FileSystem` middleware.

It avoids unneccessary overhead by merging what was previously done with two distinct packages into a single package.

It strives to be the best in its class in terms of code quality and efficiency of generated code. However, if your use goals are different, there are other similar packages that may fit your needs better.

### Alternatives

-	[`embed`](https://go.dev/pkg/embed) - Package embed provides access to files embedded in the running Go program.
-	[`go-bindata`](https://github.com/jteeuwen/go-bindata) - Reads from disk, generates Go code that provides access to data via a [custom API](https://github.com/jteeuwen/go-bindata#accessing-an-asset).
-	[`go-bindata-assetfs`](https://github.com/elazarl/go-bindata-assetfs) - Takes output of go-bindata and provides a wrapper that implements `http.FileSystem` interface (the same as what vfsgen outputs directly).
-	[`becky`](https://github.com/tv42/becky) - Embeds assets as string literals in Go source.
-	[`statik`](https://github.com/rakyll/statik) - Embeds a directory of static files to be accessed via `http.FileSystem` interface (sounds very similar to vfsgen); implementation sourced from [camlistore](https://camlistore.org).
-	[`go.rice`](https://github.com/GeertJohan/go.rice) - Makes working with resources such as HTML, JS, CSS, images and templates very easy.
-	[`esc`](https://github.com/mjibson/esc) - Embeds files into Go programs and provides `http.FileSystem` interfaces to them.
-	[`staticfiles`](https://github.com/bouk/staticfiles) - Allows you to embed a directory of files into your Go binary.
-	[`togo`](https://github.com/flazz/togo) - Generates a Go source file with a `[]byte` var containing the given file's contents.
-	[`fileb0x`](https://github.com/UnnoTed/fileb0x) - Simple customizable tool to embed files in Go.
-	[`embedfiles`](https://github.com/leighmcculloch/embedfiles) - Simple tool for embedding files in Go code as a map.
-	[`packr`](https://github.com/gobuffalo/packr) - Simple solution for bundling static assets inside of Go binaries.
-	[`rsrc`](https://github.com/akavel/rsrc) - Tool for embedding .ico & manifest resources in Go programs for Windows.

Attribution
-----------

This package was originally based on the excellent work by [@jteeuwen](https://github.com/jteeuwen) on [`go-bindata`](https://github.com/jteeuwen/go-bindata) and [@elazarl](https://github.com/elazarl) on [`go-bindata-assetfs`](https://github.com/elazarl/go-bindata-assetfs).

Directories
-----------

| Path                                                                         | Synopsis                                                                                |
|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| [cmd/vfsgendev](https://pkg.go.dev/github.com/shurcooL/vfsgen/cmd/vfsgendev) | vfsgendev is a convenience tool for using vfsgen in a common development configuration. |

License
-------

-	[MIT License](LICENSE)


vfsgen

Create an `embed.FS` from an existing `embed.FS` subdirectory

<img src="logo.png" width="50%"> 



 <code>embed.FS</code> wrapper providing additional functionality 
 <a href="https://github.com/leaanthony/debme/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
 <a href="https://goreportcard.com/report/github.com/leaanthony/debme"><img src="https://goreportcard.com/badge/github.com/leaanthony/debme"/></a>
 <a href="https://godoc.org/github.com/leaanthony/debme"><img src="https://img.shields.io/badge/godoc-reference-blue.svg"/></a>
 <a href="https://www.codefactor.io/repository/github/leaanthony/debme"><img src="https://www.codefactor.io/repository/github/leaanthony/debme/badge" alt="CodeFactor" /></a>
 <a href="https://github.com/leaanthony/debme/issues"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat" alt="CodeFactor" /></a>
 <a href="https://app.fossa.io/projects/git%2Bgithub.com%2Fleaanthony%2Fdebme?ref=badge_shield" alt="FOSSA Status"><img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Fleaanthony%2Fdebme.svg?type=shield"/></a>
 <a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg" /></a>


## Features

 * Get an `embed.FS` from an embedded subdirectory
 * Handy `Copy(sourcePath, targetPath)` method to copy an embedded file to the filesystem
 * 100% `embed.FS` compatible
 * 100% code coverage

## Example

```go
package main

import (
	"embed"
	"github.com/leaanthony/debme"
	"io/fs"
)

// Example Filesystem:
//
// fixtures/
// ├── test1
// | └── onefile.txt
// └── test2
// └── inner
// ├── deeper
// | └── three.txt
// ├── one.txt
// └── two.txt

//go:embed fixtures
var fixtures embed.FS

func main() {
	root, _ := debme.FS(fixtures, "fixtures")

	// Anchor to "fixtures/test1"
	test1, _ := root.FS("test1")
	files1, _ := test1.ReadDir(".")

	println(len(files1)) // 1
	println(files1[0].Name()) // "onefile.txt"

	// Anchor to "fixtures/test2/inner"
	inner, _ := root.FS("test2/inner")
	one, _ := inner.ReadFile("one.txt")

	println(string(one)) // "1"

	// Fully compatible FS
	fs.WalkDir(inner, ".", func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		println("Path:", path, " Name:", d.Name())
		return nil
	})

	/*
		Path: . Name: inner
		Path: deeper Name: deeper
		Path: deeper/three.txt Name: three.txt
		Path: one.txt Name: one.txt
		Path: two.txt Name: two.txt
	*/
	
	// Go deeper
	deeper, _ := inner.FS("deeper")
	deeperFiles, _ := deeper.ReadDir(".")

	println(len(deeperFiles)) // 1
	println(files1[0].Name()) // "three.txt"
	
	// Copy files
	err := deeper.Copy("three.txt", "/path/to/target.txt")
}
```

## Why

Go's new embed functionality is awesome! The only thing I found a little frustrating was the need to manage base paths.
This module was created out of the need to embed multiple templates in the [Wails](https://github.com/wailsapp/wails) CLI.

The Best Go Libraries For Resource Embedding (5)

rebed

esc

fileb0x

vfsgen

debme