feat: rename --branch to --revision

Future-proofing atlas to support sha-commits and other git revisions. The `--branch` flag is still supported till it's removed in the next major version.
openedx · Jan 17, 2024 · b16f4f1 · b16f4f1
1 parent b6e26c2
commit b16f4f1
Show file tree

Hide file tree

Showing 7 changed files with 92 additions and 56 deletions.
diff --git a/README.rst b/README.rst
@@ -67,7 +67,7 @@ regularly and useful to understand ``atlas`` at a glance.
 
         pull:
           repository: <organization-name>/<repository-name>
-          branch: <branch-name>
+          revision: <git-revision>
           directory: <repo-directory-name>:<local-dir-name> ...
           filter: <pattern> ...
           expand_glob: 0
@@ -96,8 +96,10 @@ regularly and useful to understand ``atlas`` at a glance.
         `-r` or `--repository`:
             slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
 
-        `-b` or `--branch`:
-            Branch to pull from. Defaults to 'main'
+        `-n` or `--revision`:
+            Git revision to pull from. Currently only branches and tags are supported. Defaults to 'main'.
+
+            This option name used to be `-b` or `--branch`. The deprecated name will be removed in a future release.
 
         `-f` or `--filter`:
            A comma-separated (or space-separated) list of patterns match files and sub-directories.

diff --git a/atlas b/atlas
@@ -17,7 +17,7 @@ Configuration file:
 
     pull:
       repository: <organization-name>/<repository-name>
-      branch: <branch-name>
+      revision: <git-revision>
       directory: <repo-directory-name>:<local-dir-name> ...
       filter: <pattern> ...
       expand_glob: 0
@@ -46,8 +46,10 @@ Options:
     \`-r\` or \`--repository\`:
         slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
 
-    \`-b\` or \`--branch\`:
-        Branch to pull from. Defaults to 'main'
+    \`-n\` or \`--revision\`:
+        Git revision to pull from. Currently only branches and tags are supported. Defaults to 'main'.
+
+        This option name used to be \`-b\` or \`--branch\`. The deprecated name will be removed in a future release.
 
     \`-f\` or \`--filter\`:
        A comma-separated (or space-separated) list of patterns match files and sub-directories.
@@ -92,13 +94,13 @@ parser_definition_pull() {
 	setup   PULL_REST help:usage_pull -- \
 		"Usage: atlas pull [options...] [directory mappings...]"
 	msg -- 'Options:'
-	param		CONFIG			--config			    -- "path to alternative atlas.yaml configuration file"
-	param		BRANCH		    -b	--branch			-- "A branch of translation files"
-	param		REPOSITORY	    -r	--repository		-- "The repository containing translation files"
-	param		FILTER	        -f	--filter			-- "List of patterns to select which files and sub-directories to checkout."
-	flag		EXPAND_GLOB     -g	--expand-glob       -- "Expand glob pattern e.g. 'atlas pull translations/*/done' to 'atlas pull translations/DoneXBlock/done' if it exists."
-	flag		VERBOSE		    -v	--verbose			-- "verbose output to terminal"
-	flag		SILENT		    -s	--silent			-- "no output to terminal"
+	param		CONFIG			--config			        -- "path to alternative atlas.yaml configuration file"
+	param		REPOSITORY	    -r	--repository		    -- "The repository containing translation files"
+	param		REVISION		-n --revision -b --branch   -- "A git revision of the repository to pull from. The name --branch is deprecated in favor of --revision."
+	param		FILTER	        -f	--filter			    -- "List of patterns to select which files and sub-directories to checkout."
+	flag		EXPAND_GLOB     -g	--expand-glob           -- "Expand glob pattern e.g. 'atlas pull translations/*/done' to 'atlas pull translations/DoneXBlock/done' if it exists."
+	flag		VERBOSE		    -v	--verbose			    -- "verbose output to terminal"
+	flag		SILENT		    -s	--silent			    -- "no output to terminal"
 	disp    :usage_pull  -h --help
 }
 # @end
@@ -168,7 +170,7 @@ Configuration file:
 
     pull:
       repository: <organization-name>/<repository-name>
-      branch: <branch-name>
+      revision: <git-revision>
       directory: <repo-directory-name>:<local-dir-name> ...
       filter: <pattern> ...
       expand_glob: 0
@@ -197,8 +199,10 @@ Options:
     `-r` or `--repository`:
         slug of the GitHub repository to pull from. Defaults 'openedx/openedx-translations'.
 
-    `-b` or `--branch`:
-        Branch to pull from. Defaults to 'main'
+    `-n` or `--revision`:
+        Git revision to pull from. Currently only branches and tags are supported. Defaults to 'main'.
+
+        This option name used to be `-b` or `--branch`. The deprecated name will be removed in a future release.
 
     `-f` or `--filter`:
        A comma-separated (or space-separated) list of patterns match files and sub-directories.
@@ -246,8 +250,8 @@ GETOPTIONSHERE
 # Generated by getoptions (BEGIN)
 # URL: https://github.com/ko1nksm/getoptions (v3.3.0)
 CONFIG=''
-BRANCH=''
 REPOSITORY=''
+REVISION=''
 FILTER=''
 EXPAND_GLOB=''
 VERBOSE=''
@@ -261,7 +265,7 @@ parse_pull() {
         eval 'set -- "${OPTARG%%\=*}" "${OPTARG#*\=}"' ${1+'"$@"'}
         ;;
       --no-*|--without-*) unset OPTARG ;;
-      -[brf]?*) OPTARG=$1; shift
+      -[rnbf]?*) OPTARG=$1; shift
         eval 'set -- "${OPTARG%"${OPTARG#??}"}" "${OPTARG#??}"' ${1+'"$@"'}
         ;;
       -[gvsh]?*) OPTARG=$1; shift
@@ -274,15 +278,15 @@ parse_pull() {
         OPTARG=$2
         CONFIG="$OPTARG"
         shift ;;
-      '-b'|'--branch')
+      '-r'|'--repository')
         [ $# -le 1 ] && set "required" "$1" && break
         OPTARG=$2
-        BRANCH="$OPTARG"
+        REPOSITORY="$OPTARG"
         shift ;;
-      '-r'|'--repository')
+      '-n'|'--revision'|'-b'|'--branch')
         [ $# -le 1 ] && set "required" "$1" && break
         OPTARG=$2
-        REPOSITORY="$OPTARG"
+        REVISION="$OPTARG"
         shift ;;
       '-f'|'--filter')
         [ $# -le 1 ] && set "required" "$1" && break
@@ -337,8 +341,9 @@ cat<<'GETOPTIONSHERE'
 Usage: atlas pull [options...] [directory mappings...]
 Options:
       --config CONFIG         path to alternative atlas.yaml configuration file
-  -b, --branch BRANCH         A branch of translation files
   -r, --repository REPOSITORY The repository containing translation files
+  -n, --revision, -b, --branch REVISION 
+                              A git revision of the repository to pull from. The name --branch is deprecated in favor of --revision.
   -f, --filter FILTER         List of patterns to select which files and sub-directories to checkout.
   -g, --expand-glob           Expand glob pattern e.g. 'atlas pull translations/*/done' to 'atlas pull translations/DoneXBlock/done' if it exists.
   -v, --verbose               verbose output to terminal
@@ -384,7 +389,7 @@ set_pull_params() {
     else
       pull_directory=""
       pull_repository="openedx/openedx-translations"
-      pull_branch="main"
+      pull_revision="main"
       pull_filter=""
       pull_expand_glob=""
     fi
@@ -402,9 +407,9 @@ set_pull_params() {
       pull_repository=$REPOSITORY
   fi
 
-  if [ "$BRANCH" ];
+  if [ "$REVISION" ];
   then
-      pull_branch=$BRANCH
+      pull_revision=$REVISION
   fi
 
   if [ "$FILTER" ];
@@ -439,7 +444,7 @@ display_pull_params() {
   echo "Pulling translation files"
   echo " - directory: ${pull_directory:-Not Specified}"
   echo " - repository: ${pull_repository:-Not Specified}"
-  echo " - branch: ${pull_branch:-Not Specified}"
+  echo " - revision: ${pull_revision:-Not Specified}"
   echo " - filter: ${pull_filter:-Not Specified}"
   echo " - expand-glob: ${pull_expand_glob:-Not Specified}"
 }
@@ -502,17 +507,16 @@ pull_translations() {
     quiet="--quiet"
   fi
 
-  # use git in quiet mode when verbose isn't set
-  if [ "$pull_branch" ];
+  if [ "$pull_revision" ];
   then
-    pull_branch_argument="--branch=${pull_branch}"
+    pull_revision_argument="--revision=${pull_revision}"
   else
-    pull_branch_argument=""
+    pull_revision_argument=""
   fi
 
   # Creating a shallow clone of the repo without without pulling the files yet
   # shellcheck disable=SC2086
-  git clone $quiet $pull_branch_argument --filter=blob:none --no-checkout --depth=1 \
+  git clone $quiet $pull_revision_argument --filter=blob:none --no-checkout --depth=1 \
             "https://github.com/${pull_repository}.git" translations_TEMP || exit
   cd translations_TEMP || exit
 

diff --git a/example.atlas.yml b/example.atlas.yml
@@ -1,5 +1,5 @@
 pull:
-  branch: example_branch
+  revision: example_branch
   directory: example_directory
   repository: example_repository
   filter: example_filter

diff --git a/spec/config_spec.sh b/spec/config_spec.sh
@@ -32,7 +32,7 @@ Describe 'Test Default Config'
     The line 1 of output should equal 'Pulling translation files'
     The line 2 of output should equal ' - directory: Not Specified'
     The line 3 of output should equal ' - repository: openedx/openedx-translations'
-    The line 4 of output should equal ' - branch: main'
+    The line 4 of output should equal ' - revision: main'
     The line 5 of output should equal ' - filter: Not Specified'
     The line 6 of output should equal ' - expand-glob: Not Specified'
     The variable PULL_TRANSLATIONS_CALLED should equal true
@@ -60,7 +60,7 @@ Describe 'Test example atlas.yml'
     The line 1 of output should equal 'Pulling translation files'
     The line 2 of output should equal ' - directory: example_directory'
     The line 3 of output should equal ' - repository: example_repository'
-    The line 4 of output should equal ' - branch: example_branch'
+    The line 4 of output should equal ' - revision: example_branch'
     The line 5 of output should equal ' - filter: example_filter'
     The line 6 of output should equal ' - expand-glob: 1'
     The variable PULL_TRANSLATIONS_CALLED should equal true
@@ -83,14 +83,25 @@ Describe 'Test example.atlas.yml'
     The line 1 of output should equal 'Pulling translation files'
     The line 2 of output should equal ' - directory: example_directory'
     The line 3 of output should equal ' - repository: example_repository'
-    The line 4 of output should equal ' - branch: example_branch'
+    The line 4 of output should equal ' - revision: example_branch'
     The line 5 of output should equal ' - filter: example_filter'
     The line 6 of output should equal ' - expand-glob: 1'
     The variable PULL_TRANSLATIONS_CALLED should equal true
   End
 End
 
-Describe 'Test full flags'
+Describe 'Test flags'
+  Parameters
+    # Long flags with the --revision
+    "#1" "--repository custom_repository --revision my_revision --expand-glob --filter ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Long flags with the deprecated --branch flag
+    "#2" "--repository custom_repository --branch my_revision --expand-glob --filter ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Short flags with the -n (revision) flag
+    "#3" "-r custom_repository -n my_revision -g -f ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Short flags with the deprecated -b (branch) flag
+    "#4" "-r custom_repository -b my_revision -g -f ar,es_419 positional_arg_directory:mapped_to_dir"
+  End
+
   # mock pull translations
   Intercept begin_pull_translations_mock
   __begin_pull_translations_mock__() {
@@ -100,20 +111,31 @@ Describe 'Test full flags'
     }
   }
 
-  It 'correctly reads full flag params'
-    When run source ./atlas pull --repository full_flag_repository --branch full_flag_branch --expand-glob --filter ar,es_419 positional_arg_directory:to_dir
+  It "correctly reads command line flag params test case $1"
+    When run source ./atlas pull $2  # $2 is set by the Parameters block
     The lines of output should equal 6
     The line 1 of output should equal 'Pulling translation files'
-    The line 2 of output should equal ' - directory: positional_arg_directory:to_dir'
-    The line 3 of output should equal ' - repository: full_flag_repository'
-    The line 4 of output should equal ' - branch: full_flag_branch'
+    The line 2 of output should equal ' - directory: positional_arg_directory:mapped_to_dir'
+    The line 3 of output should equal ' - repository: custom_repository'
+    The line 4 of output should equal ' - revision: my_revision'
     The line 5 of output should equal ' - filter: ar es_419'
     The line 6 of output should equal ' - expand-glob: 1'
     The variable PULL_TRANSLATIONS_CALLED should equal true
   End
 End
 
-Describe 'Test short flags'
+Describe 'Test flags'
+  Parameters
+    # Long flags with the --revision
+    "#1" "--repository custom_repository --revision my_revision --expand-glob --filter ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Long flags with the deprecated --branch flag
+    "#2" "--repository custom_repository --branch my_revision --expand-glob --filter ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Short flags with the -n (revision) flag
+    "#3" "-r custom_repository -n my_revision -g -f ar,es_419 positional_arg_directory:mapped_to_dir"
+    # Short flags with the deprecated -b (branch) flag
+    "#4" "-r custom_repository -b my_revision -g -f ar,es_419 positional_arg_directory:mapped_to_dir"
+  End
+
   # mock pull translations
   Intercept begin_pull_translations_mock
   __begin_pull_translations_mock__() {
@@ -123,21 +145,21 @@ Describe 'Test short flags'
     }
   }
 
-  It 'correctly reads short flag params'
-    When run source ./atlas pull -r short_flag_repository -b short_flag_branch -g -f 'ar es_419' positional_arg_directory:mapped_to_dir
+  It "correctly reads command line flag params test case $1"
+    When run source ./atlas pull $2  # $2 is set by the Parameters block
     The lines of output should equal 6
     The line 1 of output should equal 'Pulling translation files'
     The line 2 of output should equal ' - directory: positional_arg_directory:mapped_to_dir'
-    The line 3 of output should equal ' - repository: short_flag_repository'
-    The line 4 of output should equal ' - branch: short_flag_branch'
+    The line 3 of output should equal ' - repository: custom_repository'
+    The line 4 of output should equal ' - revision: my_revision'
     The line 5 of output should equal ' - filter: ar es_419'
     The line 6 of output should equal ' - expand-glob: 1'
     The variable PULL_TRANSLATIONS_CALLED should equal true
   End
 End
 
 
-Describe 'Test short flags'
+Describe 'Test multiple directories and comma separated filters'
   # mock pull translations
   Intercept begin_pull_translations_mock
   __begin_pull_translations_mock__() {
@@ -156,4 +178,12 @@ Describe 'Test short flags'
     The line 2 of output should equal ' - directory: orange_dir:foo_local_dir blue_dir:bazz_local_dir'
     The variable PULL_TRANSLATIONS_CALLED should equal true
   End
+
+
+  It 'correctly reads multiple directories and separate them in spaces'
+    When run source ./atlas pull -r short_flag_repository -f ar,de_DE orange_dir:foo_local_dir
+    The lines of output should equal 6
+    The line 5 of output should equal ' - filter: ar de_DE'  # Convert comma separated into space-separated shell array
+    The variable PULL_TRANSLATIONS_CALLED should equal true
+  End
 End
diff --git a/spec/integration_spec.sh b/spec/integration_spec.sh
@@ -46,7 +46,7 @@ Describe 'Pull performance on edX Platform Arabic translations'
     The output should equal 'Pulling translation files
  - directory: drag_and_drop_v2:drag_and_drop_v2 non-existent-dir:no-files-here
  - repository: openedx/xblock-drag-and-drop-v2
- - branch: v3.2.0
+ - revision: v3.2.0
  - filter: ar fr
  - expand-glob: Not Specified
 Creating a temporary Git repository to pull translations into "./translations_TEMP"...
@@ -106,7 +106,7 @@ Describe 'Bash glob patterns'
     The output should equal 'Pulling translation files
  - directory: drag_and_drop_v2/*/locale:drag_and_drop_v2
  - repository: openedx/xblock-drag-and-drop-v2
- - branch: v3.2.0
+ - revision: v3.2.0
  - filter: ar
  - expand-glob: 1
 Creating a temporary Git repository to pull translations into "./translations_TEMP"...

diff --git a/spec/pull_performance_spec.sh b/spec/pull_performance_spec.sh
@@ -44,7 +44,7 @@ Describe 'Pull performance on edX Platform Arabic translations'
     The output should equal 'Pulling translation files
  - directory: conf/locale:messages non-existent-dir:no-files-here
  - repository: openedx/edx-platform
- - branch: open-release/nutmeg.1
+ - revision: open-release/nutmeg.1
  - filter: ar fr
  - expand-glob: Not Specified
 Creating a temporary Git repository to pull translations into "./translations_TEMP"...

diff --git a/spec/pull_spec.sh b/spec/pull_spec.sh
@@ -17,7 +17,7 @@ Describe 'Pull without directory mapping param'
     echo "cp $@"
   }
 
-  setup() { pull_repository="pull_repository" pull_branch="pull_branch"; VERBOSE=1; }
+  setup() { pull_repository="pull_repository" pull_revision="pull_revision"; VERBOSE=1; }
   BeforeEach 'setup'
 
   It 'Fails and require a directory mapping positional parameter'
@@ -78,15 +78,15 @@ Describe 'Pull with directory param'
   setup() {
       pull_directory="pull_directory:local_dir pull_dir2:new/local_dir2 missing_pull_dir:local_dir3"
       pull_repository="pull_repository"
-      pull_branch="pull_branch";
+      pull_revision="pull_revision";
       VERBOSE=1;
   }
   BeforeEach 'setup'
 
   It 'calls everything properly with multiple directories'
     When call pull_translations
     The output should equal 'Creating a temporary Git repository to pull translations into "./translations_TEMP"...
-git clone --branch=pull_branch --filter=blob:none --no-checkout --depth=1 https://github.com/pull_repository.git translations_TEMP
+git clone --revision=pull_revision --filter=blob:none --no-checkout --depth=1 https://github.com/pull_repository.git translations_TEMP
 cd translations_TEMP
 Done.
 Setting git sparse-checkout rules...
@@ -148,7 +148,7 @@ Describe 'Pull filters'
   setup() {
       pull_directory="pull_directory"
       pull_repository="pull_repository"
-      pull_branch="pull_branch"
+      pull_revision="pull_revision"
       pull_filter="ar es_419 fr_CA"
       VERBOSE=0
       SILENT=1
@@ -157,7 +157,7 @@ Describe 'Pull filters'
 
   It 'sets correct sparse-checkout rules'
     When call pull_translations
-    The output should equal 'git clone --branch=pull_branch --filter=blob:none --no-checkout --depth=1 https://github.com/pull_repository.git translations_TEMP
+    The output should equal 'git clone --revision=pull_revision --filter=blob:none --no-checkout --depth=1 https://github.com/pull_repository.git translations_TEMP
 cd translations_TEMP
 git sparse-checkout set --no-cone !* pull_directory/**/ar/** pull_directory/**/ar.* pull_directory/**/es_419/** pull_directory/**/es_419.* pull_directory/**/fr_CA/** pull_directory/**/fr_CA.*
 git checkout HEAD