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

samcli/commands/init/command.py

@@ -217,6 +217,15 @@ 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,
+    incompatible_params=["package_type", "runtime", "base_image", "dependency_manager", "app_template"],
+    incompatible_params_hint=INCOMPATIBLE_PARAMS_HINT,
+)
 @click.option(
     "--tracing/--no-tracing",
     default=None,
@@ -253,6 +262,7 @@ def cli(
     app_template,
     no_input,
     extra_context,
+    checkout,
     tracing,
     application_insights,
     structured_logging,
@@ -278,6 +288,7 @@ def cli(
         app_template,
         no_input,
         extra_context,
+        checkout,
         tracing,
         application_insights,
         structured_logging,
@@ -300,6 +311,7 @@ def do_cli(
     app_template,
     no_input,
     extra_context,
+    checkout,
     tracing,
     application_insights,
     structured_logging,
@@ -356,6 +368,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 +390,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)
 

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",