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])
-    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)
+    if orig_command == "":
+        status_prefix = "\x1b[36m"
+        action = "added"
+    else:
+        status_prefix = "\x1b[34m"
+        action = "updated"
+
+    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)