feat(init): add --checkout option to sam init command for specifying git branch, tag, or commit

samcli/commands/init/command.py

@@ -217,6 +217,17 @@ def wrapped(*args, **kwargs):
     """ """,
     required=False,
 )
+@click.option(
+    "--checkout",
+    default=None,
+    help="Branch, tag or commit to checkout after git clone.",
+    required=False,
+    cls=ClickMutex,
+    required_param_lists=[["location"]],
+    required_params_hint="The --checkout option requires --location to specify a git repository.",
+    incompatible_params=["package_type", "runtime", "base_image", "dependency_manager", "app_template"],
+    incompatible_params_hint=INCOMPATIBLE_PARAMS_HINT,
+)
 @click.option(
     "--tracing/--no-tracing",
     default=None,
@@ -259,6 +270,7 @@ def cli(
     save_params,
     config_file,
     config_env,
+    checkout,
 ):
     """
     `sam init` command entry point
@@ -281,6 +293,7 @@ def cli(
         tracing,
         application_insights,
         structured_logging,
+        checkout,
     )  # pragma: no cover
 
 
@@ -303,6 +316,7 @@ def do_cli(
     tracing,
     application_insights,
     structured_logging,
+    checkout,
 ):
     """
     Implementation of the ``cli`` method
@@ -356,6 +370,7 @@ def do_cli(
             tracing,
             application_insights,
             structured_logging,
+            checkout,
         )
     else:
         if not (pt_explicit or runtime or dependency_manager or base_image or architecture):
@@ -377,6 +392,7 @@ def do_cli(
             tracing,
             application_insights,
             structured_logging,
+            checkout,
         )
 
 

samcli/commands/init/core/options.py

@@ -22,7 +22,7 @@
 ]
 
 # Can be used instead of the options in the first list
-NON_INTERACTIVE_OPTIONS: List[str] = ["no_interactive", "no_input", "extra_context"]
+NON_INTERACTIVE_OPTIONS: List[str] = ["no_interactive", "no_input", "extra_context", "checkout"]
 
 CONFIGURATION_OPTION_NAMES: List[str] = ["config_env", "config_file"] + SAVE_PARAMS_OPTIONS
 

samcli/commands/init/init_generator.py

@@ -19,6 +19,7 @@ def do_generate(
     tracing,
     application_insights,
     structured_logging,
+    checkout=None,
 ):
     try:
         generate_project(
@@ -33,6 +34,7 @@ def do_generate(
             tracing,
             application_insights,
             structured_logging,
+            checkout,
         )
     except InitErrorException as e:
         raise UserException(str(e), wrapped_from=e.__class__.__name__) from e

samcli/commands/init/interactive_init_flow.py

@@ -57,6 +57,7 @@ def do_interactive(
     tracing,
     application_insights,
     structured_logging,
+    checkout=None,
 ):
     """
     Implementation of the ``cli`` method when --interactive is provided.
@@ -85,6 +86,7 @@ def do_interactive(
         tracing,
         application_insights,
         structured_logging,
+        checkout,
     )
 
 
@@ -104,6 +106,7 @@ def generate_application(
     tracing,
     application_insights,
     structured_logging,
+    checkout=None,
 ):  # pylint: disable=too-many-arguments
     """
     The method holds the decision logic for generating an application
@@ -156,6 +159,7 @@ def generate_application(
             tracing,
             application_insights,
             structured_logging,
+            checkout,
         )
 
     else:
@@ -170,6 +174,7 @@ def generate_application(
             tracing,
             application_insights,
             structured_logging,
+            checkout,
         )
 
 
@@ -185,6 +190,7 @@ def _generate_from_location(
     tracing,
     application_insights,
     structured_logging,
+    checkout=None,
 ):
     location = click.prompt("\nTemplate location (git, mercurial, http(s), zip, path)", type=str)
     summary_msg = """
@@ -207,6 +213,7 @@ def _generate_from_location(
         tracing,
         application_insights,
         structured_logging,
+        checkout,
     )
 
 
@@ -225,6 +232,7 @@ def _generate_from_use_case(
     tracing: Optional[bool],
     application_insights: Optional[bool],
     structured_logging: Optional[bool],
+    checkout: Optional[str] = None,
 ) -> None:
     templates = InitTemplates()
     runtime_or_base_image = runtime if runtime else base_image
@@ -315,6 +323,7 @@ def _generate_from_use_case(
         tracing,
         application_insights,
         structured_logging,
+        checkout,
     )
     # executing event_bridge logic if call is for Schema dynamic template
     if is_dynamic_schemas_template:

samcli/lib/init/__init__.py

@@ -40,6 +40,7 @@ def generate_project(
     tracing=False,
     application_insights=False,
     structured_logging=False,
+    checkout=None,
 ):
     """Generates project using cookiecutter and options given
 
@@ -74,6 +75,8 @@ def generate_project(
             Enable or disable AppInsights Monitoring
     structured_logging: Optional[bool]
         boolean value to determine if Json structured logging should be enabled or not
+    checkout: Optional[str]
+        Branch, tag or commit to checkout after git clone
 
     Raises
     ------
@@ -98,6 +101,9 @@ def generate_project(
     if extra_context:
         params["extra_context"] = extra_context
 
+    if checkout:
+        params["checkout"] = checkout
+
     LOG.debug("Parameters dict created with input given")
     LOG.debug("%s", params)
 
@@ -123,7 +129,12 @@ def generate_project(
             "it as a cookiecutter template"
         )
         project_output_dir = str(Path(output_dir, name)) if name else output_dir
-        generate_non_cookiecutter_project(location=params["template"], output_dir=project_output_dir)
+        if checkout:
+            generate_non_cookiecutter_project(
+                location=params["template"], output_dir=project_output_dir, checkout=checkout
+            )
+        else:
+            generate_non_cookiecutter_project(location=params["template"], output_dir=project_output_dir)
 
     except UnknownRepoType as e:
         raise InvalidLocationError(template=params["template"]) from e

samcli/lib/init/arbitrary_project.py

@@ -24,7 +24,7 @@
 )
 
 
-def generate_non_cookiecutter_project(location, output_dir):
+def generate_non_cookiecutter_project(location, output_dir, checkout=None):
     """
     Uses Cookiecutter APIs to download a project at given ``location`` to the ``output_dir``.
     This does *not* run cookiecutter on the downloaded project.
@@ -41,6 +41,9 @@ def generate_non_cookiecutter_project(location, output_dir):
     output_dir : str
         Directory where the project should be downloaded to
 
+    checkout: Optional[str]
+        Branch, tag or commit to checkout after git clone
+
     Returns
     -------
     str
@@ -69,7 +72,10 @@ def generate_non_cookiecutter_project(location, output_dir):
     # Else, treat it as a git/hg/ssh URL and try to clone
     elif repository.is_repo_url(location):
         LOG.debug("%s location is a source control repository", location)
-        download_fn = functools.partial(repository.clone, repo_url=location, no_input=no_input)
+        clone_kwargs = {"repo_url": location, "no_input": no_input}
+        if checkout:
+            clone_kwargs["checkout"] = checkout
+        download_fn = functools.partial(repository.clone, **clone_kwargs)
 
     else:
         raise ArbitraryProjectDownloadFailed(msg=BAD_LOCATION_ERROR_MSG)

schema/samcli.json

@@ -54,7 +54,7 @@
           "properties": {
             "parameters": {
               "title": "Parameters for the init command",
-              "description": "Available parameters for the init command:\n* no_interactive:\nDisable interactive prompting for init parameters. (fail if any required values are missing)\n* architecture:\nArchitectures for Lambda functions.\n\nArchitectures: ['arm64', 'x86_64']\n* location:\nTemplate location (git, mercurial, http(s), zip, path).\n* runtime:\nLambda runtime for application.\n\nRuntimes: dotnet10, dotnet8, dotnet6, go1.x, java25, java21, java17, java11, java8.al2, nodejs24.x, nodejs22.x, nodejs20.x, nodejs18.x, nodejs16.x, provided, provided.al2, provided.al2023, python3.9, python3.8, python3.14, python3.13, python3.12, python3.11, python3.10, ruby4.0, ruby3.4, ruby3.3, ruby3.2\n* package_type:\nLambda deployment package type.\n\nPackage Types: Zip, Image\n* base_image:\nLambda base image for deploying IMAGE based package type.\n\nBase images: amazon/dotnet10-base, amazon/dotnet6-base, amazon/dotnet8-base, amazon/go-provided.al2-base, amazon/go-provided.al2023-base, amazon/go1.x-base, amazon/java11-base, amazon/java17-base, amazon/java21-base, amazon/java25-base, amazon/java8.al2-base, amazon/nodejs16.x-base, amazon/nodejs18.x-base, amazon/nodejs20.x-base, amazon/nodejs22.x-base, amazon/nodejs24.x-base, amazon/python3.10-base, amazon/python3.11-base, amazon/python3.12-base, amazon/python3.13-base, amazon/python3.14-base, amazon/python3.8-base, amazon/python3.9-base, amazon/ruby3.2-base, amazon/ruby3.3-base, amazon/ruby3.4-base, amazon/ruby4.0-base\n* dependency_manager:\nDependency manager for Lambda runtime.\n\nDependency managers: bundler, cli-package, gradle, maven, mod, npm, pip\n* output_dir:\nDirectory to initialize AWS SAM application.\n* name:\nName of AWS SAM Application.\n* app_template:\nIdentifier of the managed application template to be used. Alternatively, run '$ sam init' without options for an interactive workflow.\n* no_input:\nDisable Cookiecutter prompting and accept default values defined in the cookiecutter config.\n* extra_context:\nOverride custom parameters in the template's cookiecutter.json configuration e.g. {\"customParam1\": \"customValue1\", \"customParam2\":\"customValue2\"}\n* tracing:\nEnable AWS X-Ray tracing for application.\n* application_insights:\nEnable CloudWatch Application Insights monitoring for application.\n* structured_logging:\nEnable Structured Logging for application.\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
+              "description": "Available parameters for the init command:\n* no_interactive:\nDisable interactive prompting for init parameters. (fail if any required values are missing)\n* architecture:\nArchitectures for Lambda functions.\n\nArchitectures: ['arm64', 'x86_64']\n* location:\nTemplate location (git, mercurial, http(s), zip, path).\n* runtime:\nLambda runtime for application.\n\nRuntimes: dotnet10, dotnet8, dotnet6, go1.x, java25, java21, java17, java11, java8.al2, nodejs24.x, nodejs22.x, nodejs20.x, nodejs18.x, nodejs16.x, provided, provided.al2, provided.al2023, python3.9, python3.8, python3.14, python3.13, python3.12, python3.11, python3.10, ruby4.0, ruby3.4, ruby3.3, ruby3.2\n* package_type:\nLambda deployment package type.\n\nPackage Types: Zip, Image\n* base_image:\nLambda base image for deploying IMAGE based package type.\n\nBase images: amazon/dotnet10-base, amazon/dotnet6-base, amazon/dotnet8-base, amazon/go-provided.al2-base, amazon/go-provided.al2023-base, amazon/go1.x-base, amazon/java11-base, amazon/java17-base, amazon/java21-base, amazon/java25-base, amazon/java8.al2-base, amazon/nodejs16.x-base, amazon/nodejs18.x-base, amazon/nodejs20.x-base, amazon/nodejs22.x-base, amazon/nodejs24.x-base, amazon/python3.10-base, amazon/python3.11-base, amazon/python3.12-base, amazon/python3.13-base, amazon/python3.14-base, amazon/python3.8-base, amazon/python3.9-base, amazon/ruby3.2-base, amazon/ruby3.3-base, amazon/ruby3.4-base, amazon/ruby4.0-base\n* dependency_manager:\nDependency manager for Lambda runtime.\n\nDependency managers: bundler, cli-package, gradle, maven, mod, npm, pip\n* output_dir:\nDirectory to initialize AWS SAM application.\n* name:\nName of AWS SAM Application.\n* app_template:\nIdentifier of the managed application template to be used. Alternatively, run '$ sam init' without options for an interactive workflow.\n* no_input:\nDisable Cookiecutter prompting and accept default values defined in the cookiecutter config.\n* extra_context:\nOverride custom parameters in the template's cookiecutter.json configuration e.g. {\"customParam1\": \"customValue1\", \"customParam2\":\"customValue2\"}\n* checkout:\nBranch, tag or commit to checkout after git clone.\n* tracing:\nEnable AWS X-Ray tracing for application.\n* application_insights:\nEnable CloudWatch Application Insights monitoring for application.\n* structured_logging:\nEnable Structured Logging for application.\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
               "type": "object",
               "properties": {
                 "no_interactive": {
@@ -194,6 +194,11 @@
                   "type": "string",
                   "description": "Override custom parameters in the template's cookiecutter.json configuration e.g. {\"customParam1\": \"customValue1\", \"customParam2\":\"customValue2\"}"
                 },
+                "checkout": {
+                  "title": "checkout",
+                  "type": "string",
+                  "description": "Branch, tag or commit to checkout after git clone."
+                },
                 "tracing": {
                   "title": "tracing",
                   "type": "boolean",