listen/README.md

# Listen

A simple watcher program written in Go that runs shell command(s) when the specified file(s) are modified.

## Why Use Listen?

- Don't switch between terminals and run that command every time! Let Listen do it for you.
- Very useful for singular files or small projects.
  - For example, you can automatically compile a C++ file with `g++` anytime you make a change to that source file.
  - Same goes for simple Python scripts, Bash scripts, etc.
- Great for students who work on a small set of source files for assignments.
- Also great for validating configuration files.

### Other Features

- Choose between listening to kernel events, or wait between checks on an interval.
- Run the command when any or all files specified are modified.
- Run the command before Listen starts waiting for modifications.
- Use the sha256 checksum to determine file modification instead of the time.
  - Could be useful for binaries.
- Timeout between modifications
  - Helpful if linters are involved, such as `clang-format`, to avoid multiple runs of a command.
- Free and Open Source software!

## Installation

You can install this package easily using the Go CLI:

```bash
# main repo
go install forge.steck.dev/bryson/listen@latest
# codeberg mirror
go install codeberg.org/brysonsteck/listen@latest
```

## Building

### Using Go

When possible, you should [install Go](https://go.dev/doc/install) on your system and build from source:

```bash
# you can alternatively clone the codeberg mirror: codeberg.org/brysonsteck/listen
git clone forge.steck.dev/bryson/listen && cd listen
go build . -o out/listen
```

### Using Docker

On **Windows and Linux**, you can alternatively build Listen in a Docker container and copy it out:

```bash
# you can alternatively clone the codeberg mirror: codeberg.org/brysonsteck/listen
git clone forge.steck.dev/bryson/listen && cd listen

# replace "linux" with "windows" appropriately
docker build -t listen-build -f docker/build.linux.Dockerfile .
mkdir -p out
docker create --name listen-build-tmp listen-build
# the exe is located at:
#   /usr/src/listen/listen - on Linux
#   C:\build\listen\listen.exe - on Windows
docker cp listen-build-tmp:/usr/src/listen/listen out/
docker rm listen-build-tmp
```

Listen is not intended for use in a standalone Docker environment (currently) due to it's function. However, you could build Listen in a stage and copy the executable to another stage to run a program inside a container:

```dockerfile
# Example Dockerfile
FROM golang:1-alpine AS build

WORKDIR /usr/src/listen
COPY . .
RUN go build .

FROM python:3 AS main

COPY --from=build /usr/src/listen /usr/local/bin
# expect a file mounted to /usr/src/main.py to listen to
CMD ["listen", "-f", "/usr/src/main.py", "--", "python", "main.py"]
```

## History

Listen was originally a Perl script that came about when I wanted something for my college assignments and also needed to learn Perl for an internship. I wrote it once and haven't touched it or improved upon it since I created it.

This program is a rewrite of that script to implement new features I've wanted using capabilities of a newer programming language. It also gave me an excuse to learn Go, so the spirit of the old script still lives with the new rewrite.

The original repository has been archived [here](https://forge.steck.dev/bryson/listen-perl) for your viewing pleasure.

## License and Warranty Disclaimer

Listen is distributed under the GNU General Public License v3. See the [license](./LICENSE) for more details.

```
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```