Merge pull request #42 from mike-rambil/fix/mainContent

fix
2025-12-30 05:59:31 -06:00 · 2025-07-10 20:45:03 -05:00
parent 628500c5ff 5a5492f3b1
commit edec296c25
7 changed files with 756 additions and 14 deletions
--- a/contents/git-command-reference-full-list.md
+++ b/contents/git-command-reference-full-list.md
@@ -9,6 +9,70 @@
 A comprehensive list of Git commands used in this project, formatted according to our standard.


+---
+
+### Subcommands
+#### git init --bare
+Initialize a bare repository, typically used for remote repositories.
+
+#### Command
+```sh
+git init --bare my-repo.git
+```
+
+#### Examples
+- **Create a bare repository for collaboration.**
+
+
+```sh
+git init --bare my-repo.git
+```
+
+
+#### Steps
+1. Run `git init --bare my-repo.git` to create a bare repository.
+
+
+#### Tags
+`init`, `bare`, `repository`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### git clone --mirror <repository>
+Clone a repository in mirror mode, including all refs and branches.
+
+#### Command
+```sh
+git clone --mirror https://github.com/example/repo.git
+```
+
+#### Examples
+- **Create a full backup or migration of a repository.**
+
+
+```sh
+git clone --mirror https://github.com/example/repo.git
+```
+
+
+#### Steps
+1. Run `git clone --mirror <repository>` to create a full backup or migration.
+
+
+#### Tags
+`clone`, `mirror`, `backup`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: reference, all-commands_
--- a/contents/how-to-use-git-worktree-safely.md
+++ b/contents/how-to-use-git-worktree-safely.md
@@ -9,6 +9,181 @@
 `git worktree` allows you to manage multiple working directories linked to a single Git repository. It helps developers work on multiple branches simultaneously without switching branches in the same directory.


+---
+
+### Subcommands
+#### Check Existing Worktrees
+
+#### Command
+```sh
+git worktree list
+```
+
+#### Examples
+- **List all active worktrees.**
+
+
+```sh
+git worktree list
+```
+
+
+#### Steps
+1. List all active worktrees.
+
+
+#### Tags
+`worktree`, `list`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Create a New Worktree
+
+#### Command
+```sh
+git worktree add <path> <branch>
+```
+
+#### Examples
+- **Create a new worktree for the feature branch.**
+
+
+```sh
+git worktree add ../feature-branch feature
+```
+
+
+#### Steps
+1. Create a worktree linked to a specific branch.
+
+
+#### Prerequisites
+- The target path must not already be a git repository.
+
+
+#### Tags
+`worktree`, `add`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Remove a Worktree
+
+#### Command
+```sh
+git worktree remove <worktree-path>
+```
+
+#### Examples
+- **Detach a worktree without deleting the files.**
+
+
+```sh
+git worktree remove ../feature-branch
+```
+
+
+#### Steps
+1. Detach a worktree without deleting the files.
+
+
+#### Warnings
+- ⚠️ Make sure you have committed all changes before removing a worktree.
+
+
+#### Tags
+`worktree`, `remove`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Switch Between Worktrees
+
+#### Command
+`cd <worktree-path>`
+
+#### Examples
+- **Switch to the worktree directory.**
+
+
+```sh
+cd ../feature-branch
+```
+
+
+#### Steps
+1. Simply cd into the worktree directory to switch.
+
+
+#### Tags
+`worktree`, `switch`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Use Worktrees for Temporary Fixes
+
+#### Command
+```sh
+git worktree add ../hotfix hotfix-branch
+```
+
+#### Examples
+- **Quickly apply a fix on another branch without leaving your main branch.**
+
+
+```sh
+git worktree add ../hotfix hotfix-branch
+```
+
+
+#### Steps
+1. Quickly apply a fix on another branch without leaving your main branch.
+
+
+#### Tags
+`worktree`, `hotfix`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Flags and Their Uses
+
+#### Flags
+- `add`: Creates a new worktree for an existing branch.
+- `-b`: Creates a new worktree with a new branch.
+- `list`: Lists all active worktrees.
+- `remove`: Detaches a worktree from the repo without deleting files.
+- `prune`: Cleans up stale worktree references after manual deletion.
+- `move`: Moves a worktree to a different location.
+
+
+#### Tags
+`worktree`, `flags`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: worktree, branches, advanced_
--- a/contents/miscellaneous-orphaned-git-commands.md
+++ b/contents/miscellaneous-orphaned-git-commands.md
@@ -9,6 +9,154 @@
 This file collects useful Git commands and scripts that were previously only in the README and not referenced elsewhere in this repository.


+---
+
+### Subcommands
+#### git maintenance start
+Runs a cronJob in background for the specified repo for periodic maintenance.
+
+#### Command
+```sh
+git maintenance start
+```
+
+#### Examples
+- **Enable background maintenance for your repository.**
+
+
+```sh
+git maintenance start
+```
+
+
+#### Steps
+1. Run `git maintenance start` in your repository.
+
+
+#### Links
+- [Official Docs](https://git-scm.com/docs/git-maintenance)
+
+
+#### Tags
+`maintenance`, `automation`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### git request-pull
+Generate a request to pull changes into a repository.
+
+#### Command
+```sh
+git request-pull <start> <url> <end>
+```
+
+#### Examples
+- **Generate a pull request message from v1.0 to v1.1.**
+
+
+```sh
+git request-pull v1.0 https://github.com/example/repo.git v1.1
+```
+
+
+#### Steps
+1. Run `git request-pull <start> <url> <end>` to generate a pull request message.
+
+
+#### Links
+- [Official Docs](https://git-scm.com/docs/git-request-pull)
+
+
+#### Tags
+`collaboration`, `pull-request`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### View and Clean Up Local Git Branches (Bash)
+Scripts to view and clean up local branches using Bash.
+
+#### Examples
+- **List local branches without a remote connection.**
+
+
+```sh
+git branch -vv | grep -E '^\s*\S+\s+[^\[]+$'
+```
+- **Delete local branches without remote tracking.**
+
+
+```sh
+git branch -vv | grep -E '^\s*\S+\s+[^\[]+$' | awk '{print $1}' | xargs git branch -D
+```
+
+
+#### Steps
+1. List local branches.
+2. Delete local branches without remote.
+3. View branches with deleted remote.
+4. Delete stale local branches.
+
+
+#### Warnings
+- ⚠️ Deleting branches is irreversible. Double-check before running destructive commands.
+
+
+#### Tags
+`branches`, `cleanup`, `bash`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### View and Clean Up Local Git Branches (PowerShell)
+Scripts to view and clean up local branches using PowerShell.
+
+#### Examples
+- **List local branches without a remote connection.**
+
+
+```sh
+git branch -vv | Select-String -NotMatch "origin/"
+```
+- **Delete local branches without remote tracking.**
+
+
+```sh
+git branch -vv | Select-String -NotMatch "origin/" | ForEach-Object { $branch = ($_ -split "\s+")[1]; git branch -D $branch }
+```
+
+
+#### Steps
+1. List local branches.
+2. Delete local branches without remote.
+3. View branches with deleted remote.
+4. Delete stale local branches.
+
+
+#### Warnings
+- ⚠️ Deleting branches is irreversible. Double-check before running destructive commands.
+
+
+#### Tags
+`branches`, `cleanup`, `powershell`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: misc, cleanup, advanced_
--- a/contents/past-commits-of-a-specific-file.md
+++ b/contents/past-commits-of-a-specific-file.md
@@ -9,6 +9,139 @@
 You can see all commits related to a specific file using Git commands. Here are a few ways to do it:


+---
+
+### Subcommands
+#### Show Commit History of a Specific File
+
+#### Command
+```sh
+git log --oneline -- filename.txt
+```
+
+#### Examples
+- **List all commits that modified `filename.txt`.**
+
+
+```sh
+git log --oneline -- filename.txt
+```
+
+
+#### Steps
+1. Lists all commits that modified `filename.txt`.
+
+
+#### Tags
+`log`, `file`, `history`
+
+#### Related Commands
+- git log -p -- filename.txt
+- git blame filename.txt
+
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Show Detailed Commit History (With Changes)
+
+#### Command
+```sh
+git log -p -- filename.txt
+```
+
+#### Examples
+- **Show each commit and the actual changes made to `filename.txt`.**
+
+
+```sh
+git log -p -- filename.txt
+```
+
+
+#### Steps
+1. Shows each commit and the actual changes made to `filename.txt`.
+
+
+#### Tags
+`log`, `diff`, `file`
+
+#### Related Commands
+- git log --oneline -- filename.txt
+
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Show Commit History With Author and Date
+
+#### Command
+```sh
+git log --pretty=format:"%h - %an, %ar : %s" -- filename.txt
+```
+
+#### Examples
+- **Display commit hash, author, relative date, and commit message.**
+
+
+```sh
+git log --pretty=format:"%h - %an, %ar : %s" -- filename.txt
+```
+
+
+#### Steps
+1. Displays commit hash, author, relative date, and commit message.
+
+
+#### Tags
+`log`, `author`, `date`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### See Who Last Modified Each Line (Blame)
+
+#### Command
+```sh
+git blame filename.txt
+```
+
+#### Examples
+- **Show the last commit that changed each line of the file.**
+
+
+```sh
+git blame filename.txt
+```
+
+
+#### Steps
+1. Shows the last commit that changed each line of the file.
+
+
+#### Warnings
+- ⚠️ Blame can be misleading if the file has been heavily refactored.
+
+
+#### Tags
+`blame`, `file`, `history`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: history, inspection, file_
--- a/contents/sharing-changes-as-patch-files.md
+++ b/contents/sharing-changes-as-patch-files.md
@@ -9,6 +9,161 @@
 How to create patch files from your changes for sharing via email, SCP, Slack, or other means. Covers both committed (with full commit metadata) and uncommitted changes.


+---
+
+### Subcommands
+#### Create Patch from Last Commit(s)
+
+#### Command
+```sh
+git format-patch HEAD~1
+```
+
+#### Examples
+- **Create a .patch file for the last commit.**
+
+
+```sh
+git format-patch HEAD~1
+```
+- **Create a single patch file for all commits on top of main.**
+
+
+```sh
+git format-patch origin/main..HEAD --stdout > my-changes.patch
+```
+
+
+#### Steps
+1. Run '`git format-patch HEAD~1' to create a patch for the last commit`.
+2. Use '`git format-patch origin/main..HEAD --stdout > my-changes.patch' to create a single patch file for multiple commits`.
+
+
+#### Warnings
+- ⚠️ Patch files created this way include commit messages, authorship, and timestamps.
+- ⚠️ Use 'git am' to apply these patches on another system.
+
+
+#### Links
+- [Official Docs](https://git-scm.com/docs/git-format-patch)
+
+
+#### Tags
+`patch`, `format-patch`, `committed`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Apply Patch with Commit Metadata
+
+#### Command
+```sh
+git am my-changes.patch
+```
+
+#### Examples
+- **Apply a patch file and preserve commit info.**
+
+
+```sh
+git am my-changes.patch
+```
+
+
+#### Steps
+1. Run '`git am my-changes.patch' to apply the patch and preserve commit messages, authorship, and timestamps`.
+
+
+#### Tags
+`patch`, `am`, `apply`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Create Patch from Uncommitted Changes
+
+#### Command
+```sh
+git diff > changes.diff
+```
+
+#### Examples
+- **Create a diff file of uncommitted changes.**
+
+
+```sh
+git diff > changes.diff
+```
+
+
+#### Steps
+1. Run '`git diff > changes.diff' to save uncommitted changes to a file`.
+
+
+#### Warnings
+- ⚠️ This does NOT preserve commit metadata or history—just raw changes.
+
+
+#### Links
+- [Official Docs](https://git-scm.com/docs/git-diff)
+
+
+#### Tags
+`diff`, `uncommitted`, `snapshot`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Apply Diff File
+
+#### Command
+```sh
+git apply changes.diff
+```
+
+#### Examples
+- **Apply a diff file of uncommitted changes.**
+
+
+```sh
+git apply changes.diff
+```
+
+
+#### Steps
+1. Run '`git apply changes.diff' to apply the changes from a diff file`.
+
+
+#### Tags
+`diff`, `apply`, `uncommitted`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+#### Patch vs Diff: Quick Reference
+
+#### Tags
+`patch`, `diff`, `reference`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: patch, diff, sharing, email, collaboration_
--- a/contents/useful-rare-git-commands-you-never-heard-of.md
+++ b/contents/useful-rare-git-commands-you-never-heard-of.md
@@ -9,6 +9,40 @@
 A collection of lesser-known but powerful Git commands. Use these to level up your Git workflow!


+---
+
+### Subcommands
+#### git replace <old-commit> <new-commit>
+Temporarily substitute one commit for another.
+
+#### Command
+```sh
+git replace abc123 def456
+```
+
+#### Examples
+- **Temporarily replace commit abc123 with def456.**
+
+
+```sh
+git replace abc123 def456
+```
+
+
+#### Steps
+1. Run `git replace <old-commit> <new-commit>` to test or patch history.
+
+
+#### Tags
+`replace`, `history`
+
+#### Author
+mike-rambil
+
+#### Last Updated
+2024-06-10
+
+
 ---

 _Author: mike-rambil • Updated: 2024-06-10 • Tags: rare, advanced, tips_
--- a/scripts/generate-readme.js
+++ b/scripts/generate-readme.js
@@ -218,24 +218,58 @@ function conciseMetaLine(author, lastUpdated, tags) {
  return meta.length ? `\n---\n\n_${meta.join(' • ')}_\n` : '';
 }

+function generateMiniSubtocTOC(obj) {
+  if (!obj.subtoc || !obj.subtoc.length) return '';
+  let out = '## Subcommands\n';
+  obj.subtoc.forEach((sub) => {
+    out += `- [${sub.Name}](./${slugify(sub.Name)}.md)`;
+    if (sub.short_description) out += `: ${sub.short_description}`;
+    out += '\n';
+  });
+  return out + '\n';
+}
+
+function hasOnlySubtocContent(obj) {
+  // Returns true if the main file has no meaningful content except subtoc
+  return !(
+    obj.long_description ||
+    obj.command ||
+    obj.flags ||
+    obj.examples ||
+    obj['command similiar examples'] ||
+    obj.steps ||
+    obj.prerequisites ||
+    obj.warnings ||
+    obj.links ||
+    obj.related_commands ||
+    obj.output_example
+  );
+}
+
 function generateContentFile(obj, idx, tocData) {
  let slug = slugify(obj.Name);
  let md = `[⬅️ Back to Table of Contents](../README.md#${slug})\n\n`;
  md += `# ${obj.Name}\n\n`;
  if (obj.category) md += renderCategory(obj.category);
  if (obj.short_description) md += `> ${obj.short_description}\n\n`;
-  if (obj.long_description) md += `${obj.long_description}\n\n`;
-  if (obj.command) md += renderCommand(obj.command);
-  if (obj.flags) md += renderFlags(obj.flags);
-  if (obj.examples) md += renderExamples(obj.examples);
-  if (obj['command similiar examples'])
-    md += renderCommandExamples(obj['command similiar examples']);
-  if (obj.steps) md += renderSteps(obj.steps);
-  if (obj.prerequisites) md += renderPrerequisites(obj.prerequisites);
-  if (obj.warnings) md += renderWarnings(obj.warnings);
-  if (obj.links) md += renderLinks(obj.links);
-  if (obj.related_commands) md += renderRelatedCommands(obj.related_commands);
-  if (obj.output_example) md += renderOutputExample(obj.output_example);
+  // If only subtoc, add mini-TOC
+  if (obj.subtoc && obj.subtoc.length && hasOnlySubtocContent(obj)) {
+    md += generateMiniSubtocTOC(obj);
+  } else {
+    if (obj.long_description) md += `${obj.long_description}\n\n`;
+    if (obj.command) md += renderCommand(obj.command);
+    if (obj.flags) md += renderFlags(obj.flags);
+    if (obj.examples) md += renderExamples(obj.examples);
+    if (obj['command similiar examples'])
+      md += renderCommandExamples(obj['command similiar examples']);
+    if (obj.steps) md += renderSteps(obj.steps);
+    if (obj.prerequisites) md += renderPrerequisites(obj.prerequisites);
+    if (obj.warnings) md += renderWarnings(obj.warnings);
+    if (obj.links) md += renderLinks(obj.links);
+    if (obj.related_commands) md += renderRelatedCommands(obj.related_commands);
+    if (obj.output_example) md += renderOutputExample(obj.output_example);
+  }
+  if (obj.subtoc) md += renderSubtoc(obj.subtoc);
  md += conciseMetaLine(obj.author, obj.last_updated, obj.tags);
  return md;
 }
@@ -271,9 +305,8 @@ function main() {
      obj.subtoc.forEach((sub, subIdx) => {
        const subPath = path.join(CONTENTS_DIR, `${slugify(sub.Name)}.md`);
        let subMd = '';
-        // Back to parent
+        // Always add Back to parent
        subMd += `[⬅️ Back to ${obj.Name}](./${slugify(obj.Name)}.md)\n\n`;
-        // Previous step
        if (subIdx > 0) {
          const prev = obj.subtoc[subIdx - 1];
          subMd += `[⬆️ Previous Step: ${prev.Name}](./${slugify(