feat: add ProTips section to toc-source.json and update FORMAT.md for documentation

dev-docs/FORMAT.md

@@ -76,6 +76,11 @@ This project uses a structured format for documenting Git commands, which is sto
 - **Type:** list of strings (optional)
 - **Description:** Important cautions or risks.
 
+## ProTips
+
+- **Type:** list of strings (optional)
+- **Description:** Short, actionable tips to help users be more successful with this command. Use 1–2 lines per tip. Example: "Use `-n` for a dry run before deleting files."
+
 ## Tags
 
 - **Type:** list of strings
@@ -143,6 +148,11 @@ This project uses a structured format for documenting Git commands, which is sto
 - This will permanently delete files! Always use `-n` before `-f`.
 - Be cautious with `-x` and `-X` as they remove ignored files, which might include config files.
 
+**ProTips:**
+
+- Use `git clean -n` to preview what will be deleted before running with `-f`.
+- Combine with `-d` to also remove untracked directories.
+
 **Tags:** clean, untracked, workspace  
 **Author:** mike-rambil  
 **Last Updated:** 2024-06-10

scripts/generate-readme.js

@@ -131,6 +131,15 @@ function renderWarnings(warnings) {
   return renderSection('Warnings', out);
 }
 
+function renderProTips(protips) {
+  if (!protips || !protips.length) return '';
+  let out = '';
+  protips.forEach((tip) => {
+    out += `> [!TIP]\n> ${tip}\n\n`;
+  });
+  return renderSection('ProTips', out);
+}
+
 function renderTags(tags) {
   if (!tags || !tags.length) return '';
   return renderSection('Tags', tags.map((t) => `\`${t}\``).join(', '));
@@ -199,6 +208,7 @@ function renderSubtoc(subtoc) {
     if (sub.steps) out += renderSteps(sub.steps);
     if (sub.prerequisites) out += renderPrerequisites(sub.prerequisites);
     if (sub.warnings) out += renderWarnings(sub.warnings);
+    if (sub.protips) out += renderProTips(sub.protips);
     if (sub.links) out += renderLinks(sub.links);
     if (sub.tags) out += renderTags(sub.tags);
     if (sub.related_commands)
@@ -246,6 +256,7 @@ function generateContentFile(obj, idx, tocData) {
   if (obj.steps) md += renderSteps(obj.steps);
   if (obj.prerequisites) md += renderPrerequisites(obj.prerequisites);
   if (obj.warnings) md += renderWarnings(obj.warnings);
+  if (obj.protips) md += renderProTips(obj.protips);
   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);
@@ -307,6 +318,7 @@ function main() {
         if (sub.steps) subMd += renderSteps(sub.steps);
         if (sub.prerequisites) subMd += renderPrerequisites(sub.prerequisites);
         if (sub.warnings) subMd += renderWarnings(sub.warnings);
+        if (sub.protips) subMd += renderProTips(sub.protips);
         if (sub.links) subMd += renderLinks(sub.links);
         if (sub.related_commands)
           subMd += renderRelatedCommands(sub.related_commands);

toc-source.json

@@ -7,6 +7,10 @@
     "tags": ["misc", "cleanup", "advanced"],
     "author": "mike-rambil",
     "last_updated": "2024-06-10",
+    "protips": [
+      "Try these commands in a test repo before using them on important projects.",
+      "Bookmark this section for quick reference to hidden gems."
+    ],
     "subtoc": [
       {
         "Name": "git maintenance start",
@@ -28,7 +32,11 @@
         ],
         "tags": ["maintenance", "automation"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Set up maintenance on large repos to keep them fast.",
+          "Use with cron or scheduled tasks for automation."
+        ]
       },
       {
         "Name": "git request-pull",
@@ -52,7 +60,11 @@
         ],
         "tags": ["collaboration", "pull-request"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Use request-pull to generate a summary for code reviews.",
+          "Include a clear start and end point for clarity."
+        ]
       }
     ]
   },
@@ -63,6 +75,10 @@
     "tags": ["branches", "cleanup", "fast", "bash", "powershell"],
     "author": "mike-rambil",
     "last_updated": "2024-06-10",
+    "protips": [
+      "Run 'git fetch -p' before cleaning up branches to update remote info.",
+      "Always double-check which branches will be deleted."
+    ],
     "subtoc": [
       {
         "Name": "Delete Local Branches Whose Remote is Gone (Bash)",
@@ -87,7 +103,11 @@
         ],
         "tags": ["branches", "cleanup", "gone", "bash"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Use this after deleting branches on the remote to keep your local repo tidy.",
+          "Add 'echo' before 'git branch -d' to preview what will be deleted."
+        ]
       },
       {
         "Name": "Delete Local Branches Whose Remote is Gone (PowerShell)",
@@ -112,7 +132,11 @@
         ],
         "tags": ["branches", "cleanup", "gone", "powershell"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Great for Windows users to automate branch cleanup.",
+          "Review the list before confirming deletion."
+        ]
       },
       {
         "Name": "View and Clean Up Local Git Branches (Bash)",
@@ -139,7 +163,11 @@
         ],
         "tags": ["branches", "cleanup", "bash"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Use 'git branch -vv' to see tracking info for all branches.",
+          "Pipe to 'awk' and 'xargs' for batch deletion."
+        ]
       },
       {
         "Name": "View and Clean Up Local Git Branches (PowerShell)",
@@ -166,7 +194,11 @@
         ],
         "tags": ["branches", "cleanup", "powershell"],
         "author": "mike-rambil",
-        "last_updated": "2024-06-10"
+        "last_updated": "2024-06-10",
+        "protips": [
+          "Use PowerShell's 'Select-String' for flexible filtering.",
+          "Automate cleanup with a script for regular maintenance."
+        ]
       }
     ]
   },