initial commitHEADmain

1 files changed, 45 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..193bcfa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# Porteur
+
+Porteur automates the creation of FreeBSD ports directly from Git repositories.
+It bridges the gap between source code and the FreeBSD ports framework with
+generating ready-to-build ports that work seamlessly with `poudriere` and
+native `make` tooling.
+
+
+## Concepts
+
+### Ports Trees
+A ports tree is a collection of ports similar to how FreeBSD defines it. It
+only contains the ports and can be used as an overlay in the ports tooling
+of FreeBSD. Porteur can manage multiple ports trees and defaults to the
+`default` tree.
+
+### Template
+A template defines all the files that the resulting FreeBSD port should contain.
+It is used to avoid repetitive port file definitions and uses variables to make
+these files usable by multiple ports.
+
+All templates must be defined in the directory `$PREFIX/etc/porteur/tmpl`.
+
+### Port
+A port in porteur is basically a reference to a Git repository and a template.
+From such a port porteur creates a FreeBSD port which is ready to use with
+`poudriere` or `make`.
+
+The Git repository is used to create the distfile that will be referenced in
+the Makefile. Porteur manages a local clone of this repository and bundles the
+source code of the branch that is configured.
+
+The template defines the contents of the resulting FreeBSD port. Each variable
+used in the template must be defined by the port in order to render correctly.
+
+
+## Quickstart
+
+1. Create a template in `$PREFIX/etc/porteur/tmpl`.
+2. Create a new port: `porteur port add my-app`
+3. Define the variables the referenced template needs: `porteur port vars --edit my-app`
+4. Trigger the first rendering of the port: `porteur port update my-app`
+5. Use the port with the FreeBSD ports tooling.
+
+For more information see `porteur --help`.