scripts: improve manage-package-overrides.sh clone workflow

- Clone with --recurse-submodules so submodules are initialised
- Use --recurse-submodules on git pull during updates too
- Add fork-first workflow for GitHub repos: fork via gh, clone the
  fork as origin, add original as upstream remote
- Add -f/--fork flag to auto-accept the fork prompt
- Create a local branch at the pinned version commit instead of
  leaving the repo in detached HEAD state
- Redirect all print_* output inside fork_github_repo to stderr so
  the fork URL captured by command substitution stays clean
- Abort override registration when git clone fails

docs: add local-overrides.md newbie guide covering the full workflow
from listing packages through cloning, building, and opening a PR

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: themactep

docs/local-overrides.md

@@ -0,0 +1,135 @@
+# Working with Local Package Overrides
+
+Buildroot's **override** mechanism lets you replace a package's downloaded source
+with a local directory on your machine. This is the standard way to develop or
+patch a package without touching the Buildroot internals.
+
+The `scripts/manage-package-overrides.sh` helper automates the whole workflow.
+
+---
+
+## How it works
+
+When a package has an override, Buildroot reads its source from the directory you
+specify instead of downloading the upstream tarball or cloning the upstream repo.
+The mapping lives in `local.mk`:
+
+```
+EXFAT_NOFUSE_OVERRIDE_SRCDIR = $(BR2_EXTERNAL)/overrides/exfat-nofuse
+```
+
+During a build, Buildroot uses `rsync` to copy that directory into the build tree,
+so you can edit files in `overrides/<package>/`, run `make <package>-rebuild`, and
+see your changes without a full rebuild.
+
+---
+
+## Quick-start: set up an override
+
+### 1. Find the package name
+
+```sh
+./scripts/manage-package-overrides.sh -l          # list all packages
+./scripts/manage-package-overrides.sh -l thingino-*  # filter by pattern
+```
+
+### 2. Clone and register an override (interactive)
+
+```sh
+./scripts/manage-package-overrides.sh <package-name>
+```
+
+The script reads the package's `.mk` file, shows you the upstream URL and pinned
+version, then asks:
+
+- **Fork this GitHub repo before cloning?** – say `y` if this is a foreign
+  (third-party) repo you may want to send changes back to.  The script forks it
+  under your GitHub account, clones the fork, and adds the original as `upstream`.
+- **Download/clone this package?** – say `y` to proceed.
+
+The clone lands in `overrides/<package>/` and the entry is written to `local.mk`.
+
+#### Auto mode (no prompts)
+
+```sh
+./scripts/manage-package-overrides.sh -a <pattern>   # clone without asking
+./scripts/manage-package-overrides.sh -a -f <pattern> # also fork automatically
+```
+
+---
+
+## Making and building changes
+
+```sh
+# edit source files
+vim overrides/exfat-nofuse/exfat.c
+
+# rebuild just that package
+make exfat-nofuse-rebuild
+
+# rebuild and re-generate the firmware image
+make exfat-nofuse-rebuild all
+```
+
+---
+
+## Contributing changes back
+
+When you cloned via a fork (`-f`), the repo is pre-configured for the full
+fork → branch → PR workflow:
+
+| Remote | Points to |
+|--------|-----------|
+| `origin` | Your fork on GitHub |
+| `upstream` | The original repo |
+
+A local branch named `local-<short-hash>` was created at the pinned commit, so
+you are never in a detached HEAD state.
+
+```sh
+cd overrides/exfat-nofuse
+
+# commit your work
+git add -p
+git commit -m "fix: description of the change"
+
+# push to your fork
+git push origin local-01c30ad...
+
+# open a pull request against the original repo
+gh pr create --repo dorimanx/exfat-nofuse --base master \
+  --title "fix: description" --body "Details..."
+```
+
+---
+
+## Managing existing overrides
+
+| Task | Command |
+|------|---------|
+| List all overrides and their paths | `./scripts/manage-package-overrides.sh -l` |
+| Temporarily disable (comment out) | `./scripts/manage-package-overrides.sh -d <package>` |
+| Re-enable a disabled override | `./scripts/manage-package-overrides.sh -e <package>` |
+| Pull latest changes in an override | `./scripts/manage-package-overrides.sh -u <package>` |
+| Update all overrides at once | `./scripts/manage-package-overrides.sh -u --all` |
+| Remove an override entry | `./scripts/manage-package-overrides.sh -r <package>` |
+| Remove all override entries | `./scripts/manage-package-overrides.sh --clean` |
+
+Disabling an override comments out the `local.mk` line so Buildroot falls back to
+the upstream source, without losing the local clone.
+
+---
+
+## Directory layout
+
+```
+firmware/
+├── local.mk                     ← override mappings (git-ignored, machine-local)
+├── overrides/                   ← git-ignored; holds your local clones
+│   └── exfat-nofuse/            ← working clone (origin = fork, upstream = original)
+└── scripts/
+    └── manage-package-overrides.sh
+```
+
+Both `local.mk` and `overrides/` are git-ignored, so your local development setup
+never pollutes the firmware repository.

scripts/manage-package-overrides.sh

@@ -7,6 +7,7 @@ BASE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 PACKAGE_DIR="$BASE_DIR/package"
 OVERRIDES_DIR="$BASE_DIR/overrides"
 LOCAL_MK="$BASE_DIR/local.mk"
+FORK_MODE="no"
 
 # Colors for output
 RED='\033[0;31m'
@@ -40,6 +41,7 @@ Traverse packages in package/ directory and manage local source overrides.
 OPTIONS:
     -h, --help              Show this help message
     -a, --auto              Automatically download all matching packages without prompting
+    -f, --fork              Fork GitHub repos before cloning (enables contribution workflow)
     -l, --list              List packages and their override status only
     -r, --remove PACKAGE    Remove override for specified package
     -e, --enable PACKAGE    Enable (uncomment) override for specified package
@@ -317,7 +319,7 @@ update_override() {
 
     # Pull latest changes
     print_info "Pulling latest changes on $current_branch..."
-    if git pull --ff-only origin "$current_branch" 2>&1; then
+    if git pull --recurse-submodules --ff-only origin "$current_branch" 2>&1; then
         print_success "Updated $pkg_name successfully"
     else
         print_error "Failed to update $pkg_name (conflicts or non-fast-forward)"
@@ -329,6 +331,33 @@ update_override() {
     return 0
 }
 
+# Check if a URL points to a GitHub repository
+is_github_url() {
+    [[ "$1" =~ github\.com ]]
+}
+
+# Fork a GitHub repo and echo the fork's clone URL
+fork_github_repo() {
+    local repo_url="$1"
+    local repo_path
+    repo_path=$(echo "$repo_url" | sed -E 's|https://github\.com/||; s|git@github\.com:||; s|\.git$||')
+
+    print_info "Forking $repo_path on GitHub..." >&2
+    if ! gh repo fork "$repo_path" --clone=false >&2 2>&1; then
+        print_error "Failed to fork repository" >&2
+        return 1
+    fi
+
+    local gh_user
+    gh_user=$(gh api user --jq .login 2>/dev/null)
+    if [ -z "$gh_user" ]; then
+        print_error "Could not determine GitHub username" >&2
+        return 1
+    fi
+
+    echo "https://github.com/$gh_user/$(basename "$repo_path")"
+}
+
 # Clone or download package source
 download_package() {
     local pkg_name="$1"
@@ -355,18 +384,58 @@ download_package() {
     fi
 
     if [ "$method" = "git" ]; then
-        print_info "Cloning $site to $dest_dir"
+        local clone_url="$site"
+        local upstream_url=""
+
+        # Offer to fork GitHub repos for an easier contribution workflow
+        if is_github_url "$site"; then
+            local do_fork="$FORK_MODE"
+            if [ "$do_fork" != "yes" ]; then
+                read -p "Fork this GitHub repo before cloning? [y/N]: " -n 1 -r
+                echo
+                [[ $REPLY =~ ^[Yy]$ ]] && do_fork="yes"
+            fi
+            if [ "$do_fork" = "yes" ]; then
+                local fork_url
+                if fork_url=$(fork_github_repo "$site"); then
+                    upstream_url="$site"
+                    clone_url="$fork_url"
+                    print_success "Will clone fork: $clone_url"
+                else
+                    print_warning "Forking failed, cloning original..."
+                fi
+            fi
+        fi
+
+        print_info "Cloning $clone_url to $dest_dir"
 
         if [ -n "$branch" ]; then
-            git clone --branch "$branch" "$site" "$dest_dir"
+            if ! git clone --recurse-submodules --branch "$branch" "$clone_url" "$dest_dir"; then
+                print_error "Clone failed"
+                return 1
+            fi
         else
-            git clone "$site" "$dest_dir"
+            if ! git clone --recurse-submodules "$clone_url" "$dest_dir"; then
+                print_error "Clone failed"
+                return 1
+            fi
+        fi
+
+        # Add upstream remote if we cloned a fork
+        if [ -n "$upstream_url" ]; then
+            git -C "$dest_dir" remote add upstream "$upstream_url"
+            print_info "Added upstream remote: $upstream_url"
         fi
 
-        # Checkout specific version if not HEAD
+        # Checkout specific version if not HEAD; create a local branch to avoid detached HEAD
         if [ -n "$version" ] && [ "$version" != "HEAD" ]; then
             cd "$dest_dir"
-            git checkout "$version" 2>/dev/null || print_warning "Could not checkout version: $version"
+            local local_branch="local-$(echo "$version" | tr '/' '-' | cut -c1-30)"
+            if git checkout -b "$local_branch" "$version" 2>/dev/null; then
+                print_info "Created local branch '$local_branch' at $version"
+            else
+                print_warning "Could not create branch at version: $version"
+            fi
             cd - >/dev/null
         fi
 
@@ -630,6 +699,10 @@ main() {
                 auto_mode="yes"
                 shift
                 ;;
+            -f|--fork)
+                FORK_MODE="yes"
+                shift
+                ;;
             -l|--list)
                 mode="list"
                 shift