diff --git a/dev-docs/FORMAT.md b/dev-docs/FORMAT.md index 9966e11..11b9cca 100644 --- a/dev-docs/FORMAT.md +++ b/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 diff --git a/scripts/generate-readme.js b/scripts/generate-readme.js index 92448f0..50eb95f 100644 --- a/scripts/generate-readme.js +++ b/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); diff --git a/toc-source.json b/toc-source.json index 50ef092..9c21d02 100644 --- a/toc-source.json +++ b/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." + ] } ] },