1 files changed, 122 insertions, 1 deletions

diff --git a/README.md b/README.md
index 140ae2c..1550e51 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,124 @@
 # dots-backup
 
-A simple bash script to backup all my dotfiles and have them available to be easily restored on any system.
\ No newline at end of file
+Bash script to back up dotfiles into a local git repo, and restore them on any system.
+
+## Requirements
+
+- `bash`
+- `rsync`
+- `git`
+
+## How It Works
+
+`dot-backup.sh` reads a list of dotfiles, copies them into a local git repo using `rsync`, then auto-commits any changes.
+
+Backup layout:
+
+```
+~/Programming/GIT/my-dotfiles/
+├── home/           # files from $HOME (relative paths)
+│   ├── .bashrc
+│   ├── .gitconfig
+│   └── .config/
+│       └── nvim/
+└── system/         # files from / (absolute paths)
+    └── etc/
+        └── bash_completion.d/
+```
+
+## First Run
+
+```bash
+git clone https://github.com/you/dots-backup
+cd dots-backup
+./dot-backup.sh
+```
+
+On first run the script creates `~/Programming/GIT/my-dotfiles` and initializes a git repo inside it. Add a remote so you can push:
+
+```bash
+cd ~/Programming/GIT/my-dotfiles
+git remote add origin git@github.com:you/my-dotfiles.git
+git push -u origin master
+```
+
+## Usage
+
+```
+./dot-backup.sh [options]
+
+  -n, --dry-run    Show what would be copied without copying
+  -v, --verbose    Print each file as rsync transfers it
+  -r, --restore    Restore dotfiles from backup to original locations
+  -q, --quiet      Suppress stdout; write output to log instead
+  -h, --help       Show this help
+```
+
+## Daily Routine
+
+Run manually after changing config:
+
+```bash
+./dot-backup.sh
+```
+
+Or automate with cron (silent, logs to `~/.local/share/dot-backup/backup.log`):
+
+```bash
+# crontab -e
+0 * * * * /path/to/dot-backup.sh -q
+```
+
+After backup, push manually:
+
+```bash
+cd ~/Programming/GIT/my-dotfiles && git push
+```
+
+## Restoring on a New Machine
+
+Preview what would be restored first:
+
+```bash
+./dot-backup.sh -r --dry-run
+```
+
+Then restore:
+
+```bash
+./dot-backup.sh -r
+```
+
+System files (absolute paths like `/etc/bash_completion.d`) may need `sudo`.
+
+## Configuration
+
+Copy `config.example` to `~/.config/dot-backup/config` and edit:
+
+```bash
+mkdir -p ~/.config/dot-backup
+cp config.example ~/.config/dot-backup/config
+```
+
+Available options:
+
+```bash
+DEFAULT_OUTPUT_DIR="${HOME}/Programming/GIT/my-dotfiles"
+LOG_FILE="${HOME}/.local/share/dot-backup/backup.log"
+DOTFILES_LIST="${HOME}/.config/dot-backup/files.list"
+```
+
+## Adding Files
+
+**Edit the script** — add paths to the `DOTFILES` array in `dot-backup.sh`.
+
+**Or use the external list** — add paths to `~/.config/dot-backup/files.list`, one per line:
+
+```
+# extra dotfiles
+.config/myapp
+.config/otherapp.conf
+/etc/hosts
+```
+
+Relative paths are treated as `$HOME`-relative. Absolute paths (starting with `/`) are treated as system files.