distribusi-go/README.md

# distribusi-go

<p align="center">
  <img src="./contrib/logo/logo.png" />
</p>

> This is still very experimental, please take a backup of your archives if you
> are running it on files you care about. It hasn't been tested on large
> archives. There are probably some pretty bad bugs lurking in there. It may
> still thrash files. Please [report issues] as you find them :100: Thanks for
> testing!

A [Go] implementation of [distribusi].

If you're migrating from the Python version or have experience using it, here are the differences in `distribusi-go`:

- It's simpler to install on your computer, just download the binary, `chmod
  +x` and run it :100:

- There is no need to install [Pillow] for handling images, that is now
  built-in. The only external dependency is [exiftool] for image captions from
  embedded metadata. If you don't have `exiftool` installed, then it gracefully
  skips that feature. So, you don't need to install anything else to run
  `distribusi` now :pray:

- The command-line interface is quite different. There are less optional flags
  and more defaults. I shuffled a number of things around according to my
  preferences (open to changes, please [open a ticket]). For example, I always
  like my images to be thumbnail'd. There's a handy web server built-in now,
  just run with `-s` :metal:

## Install

:champagne: `distribusi-go` has enterprise cross-platform support! :champagne:

If your platform isn't listed below, please see [the entire listing]. If you
can't find it there, we can probably add support for it (see `$GOOS`/`$GOARCH`
[on go.dev]), please [open a ticket]. Package manager installation methods are
planned for Some Time Soon :tm: (e.g. `apt install distribusi`, see [this ticket] to track)

### GNU/Linux

<details><summary>GNU/Linux (amd64)</summary>
<pre>
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_linux_amd64/distribusi -o distribusi
chmod +x distribusi
./distribusi -h # check things work
</pre>
</details>

<details><summary>GNU/Linux (386)</summary>
<pre>
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_linux_386/distribusi -o distribusi
chmod +x distribusi
./distribusi -h # check things work
</pre>
</details>

<details><summary>GNU/Linux (arm64)</summary>
<pre>
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_linux_arm64/distribusi -o distribusi
chmod +x distribusi
./distribusi -h # check things work
</pre>
</details>

### Mac OS X

<details><summary>Mac OS X (amd64)</summary>
<pre>
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_darwin_amd64/distribusi -o distribusi
chmod +x distribusi
./distribusi -h # check things work
</pre>
</details>

<details><summary>Mac OS X (arm64)</summary>
<pre>
curl https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_darwin_arm64/distribusi -o distribusi
chmod +x distribusi
./distribusi -h # check things work
</pre>
</details>

### Windows

<details><summary>Windows (amd64)</summary>
I've no idea how you even install this on Windoze! Maybe you can help by
sending a documentation patch? :pray:

> https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_windows_amd64/distribusi.exe

</details>

<details><summary>Windows (386)</summary>
I've no idea how you even install this on Windoze! Maybe you can help by
sending a documentation patch? :pray:

> https://vvvvvvaria.org/~decentral1se/distribusi-go/0.1.0-alpha/distribusi_windows_386/distribusi.exe

</details>

## Quick start

Run `distribusi-go` on `<path>` and serve it locally for viewing:

```bash
./distribusi -p <path> -s
```

If you want to ignore certain paths, you can use `-i/--ignore`:

```bash
./distribusi -p <path> -s -i '*.gif, *.md, mydir'
```

It supports a list of patterns in a comma separated list, wildcards work, more [on pkg.go.dev].

If you run into issues, run with `-d/--debug`. All debug logs are stored in a time stamped log file under `/tmp/`.

```bash
ls /tmp/ | grep -i distribusi
distribusi-go-20-25-492637114356
```

If you have SSH access to a server, you can publish your files with `-P/--publish`.

The syntax works just like [scp] and it uses SSH to transfer the files under the hood:

```
./distribusi -p <path> -P <server>:<remote-path>
```

See [this short guide](#ssh-guide-for-p-publish) for help with SSH connection issues.

:v:

## Hacking

You'll need [Go] >= 1.11 installed. Run `make` to build a new `./distribusi` executable.

If you wanna learn Go, I've got [this book], feel free to take a loan of it :grinning:

## Release

Currently, you have to be `@decentral1se` to do this:

```bash
git tag <version>
VERSION=<version> make release
```

You can build a local-only release by running this:

```bash
goreleaser release --snapshot --rm-dist
```

Binaries are in `dist/`.

## Acknowledgements

[`AUTHORS.md`](./AUTHORS.md)

## License

![](https://www.gnu.org/graphics/gplv3-or-later.png)

[`LICENSE`](./LICENSE)

## Tips

### SSH guide for `-P/--publish`

`distribusi-go` only supports one connection method right now: SSH public key
authentication using `ssh-agent`. This is mostly for simplicity, there is a
discussion running [over here] if you'd like to see more methods available.

Let's take a practical example. First, make sure your `ssh-agent` is running
and your SSH key is loaded:

```
eval $(ssh-agent -s)
ssh-add ~/.ssh/<ssh-secret-key-part>
ssh-add -L # see loaded keys
```

Now, when you type `-P <server>:...`, `distribusi-go` will look up an entry in
your `~/.ssh/config` with a matching `<server>` value. I.e. if you want to run
`./distribusi -p <path> -P varia.zone:/var/www/`, then a matching
`~/.ssh/config` entry might look like this:

```ssh
Host varia.zone
  Hostname varia.zone
  User decentral1se
  Port 22
  IdentityFile ~/.ssh/<ssh-secret-key-part>
```

`distribusi-go` will read the `User` and `Port` values from this configuration.
It won't try to parse private key files or prompt for passwords, it will simply
interface with `ssh-agent` which handles all that. If there is no
`~/.ssh/config` entry, default values will be attempted.

If all else fails, try `-d/--debug` for extra help figuring out what SSH
connection details are used. You can [open a ticket] and we can try and help.

### Generating the logo

```
cat contrib/logo/LOGO | lolcat -F 0.1
```

[Go]: https://go.dev
[Pillow]: https://pillow.readthedocs.io/en/stable/installation.html#external-libraries
[distribusi]: https://git.vvvvvvaria.org/varia/distribusi
[exiftool]: https://exiftool.org/
[on go.dev]: https://go.dev/doc/install/source#environment
[on pkg.go.dev]: https://pkg.go.dev/path/filepath#Match
[open a ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
[over here]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/4
[report issues]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/new/choose
[scp]: https://linux.die.net/man/1/scp
[the entire listing]: https://vvvvvvaria.org/~decentral1se/distribusi-go/
[this book]: https://www.gopl.io/
[this ticket]: https://git.vvvvvvaria.org/decentral1se/distribusi-go/issues/1