diff --git a/README.md b/README.md
index e3d332e..b64d1ca 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ The git repo in the current directory is expected to have at least
 one remote pointing to the target project. If that repo is not
 writable, another one can be used for pushing.
 
-create a config file in the current directory
+create a config file `.settings` in the top level directory of the git submodule project:
 ```
 # name of the remote to push to as repored by `git remote`
 PUSH_REMOTE="joesix"
@@ -30,3 +30,24 @@ DATE="@token"
 # optional: an OBS project with a list of packages
 OBSPKGLIST="https://api.opensuse.org/public/source/openSUSE:Factory:Rings:0-Bootstrap"
 ```
+
+Scripts:
+
+All scripts use getopt, --help may not always be up to date though
+:-)
+
+- updatemodules: checks all submodules for updates. For packages
+  that need to be updated creates `refs/pq/$packagename`. The
+  updated refence there updates the submodule commit reference for
+  updates. It also adds or removes entries from/to `.gitmodules` if
+  needed. There's also a `--single` option which produces a single
+  reference for all updates. The `--status` option show the current
+  state.
+- pusher: compares the references created by the `updatemodules`
+  script with the specified remote. Pushed pending refs to an
+  `update_$packagename` ref. Gitea doesn't seem to support refs in
+  subdirs other than `heads`, that's why. Unless the `--dry` option
+  is specified, the `pusher` script also creates pull requests for
+  pending refs.
+- gitea-pulls: dialog based script to list, view, merge or close
+  pull requests from the command line.