README: add git workflow section — install, pull, overwrite local changes

Covers: installing git, first clone, pulling updates, stash vs reset --hard, checking diffs, switching branches, and a note that .env is never touched by git pulls. https://claude.ai/code/session_01C4jbd3waXG3eKZYbGUjLUQ
2026-04-22 20:55:20 +00:00
parent d00d4bf15e
commit be784a9452
1 changed files with 97 additions and 0 deletions
@@ -250,3 +250,100 @@ journalctl --user -u sky-cam-watchdog-east.service -f
 journalctl --user -u sky-cam-sunrise.service
 journalctl --user -u sky-cam-seasons-east.service
 ```
+
+---
+
+## Keeping sky-cam up to date
+
+### Install git
+
+```bash
+sudo apt install git
+```
+
+### First-time clone (if you don't have the repo yet)
+
+```bash
+git clone https://github.com/outis1one/sky-cam.git
+cd sky-cam
+```
+
+### Pull the latest changes from main
+
+After merging a pull request on GitHub, or whenever you want to update your running copy:
+
+```bash
+git pull origin main
+```
+
+Then re-run install if any schedules or scripts changed:
+
+```bash
+./install.sh
+```
+
+### Check what changed since your last pull
+
+```bash
+git log --oneline origin/main ^HEAD   # commits on remote not yet on your machine
+git diff HEAD origin/main             # full diff of incoming changes
+git fetch origin && git status        # fetch first, then show your local state
+```
+
+### You have local edits and want to pull anyway
+
+**Option A — save your changes first (recommended):**
+```bash
+git stash                # temporarily shelve your local edits
+git pull origin main     # pull updates
+git stash pop            # re-apply your edits on top
+```
+
+If `stash pop` reports a conflict, open the file and look for the `<<<<<<` markers — edit to resolve, then `git add <file>` and `git stash drop`.
+
+**Option B — discard your local edits completely:**
+```bash
+git fetch origin
+git reset --hard origin/main    # WARNING: your local edits are gone permanently
+```
+
+Use this only when you are sure you do not need your local changes.
+
+### Check what you have changed locally
+
+```bash
+git status              # which files are modified / untracked
+git diff                # show the actual changes (unstaged)
+git diff --staged       # show changes already staged with git add
+```
+
+### Look at the history
+
+```bash
+git log --oneline               # compact list of commits
+git log --oneline -20           # last 20 only
+git show <commit-hash>          # full diff for one commit
+```
+
+### Switch to a specific branch (e.g. a development branch)
+
+```bash
+git fetch origin
+git checkout claude/seasonal-sunrise-montage-nn268
+```
+
+To switch back to main:
+```bash
+git checkout main
+git pull origin main
+```
+
+### Undo the last commit (before pushing)
+
+```bash
+git reset HEAD~1        # undo commit, keep the file changes
+```
+
+### Credentials and .env are never in git
+
+`.env` is listed in `.gitignore` and will never be overwritten by a pull. `sky-cam.conf` **is** in git — if you edited it locally, a pull may conflict. Keep your machine-specific values in `.env` and leave `sky-cam.conf` for settings you want to track.