scripts: add option to dry-run (#11883)

scripts/set-alias-page.py

@@ -12,7 +12,7 @@ Note: If there is a symlink error when using the stage flag remove the `pages.en
 directory temporarily and try executing it again.
 
 Usage:
-    python3 scripts/set-alias-page.py [-p PAGE] [-s] [-S] [COMMAND]
+    python3 scripts/set-alias-page.py [-p PAGE] [-s] [-S] [-n] [COMMAND]
 
 Options:
     -p, --page PAGE
@@ -21,13 +21,20 @@ Options:
         Stage modified pages (requires 'git' on $PATH and TLDR_ROOT to be a Git repository).
     -S, --sync
         Synchronize each translation's alias page (if exists) with that of the English page.
+    -n, --dry-run
+        Show what changes would be made without actually modifying the page.
+
 
 Examples:
     1. Add 'vi' as an alias page of 'vim':
-    python3 scripts/set-alias-page.py -p common/vi vim
+       python3 scripts/set-alias-page.py -p common/vi vim
 
     2. Read English alias pages and synchronize them into all translations:
-    python3 scripts/set-alias-page.py -S
+       python3 scripts/set-alias-page.py -S
+
+    3. Read English alias pages and show what changes would be made:
+       python3 scripts/set-alias-page.py -Sn
+       python3 scripts/set-alias-page.py --sync --dry-run
 """
 
 import argparse
@@ -123,13 +130,14 @@ def get_alias_page(file):
     return ""
 
 
-def set_alias_page(file, command):
+def set_alias_page(file, command, dry_run=False):
     """
     Write an alias page to disk.
 
     Parameters:
     file (string): Path to an alias page
     command (string): The command that the alias stands for.
+    dry_run (bool): Whether to perform a dry-run.
 
     Returns:
     str: Execution status
@@ -151,45 +159,57 @@ def set_alias_page(file, command):
     orig_command = get_alias_page(file)
     if orig_command == command:
         return ""
-    elif orig_command == "":
-        status = "\x1b[36mpage added"
-    else:
-        status = "\x1b[34mpage updated"
 
-    alias_name = os.path.basename(file[:-3])
+    if orig_command == "":
-    text = (
+        status_prefix = "\x1b[36m"
-        templates[locale].replace("example", alias_name, 1).replace("example", command)
+        action = "added"
-    )
+    else:
-    os.makedirs(os.path.dirname(file), exist_ok=True)
+        status_prefix = "\x1b[34m"
-    with open(file, "w") as f:
+        action = "updated"
-        f.write(text)
+
+    if dry_run:
+        status = f"page will be {action}"
+    else:
+        status = f"page {action}"
+
+    status = f"{status_prefix}{status}\x1b[0m"
+
+    if not dry_run:  # Only write to the file during a non-dry-run
+        alias_name, _ = os.path.splitext(os.path.basename(file))
+        text = (
+            templates[locale]
+            .replace("example", alias_name, 1)
+            .replace("example", command)
+        )
+        os.makedirs(os.path.dirname(file), exist_ok=True)
+        with open(file, "w") as f:
+            f.write(text)
 
     return status
 
 
-def sync(root, pages_dirs, alias_name, orig_command):
+def sync(root, pages_dirs, alias_name, orig_command, dry_run=False):
     """
-    Synchronize an alias page into all translations:
+    Synchronize an alias page into all translations.
 
     Parameters:
     root (str): TLDR_ROOT
     pages_dirs (list of str): Strings of page entry and platform, e.g. "page.fr/common".
     alias_name (str): An alias command with .md extension like "vi.md".
     orig_command (string): An Original command like "vim".
+    dry_run (bool): Whether to perform a dry-run.
 
     Returns:
-    str: a list of paths to be staged into git, using by --stage option.
+    list: A list of paths to be staged into git, using by --stage option.
     """
-
     rel_paths = []
     for page_dir in pages_dirs:
         path = os.path.join(root, page_dir, alias_name)
-        status = set_alias_page(path, orig_command)
+        status = set_alias_page(path, orig_command, dry_run)
         if status != "":
             rel_path = path.replace(f"{root}/", "")
             rel_paths.append(rel_path)
             print(f"\x1b[32m{rel_path} {status}\x1b[0m")
-
     return rel_paths
 
 
@@ -219,6 +239,13 @@ def main():
         default=False,
         help="synchronize each translation's alias page (if exists) with that of English page",
     )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="show what changes would be made without actually modifying the pages",
+    )
     parser.add_argument("command", type=str, nargs="?", default="")
     args = parser.parse_args()
 
@@ -260,9 +287,12 @@ def main():
             for command in commands:
                 orig_command = get_alias_page(os.path.join(root, "pages", command))
                 if orig_command != "":
-                    rel_paths += sync(root, pages_dirs, command, orig_command)
+                    rel_paths += sync(
+                        root, pages_dirs, command, orig_command, args.dry_run
+                    )
 
-    if args.stage:
+    # Use '--stage' option
+    if args.stage and not args.dry_run:
         subprocess.call(["git", "add", *rel_paths], cwd=root)
 
 

scripts/set-more-info-link.py

@@ -10,7 +10,7 @@ of a clone of https://github.com/tldr-pages/tldr, and 'git' is available.
 If there is a symlink error when using the stage flag remove the `pages.en`
 directory temporarily and try executing it again.
 
-Usage: python3 scripts/set-more-info-link.py [-p PAGE] [-s] [-S] [LINK]
+Usage: python3 scripts/set-more-info-link.py [-p PAGE] [-s] [-S] [-n] [LINK]
 
 Supported Arguments:
     -p, --page    Specify the page name in the format "platform/command.md".
@@ -20,6 +20,7 @@ Supported Arguments:
     -S, --sync    Synchronize each translation's more information link (if
                   exists) with that of the English page. This is useful to
                   ensure consistency across translations.
+    -n, --dry-run Show what changes would be made without actually modifying the page.
 
 Positional Argument:
     LINK          The link to be set as the "More information" link.
@@ -34,6 +35,10 @@ Examples:
     3. Synchronize more information links across translations and stage modified pages for commit:
        python3 scripts/set-more-info-link.py -Ss
        python3 scripts/set-more-info-link.py --sync --stage
+
+    4. Show what changes would be made across translations:
+       python3 scripts/set-more-info-link.py -Sn
+       python3 scripts/set-more-info-link.py --sync --dry-run
 """
 
 import argparse
@@ -99,7 +104,7 @@ def get_tldr_root():
     sys.exit(1)
 
 
-def set_link(file, link):
+def set_link(file, link, dry_run=False):
     with open(file, encoding="utf-8") as f:
         lines = f.readlines()
 
@@ -135,17 +140,29 @@ def set_link(file, link):
         # return empty status to indicate that no changes were made
         return ""
 
+    status_prefix = "\x1b[36m"  # Color code for pages
+
     if re.search(r"^>.*<.+>", lines[desc_end]):
         # overwrite last line
         lines[desc_end] = new_line
-        status = "\x1b[34mlink updated"
+        status_prefix = "\x1b[34m"
+        action = "updated"
     else:
         # add new line
         lines.insert(desc_end + 1, new_line)
-        status = "\x1b[36mlink added"
+        status_prefix = "\x1b[36m"
+        action = "added"
 
-    with open(file, "w", encoding="utf-8") as f:
+    if dry_run:
-        f.writelines(lines)
+        status = f"link will be {action}"
+    else:
+        status = f"link {action}"
+
+    status = f"{status_prefix}{status}\x1b[0m"
+
+    if not dry_run:
+        with open(file, "w", encoding="utf-8") as f:
+            f.writelines(lines)
 
     return status
 
@@ -172,14 +189,14 @@ def get_link(file):
         return ""
 
 
-def sync(root, pages_dirs, command, link):
+def sync(root, pages_dirs, command, link, dry_run=False):
     rel_paths = []
     for page_dir in pages_dirs:
         path = os.path.join(root, page_dir, command)
         if os.path.exists(path):
             rel_path = path.replace(f"{root}/", "")
             rel_paths.append(rel_path)
-            status = set_link(path, link)
+            status = set_link(path, link, dry_run)
             if status != "":
                 print(f"\x1b[32m{rel_path} {status}\x1b[0m")
     return rel_paths
@@ -211,6 +228,13 @@ def main():
         default=False,
         help="synchronize each translation's more information link (if exists) with that of English page",
     )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="show what changes would be made without actually modifying the pages",
+    )
     parser.add_argument("link", type=str, nargs="?", default="")
     args = parser.parse_args()
 
@@ -264,9 +288,9 @@ def main():
             for command in commands:
                 link = get_link(os.path.join(root, "pages", command))
                 if link != "":
-                    rel_paths += sync(root, pages_dirs, command, link)
+                    rel_paths += sync(root, pages_dirs, command, link, args.dry_run)
 
-    if args.stage:
+    if args.stage and not args.dry_run:
         subprocess.call(["git", "add", *rel_paths], cwd=root)