Add helper and fix wording

Signed-off-by: Wei-Chun, Chang <[email protected]>

piperider_cli/cli.py

@@ -430,7 +430,7 @@ def cloud_compare_reports(**kwargs):
 
 
 @cli.command(name='compare', short_help='Compare the change for the current branch.', cls=TrackCommand)
-@click.argument('ref-diff', required=False, type=click.STRING)
+@click.argument('ref', required=False, type=click.STRING)
 @click.option('--recipe', default=None, type=click.STRING, help='Select a different recipe.')
 @click.option('--upload', default=False, is_flag=True, help='Upload the report to PipeRider Cloud.')
 @click.option('--share', default=False, is_flag=True, help='Enable public share of the report to PipeRider Cloud.')
@@ -451,13 +451,33 @@ def cloud_compare_reports(**kwargs):
 ])
 @add_options(dbt_related_options)
 @add_options(debug_option)
-def compare_with_recipe(ref_diff, **kwargs):
+def compare_with_recipe(ref, **kwargs):
     """
     Generate the comparison report for your branch.
+
+    \b
+    # compare with main/master branch
+    piperider compare
+
+    \b
+    # compare with specific branch
+    piperider compare --base-branch <branch>
+
+    \b
+    # compare with any reference
+    piperider compare <git-ref>
+
+    \b
+    # compare with two references
+    piperider compare <git-ref>...<git-ref>
+
+    \b
+    Note: <git-ref> can be reference that git understands. e.g., branch, tag, commit, etc.
+
     """
 
     from piperider_cli.cli_utils.compare_with_recipe import compare_with_recipe as cmd
-    return cmd(ref_diff, **kwargs)
+    return cmd(ref, **kwargs)
 
 
 @cloud.command(short_help='Signup to PipeRider Cloud.', cls=TrackCommand)

piperider_cli/cli_utils/compare_with_recipe.py

@@ -1,29 +1,30 @@
 from rich.console import Console
 
 
-def parse_compare_ref(refs: str):
+def parse_compare_ref(ref: str):
     console = Console()
 
-    if refs is None:
+    if ref is None:
         return None, None
 
-    if '...' in refs:
-        base_ref = refs.split('...')[0]
-        target_ref = refs.split('...')[1]
+    if '...' in ref:
+        base_ref = ref.split('...')[0]
+        target_ref = ref.split('...')[1]
         if base_ref == '' or target_ref == '':
-            console.print('[bold red]Error:[/bold red] Commit format is not supported')
+            console.print('[bold red]Error:[/bold red] '
+                          'Please either provide a single git reference or a 3-dot diff comparison form.')
             return None, None
-    elif '..' in refs:
+    elif '..' in ref:
         console.print('[bold red]Error:[/bold red] Two-dot diff comparisons are not supported')
         return None, None
     else:
-        base_ref = refs
+        base_ref = ref
         target_ref = None
 
     return base_ref, target_ref
 
 
-def compare_with_recipe(ref_diff, **kwargs):
+def compare_with_recipe(ref, **kwargs):
     """
     Generate the comparison report for your branch.
     """
@@ -48,13 +49,13 @@ def compare_with_recipe(ref_diff, **kwargs):
     modified = kwargs.get('modified')
     skip_datasource_connection = kwargs.get('skip_datasource')
 
-    base_ref, target_ref = parse_compare_ref(ref_diff)
-    if ref_diff is not None and base_ref is None:
+    base_ref, target_ref = parse_compare_ref(ref)
+    if ref is not None and base_ref is None:
         return -1
 
     if base_ref is not None and kwargs.get('base_branch') is not None:
         console.print("[bold red]Error:[/bold red] "
-                      "'--base-branch' option and '[REF-DIFF]' argument cannot be used together")
+                      "'--base-branch' option and '[REF]' argument cannot be used together")
         return -1
     elif base_ref is None:
         base_ref = kwargs.get('base_branch')