geet-geet 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# geet — layered template system
+https://github.com/modularizer/geet
+
+> **One working directory**. **Multiple Git repositories**. Each repo tracks a different subset of files.
+
+Nothing moves.
+Nothing is copied.
+Only Git's *view* of the filesystem changes.
+
+## Why?
+>   “I built something useful, and I think that **SOME but not all of my code is re-usable**.
+    I want to publish some of my code for other's to use (or to re-use myself)...
+    but **I don't want to spend weeks refactoring** to split apart the reusable code from the implementation-specific code.
+    In fact, it may not even be possible to move around all my files without breaking things. 
+    Plus, supporting this template is my **secondary task** which I want to do in tandem with my **primary development**, using my main repository's working directory and publishing some pieces to the template repo.”
+
+- **Making code re-usable is a struggle**, especially if you want to ship an incomplete template that is not easily separated into a standalone module.
+- Modern React Native / Expo apps are **extremely path-sensitive**:
+  * file-based routing
+  * config files at exact paths
+  * native folders
+  * toolchains that assume canonical layouts
+- templates are not static: they evolve over time. I don't want to wait until a template is fully perfect before adding to my project, and I want to get features and fixes as the come
+- syncing sucks
+- submodules don't support interleaving files and folders of template code with custom app code
+- I want to simultaneously develop many apps with a similar architecture
+
+---
+## PreReqs
+1. `git` - for pretty much everything
+2. `npm` - really just for installing `geet` globally
+3. `gh` - for use of `publish` command and `--publish`, `--private`, `--internal` flags
+
+
+---
+
+## Quickstart
+```bash
+npm install -g geet-geet
+geet
+```
+
+Try our [Demo](/docs/DEMO.md)
+
+---
+
+## Table of Contents
+
+1. [Understanding geet](/docs/UNDERSTANDING_GEET.md)
+2. [Using a geet template](/docs/USING_A_TEMPLATE.md)
+3. [Publishing a geet template](/docs/PUBLISHING_A_TEMPLATE.md)
+4. [Multi-layered repos](/docs/MULTI_LAYERED_TEMPLATES.md)
+5. [Advanced: File promotion](/docs/AUTO_PROMOTE.md)
+6. [Advanced: Merge keep-ours strategy](/docs/MERGE_KEEP_OURS.md)
+7. [Advanced: Preventing app-specific code](/docs/PREVENT_COMMIT_PATTERNS.md)
+8. [Contributing to geet](/docs/CONTRIBUTING.md)
+9. [FAQ](/docs/FAQ.md)
+10. [Demo](/docs/DEMO.md)

package/bin/geet.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "ERR at ${BASH_SOURCE[0]}:${LINENO}: $BASH_COMMAND" >&2' ERR
+
+NODE_BIN="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+GEET_LIB="$(cd -- "$NODE_BIN/../lib/node_modules/geet-geet/lib" && pwd)"
+GEET_ARGS=("$@")
+source "$GEET_LIB/digest-and-locate.sh" "$@"
+debug "GEET_ARGS=${GEET_ARGS[@]}"
+cmd="${1:-help}"
+
+
+shift || true
+
+case "$cmd" in
+  help|-h|--help)
+    source "$GEET_LIB/help.sh"
+    help
+    ;;
+
+  sync)
+    source "$GEET_LIB/sync.sh"
+    sync "${GEET_ARGS[@]:1}"
+    ;;
+
+  # Explicit non-git commands
+  init)
+    source "$GEET_LIB/init.sh"
+    init "${GEET_ARGS[@]:1}"
+    ;;
+
+  tree)
+    source "$GEET_LIB/tree.sh"
+    tree "${GEET_ARGS[@]:1}"
+    ;;
+
+  split)
+    source "$GEET_LIB/split.sh"
+    split "${GEET_ARGS[@]:1}"
+    ;;
+
+  session)
+    source "$GEET_LIB/session.sh"
+    session "${GEET_ARGS[@]:1}"
+    ;;
+
+  template)
+    source "$GEET_LIB/template.sh"
+    template "${GEET_ARGS[@]:1}"
+    ;;
+
+  doctor)
+    source "$GEET_LIB/doctor.sh"
+    doctor "${GEET_ARGS[@]:1}"
+    ;;
+
+  prework)
+    source "$GEET_LIB/prework.sh"
+    prework "${GEET_ARGS[@]:1}"
+    ;;
+
+  gh)
+    source "$GEET_LIB/ghcli.sh"
+    handle "${GEET_ARGS[@]:1}"
+    ;;
+
+  pub|publish)
+    GEET_ARGS=("${GEET_ARGS[@]:1}")
+    source "$GEET_LIB/ghcli.sh"
+    publish_cmd "${GEET_ARGS[@]}"
+    ;;
+
+  install)
+    source "$GEET_LIB/git.sh"
+    source "$GEET_LIB/install.sh"
+    GEET_ARGS=("${GEET_ARGS[@]:1}")
+    install "${GEET_ARGS[@]}"
+    ;;
+
+  soft-detach|soft_detach|slide)
+    source "$GEET_LIB/detach.sh"
+    soft_detach "${GEET_ARGS[@]:1}"
+    ;;
+
+  detach|hard-detach)
+    source "$GEET_LIB/detach.sh"
+    detach "${GEET_ARGS[@]:1}"
+    ;;
+
+  detached)
+      source "$GEET_LIB/detach.sh"
+      detached "${GEET_ARGS[@]:1}"
+      ;;
+
+  soft-detached|soft_detached|slid)
+        source "$GEET_LIB/detach.sh"
+        soft_detached "${GEET_ARGS[@]:1}"
+        ;;
+
+  retach)
+      source "$GEET_LIB/detach.sh"
+      retach "${GEET_ARGS[@]:1}"
+      ;;
+
+  precommit|pc)
+    source "$GEET_LIB/pre-commit/hook.sh"
+    ;;
+
+  remove|rm)
+    brave_guard "removing the template tracking" "Are you sure you want to call \`rm -rf \"$TEMPLATE_DIR\"\`?"
+    log "You asked for it! Deleting $TEMPLATE_DIR"
+    rm -rf "$TEMPLATE_DIR"
+    log "You have FULLY detached from the template and removed the git tracking of the template repo"
+    log "geet commands will now only work in the generic sense to create or init new projects, but will have no reference of the template repo"
+    ;;
+
+  destroy)
+    log "You asked for it! Deleting $TEMPLATE_DIR"
+    rm -rf "$TEMPLATE_DIR"
+    log "You have FULLY detached from the template and removed the git tracking of the template repo"
+    log "geet commands will now only work in the generic sense to create or init new projects, but will have no reference of the template repo"
+      ;;
+
+  bug|feature|issue|whoops|suggest)
+    source "$GEET_LIB/whoops.sh"
+    open_issue "${GEET_ARGS[@]:1}"
+    ;;
+
+  # Explicit escape hatch
+  git)
+    source "$GEET_LIB/git.sh"
+    call_cmd "${GEET_ARGS[@]:1}"
+    ;;
+
+  include)
+    source "$GEET_LIB/include.sh"
+    include "${GEET_ARGS[@]:1}"
+    ;;
+
+  ignored|included|excluded)
+    source "$GEET_LIB/ignored.sh"
+    echo "$(is_ignored "${GEET_ARGS[@]:1}")"
+    ;;
+
+  # Default: assume git subcommand
+  *)
+    source "$GEET_LIB/git.sh"
+    call_cmd "${GEET_ARGS[@]}"
+    ;;
+esac

package/docs/AUTO_PROMOTE.md

@@ -0,0 +1,173 @@
+# Advanced: File Promotion Pattern
+
+## The Problem
+
+When developing a template and app simultaneously in the same working directory, you may need different versions of certain files:
+
+- **App's `README.md`**: Explains your specific app
+- **Template's `README.md`**: Explains how to use the template
+
+Both need to be at the root:
+- App repo: `README.md` at root for your app's GitHub
+- Template repo: `README.md` at root for template's GitHub
+
+But you can't have two different `README.md` files in the same working directory!
+
+## The Solution: File Promotion
+
+**Promotion** means committing a file to the template repo at a different path than it exists in the working tree.
+
+**Example:**
+- Working tree: `.mytemplate/README.md` (template's README source)
+- Template repo tree: Both `README.md` AND `.mytemplate/README.md`
+- App repo: `README.md` (app's README, different content)
+
+When someone clones the template from GitHub, they get `README.md` at the root.
+
+## How It Works
+
+### Naming Convention (Future Feature)
+
+Files matching `*-{template-name}.*` auto-promote to the base name:
+
+```
+README-mytemplate.md    → promotes to README.md
+LICENSE-mytemplate.txt  → promotes to LICENSE.txt
+package-mytemplate.json → promotes to package.json
+```
+
+**Process:**
+1. Edit `README-mytemplate.md` in working tree
+2. Run `geet add README-mytemplate.md`
+3. Git stages it at BOTH locations in template repo:
+   - `README-mytemplate.md` (source)
+   - `README.md` (promoted)
+4. Commit to template
+5. GitHub shows `README.md` at root
+
+### Avoiding Merge Conflicts
+
+Promoted files use a custom merge strategy (`merge=keep-ours`):
+
+- Files sync normally when content is identical
+- On first divergence: auto-keeps working tree version
+- After divergence: files stop syncing (no conflicts!)
+
+This prevents the template's `README.md` from overwriting your app's `README.md` during pulls.
+
+**Learn more:** See [Git Merge Strategy: keep-ours](/docs/MERGE_KEEP_OURS.md) for detailed explanation and other use cases.
+
+## Current Implementation
+
+**As of now, only `README.md` uses promotion**, and it's set up automatically by `geet template`:
+
+- Creates `.mytemplate/README.md` (template README source)
+- Promotes to `README.md` in template repo
+- Sets `merge=keep-ours` to prevent conflicts
+- Creates pre-commit hook to auto-promote on future commits
+
+**Workflow after setup:**
+1. Edit `.mytemplate/README.md`
+2. Run `geet add .mytemplate/README.md`
+3. Run `geet commit -m "Update README"`
+4. **Pre-commit hook automatically promotes to `README.md`**
+5. Both versions get committed together
+
+## Extending the Pre-commit Hook
+
+The pre-commit hook created by `geet template` can be extended to promote additional files.
+
+**Location:** `.mytemplate/dot-git/hooks/pre-commit`
+
+**Example - promote LICENSE too:**
+
+```bash
+# Edit .mytemplate/dot-git/hooks/pre-commit
+# Add this section to the "USER CUSTOMIZATIONS" area:
+
+if git --git-dir="$DOTGIT" diff --cached --name-only | grep -q "^.$LAYER_NAME/LICENSE$"; then
+  license_path=".$LAYER_NAME/LICENSE"
+  if [[ -f "$license_path" ]]; then
+    hash=$(git --git-dir="$DOTGIT" hash-object -w "$license_path")
+    git --git-dir="$DOTGIT" update-index --add --cacheinfo 100644 "$hash" "LICENSE"
+    echo "[pre-commit] Auto-promoted $license_path → LICENSE"
+  fi
+fi
+```
+
+Then set merge strategy for LICENSE:
+```bash
+geet git config merge.keep-ours.driver "true"  # if not already set
+echo "LICENSE merge=keep-ours" >> .mytemplate/dot-git/info/attributes
+```
+
+## Manual Promotion (Advanced)
+
+If you need to promote files without the pre-commit hook:
+
+```bash
+# Stage file at original location
+geet add .mytemplate/LICENSE.md
+
+# Also stage it at promoted location
+hash=$(geet git hash-object -w .mytemplate/LICENSE.md)
+geet git update-index --add --cacheinfo 100644 "$hash" LICENSE.md
+
+# Prevent merge conflicts
+geet git config merge.keep-ours.driver "true"
+echo "LICENSE.md merge=keep-ours" >> .mytemplate/dot-git/info/attributes
+
+# Commit
+geet commit -m "Add LICENSE"
+```
+
+## When to Use
+
+✅ **Good use cases:**
+- `README.md` (essential for GitHub)
+- `LICENSE` (if template has different license than app)
+
+⚠️ **Use sparingly for:**
+- Config files (consider alternatives first)
+- Package manifests (can be confusing)
+
+❌ **Avoid for:**
+- Source code (use include/exclude instead)
+- Files that change frequently
+- Files with complex merge requirements
+
+## Alternatives
+
+**Simple approach (recommended for most files):**
+
+Store template files at their normal location:
+- `.mytemplate/docs/USAGE.md`
+- `.mytemplate/examples/`
+
+Users get them at these paths when cloning. No promotion needed.
+
+**Post-init hook:**
+
+Copy files during initialization:
+
+```bash
+# In .mytemplate/post-init.sh
+cp .mytemplate/README.md README.md
+```
+
+Works great if you don't need the file visible on GitHub before clone.
+
+## Trade-offs
+
+**Pros:**
+- ✅ Template repo looks complete on GitHub
+- ✅ Files at expected locations after clone
+- ✅ No merge conflicts
+
+**Cons:**
+- ⚠️ Adds complexity to git operations
+- ⚠️ Can confuse collaborators
+- ⚠️ Files exist at two paths in repo
+- ⚠️ Custom merge strategy might surprise people
+
+**Recommendation:** Use only when necessary, document clearly, prefer simpler alternatives when possible.

package/docs/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# 5. Contributing to geet
+
+## Development setup
+
+```bash
+# Clone the repo
+git clone https://github.com/modularizer/geet.git
+cd geet
+
+# The scripts are in lib/
+ls lib/
+
+# Test any script
+bash lib/doctor.sh help
+bash lib/ghcli.sh help
+```
+
+## Project structure
+
+```text
+geet/
+  lib/
+    cli.sh          # Main router
+    git.sh          # Git operations wrapper
+    init.sh         # Initialize layer
+    tree.sh         # Inspect layer contents
+    split.sh        # Export layer files
+    session.sh      # Isolated build helper
+    doctor.sh       # Health checks
+    gh.sh           # GitHub integration
+    template.sh     # Create new layer
+
+  bin/
+    geet.sh         # npm executable wrapper
+
+  geetinclude.sample   # Whitelist example
+  package.json         # npm package config
+```
+
+## Architecture principles
+
+**Single responsibility:** Each script does one thing well.
+
+**Composable:** Scripts call each other via explicit paths.
+
+**Portable:** Pure bash + git. No runtime dependencies (except `gh` for GitHub features).
+
+**Safe by default:** Dangerous operations require explicit flags.
+
+**Idempotent:** Running commands multiple times is safe.
+
+## Code style
+
+- Use `set -euo pipefail` at the top
+- Provide clear `die()` and `log()` helpers
+- Include comprehensive help text
+- Document non-obvious behavior
+- Validate inputs early
+- Fail fast with clear errors
+
+## Testing changes
+
+```bash
+# Run doctor to check for issues
+bash lib/doctor.sh
+
+# Test in a real project
+cd /path/to/test-project
+/path/to/geet/lib/cli.sh doctor
+```
+
+## Common tasks
+
+### Adding a new command
+
+1. Create `lib/mycommand.sh`
+2. Add to `lib/cli.sh` router
+3. Update help text
+4. Test thoroughly
+
+### Updating documentation
+
+- README.md for user-facing docs
+- Inline comments for complex logic
+- Help text in each script
+
+## Submitting changes
+
+1. **Fork the repo**
+2. **Create a branch:** `git checkout -b feature/my-feature`
+3. **Make changes** following code style
+4. **Test thoroughly** with `doctor` and real projects
+5. **Commit:** Clear, descriptive messages
+6. **Push:** `git push origin feature/my-feature`
+7. **Open PR** with description of changes
+
+## Feature requests
+
+Open an issue with:
+- Clear description of the problem
+- Proposed solution (if you have one)
+- Use cases / why it's needed
+
+## Bug reports
+
+Open an issue with:
+- What you did (exact commands)
+- What you expected
+- What actually happened
+- Output of `geet doctor`
+- geet version / git version
+
+## Questions
+
+For questions about:
+- **Using geet:** Open a discussion
+- **Template design:** Open a discussion
+- **Contributing:** Open an issue
+- **Bugs:** Open an issue
+
+---
+
+## Status
+
+This system is intentionally small, explicit, and evolvable.
+
+It will grow **only** when real workflows demand it.
+
+Core features:
+- ✅ Cloning templates
+- ✅ Init workflow
+- ✅ Layered templates
+- ✅ Include/exclude modes
+- ✅ Introspection tools
+- ✅ Export functionality
+- ✅ Build sessions
+- ✅ Safety rails
+- ✅ Post-init hooks
+- ✅ GitHub integration
+- ✅ Multi-layer support
+
+That's the core. Everything else is optional.

package/docs/DEMO.md

@@ -0,0 +1,131 @@
+# geet Demo
+
+This guide walks you through testing geet's core features in under 10 minutes.
+
+## Prerequisites
+
+```bash
+npm install -g geet-geet
+```
+
+---
+
+### Step 1: Create normal sample git repo
+There is nothing special about this repo. It has no clue it will become a geet template.
+```bash
+# Create a minimal Expo Router app template (5 tiny files)
+mkdir myapp
+cd myapp
+
+git init
+
+# Create app directory FIRST
+mkdir -p app/settings
+
+# 1) Expo Router layout (required)
+cat > app/_layout.tsx <<'EOF'
+import { Stack } from "expo-router";
+export default function Layout(){ return <Stack/>; }
+EOF
+
+# 2) Home screen
+cat > app/index.tsx <<'EOF'
+import { View, Text } from "react-native";
+export default ()=> <View><Text>Home</Text></View>;
+EOF
+
+# 3) About screen
+cat > app/about.tsx <<'EOF'
+import { View, Text } from "react-native";
+export default ()=> <View><Text>About</Text></View>;
+EOF
+
+# 4) Nested route
+cat > app/settings/index.tsx <<'EOF'
+import { View, Text } from "react-native";
+export default ()=> <View><Text>Settings</Text></View>;
+EOF
+
+# 5) Minimal Expo config (enables expo-router)
+cat > app.json <<'EOF'
+{ "expo": { "name":"my-template", "slug":"my-template", "plugins":["expo-router"] } }
+EOF
+
+cat > .gitignore <<'EOF'
+.idea/
+.claude/
+.vscode/
+EOF
+
+git add .
+git commit -m "Minimal Expo Router sample with multiple routes"
+```
+
+### Step 2: Initialize the template layer
+```bash
+#make a template git repo and publish to github
+geet template mytemplate "just a demo template" --private  # Note: if you omit --private we wont push to github, if you use --public or --internal it will use that visibility
+
+# Add some of the app files to the template layer (geet include modifies the .geetinclude then calls geet add)
+geet include "app/index.tsx" "app/_layout.tsx" "app/about.tsx"
+geet commit -m "Initial template layer"
+geet push
+```
+
+### Step 3: Use the template in a new app
+
+```bash
+cd ..
+# Clone and set up the template
+geet install <your-github-username>/mytemplate MyApp2 --private # Note: if you omit --private we wont push to github, if you use --public or --internal it will use that visibility
+```
+
+### Step 3: Customize your app (MyApp2)
+
+```bash
+cd MyApp2
+# Add app-specific files
+cat > app/welcome.tsx <<'EOF'
+import { View, Text } from "react-native";
+export default ()=> <View><Text>Welcome</Text></View>;
+EOF
+
+# Commit to your app repo (normal git)
+git add .
+git commit -m "Add custom home page"
+git push
+
+# Your custom files are NOT in the template
+geet status  # Should show clean (welcome.tsx is not in the template (yet) and is ignore by the template layer)
+git status   # Should show clean (welcome.tsx is in app)
+
+# validate welcome.tsx is not in the template
+geet included app/welcome.tsx
+geet ls-files | grep welcome
+```
+
+### Step 4: Update the template from MyApp2
+
+```bash
+# Later on if you want to add welcome.tsx to the template:
+geet include app/welcome.tsx
+geet commit -m "Add welcome page to template"
+geet push
+```
+
+### Step 5: Pull template updates in your app MyApp
+
+```bash
+# Back in your app
+cd ../MyApp
+
+# Pull template updates
+geet pull
+
+# The changes appear in your working tree
+git diff  # Shows welcome.tsx changed
+
+# Commit with normal git
+git commit -am "Pulled in an update to welcome.tsx made by the template repo"
+
+```