From 09617733cb68064d54ab558c514cca6fb38eb25b Mon Sep 17 00:00:00 2001
From: balki <3070606-balki@users.noreply.gitlab.com>
Date: Wed, 17 Aug 2022 00:14:42 -0400
Subject: [PATCH] improve doc

---
 Makefile  |  9 ++++-----
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/Makefile b/Makefile
index 541bf7e..61c2c43 100644
--- a/Makefile
+++ b/Makefile
@@ -2,16 +2,15 @@
 help:  ## Show this help
 	@echo 'makepac'
 	@echo '--------'
-	@echo 'Run the below command in the projects main directory for initial setup'
+	@echo 'Simple configuration manager'
 	@echo ''
-	@echo '    git submodule add https://gitlab.com/balki/makepac'
-	@echo '    echo "include makepac/Makefile" > Makefile'
+	@echo 'See https://gitlab.com/balki/makepac for usage'
 	@echo ''
 	@#https://stackoverflow.com/a/47107132
 	@sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST) | column -tl 2
 
 .PHONY: install
-install:  ## Symlinks files in pac-root
+install:  ## Symlinks files in root/ to real root
 	sudo ./makepac/install.sh
 
 .PHONY: sd-reload
@@ -27,7 +26,7 @@ save-perms:  ## Saves the file permissions to ./acl. Run this after adding new f
 	getfacl --recursive root > acl
 
 .PHONY: set-perms
-set-perms:  ## Restores permissions of all the files from ./acl
+set-perms:  ## Restores permissions of all files from ./acl
 	sudo setfacl --restore acl
 
 .PHONY: skel
diff --git a/README.md b/README.md
index 1a81686..6322f8b 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,63 @@
-makepac
---------
+`makepac` is a simple configuration manager for a linux system
 
-`makepacc` is a simple package manager to keep all file changes in a linux server in a git repository.
+A typical linux app needs multiple files in different paths spread in the file-system. E.g. systemd service, timer, app config, webserver config, logrotate config. `makepac` keeps all configs in a single place in a git repository and creates symlinks in real root
+
+Easily share the setup to other user.
 
 Initial setup
+-------------
 
     mkdir myfiles
     cd myfiles
     git init
     git submodule add https://gitlab.com/balki/makepac'
     echo "include makepac/Makefile" > Makefile'
+    sudo apt install acl
     make skel
     git add .
     git commit -m 'initial commit'
 
-Now, create all the files inside the `root` directory and run `make install` to have it symlinked to the same path in the real root. Permissions and ownership of the files are recorded with `make save-perms` in `./acl`. After making changes to the system, just make a git commit to record the state
+
+Workflow
+--------
+
+1. Create required files under root/
+2. Set correct ownership and permissions
+3. Run `make intall`
+4. Run `make sd-users` and `make sd-reload` if required
+5. Enable and test the service and update all configs as required
+6. Run `make save-perms` to update `./acl` file
+7. Add any important notes in README (like dependencies, additional commands ran)
+8. Finally `git commit`
+
+Cloning from other user
+-----------------------
+
+    git clone <other user repo url>
+    make set-perms
+    make install
+
+Usage
+-----
+
+    ❯ make help        
+    makepac
+    --------
+    Simple configuration manager
+
+    See https://gitlab.com/balki/makepac for usage
+
+    help:         Show this help
+    install:      Symlinks files in root/ to real root
+    sd-reload:    Run this after editing systemd service/timer files
+    sd-users:     Run this after adding new users
+    save-perms:   Saves the file permissions to ./acl. Run this after adding new files with correct permissions
+    set-perms:    Restores permissions of all files from ./acl
+    skel:         Creates common directories needed
+
+Tips
+----
+1. When adding a file with no public read permissions, it can't be saved in the git repo. You can git-ignore the file or add read permission for the repo use alone using this command. Also consider setting up [git-crypt](https://www.agwa.name/projects/git-crypt/) for those files
+
+    sudo setfacl -m "u:$USER:r" root/etc/app/secret_token
+