🧱 How to Create a New Project from a GitHub Template and Clone It Locally

This guide walks you through using a GitHub repository as a template to start a new project and then cloning it to your local machine. It also covers how to properly rename identifiers in a Flutter template project so it runs cleanly as a new app.

Step 1: Turn an Existing Repo into a Template (One-Time Setup)

If you already have a repo you want to use as a template:

Go to the repo on GitHub.
Click Settings.
Scroll down to “Template repository” and check the box.
Done! Your repo is now a template and shows a “Use this template” button.

Step 2: Create a New Repo from the Template

On the GitHub page of the template repository, click the green “Use this template” button.
Select “Create a new repository”.
Choose:
- A new name (e.g., my-cool-project)
- Whether it’s public or private
Click Create repository from template.

This gives you a clean copy of the repo — without commit history — to start fresh.

💻 Step 3: Clone the New Repo to Your Local Machine

Navigate to the folder where you keep your projects:
```
cd ~/projects
```

Clone the new repository:

git clone git@github.com:your-username/my-cool-project.git
# Or using HTTPS
git clone https://github.com/your-username/my-cool-project.git

Navigate into the cloned folder:
```
cd my-cool-project
```
(Optional) Check your remote:
```
git remote -v
```

⚒️ Step 4: Set Up Your Flutter Project

When starting a new Flutter project using an existing template, update certain identifiers so the new app is recognized as distinct from the original. This is especially critical on Android to avoid namespace and installation conflicts.

1. Update the Package Name (Namespace)

a. `build.gradle.kts` or `build.gradle`

Location: android/app/build.gradle.kts or build.gradle

Find and update:

namespace = "com.example.template"
applicationId = "com.example.template"

Change both to your new namespace:

namespace = "com.example.todo"
applicationId = "com.example.todo"

b. Update Kotlin Package Path

Location: android/app/src/main/kotlin/com/example/template/MainActivity.kt

Steps:

Change the package declaration at the top of MainActivity.kt:
```
package com.example.todo
```

Rename the folder structure to match:

android/app/src/main/kotlin/com/example/todo/MainActivity.kt

Create the folders if they don’t exist.

Important: The folder structure must match the package exactly, or Android will not find the class at runtime.

2. (OPTIONAL) Update `AndroidManifest.xml`

Location: android/app/src/main/AndroidManifest.xml

Update the package at the top:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.todo">

Update the <activity> block to use the fully qualified name:

<activity
    android:name="com.example.todo.MainActivity"

Important: The android:name must match the full class path even if the folder path is correct.

3. (Optional) Update `pubspec.yaml`

Location: pubspec.yaml

Update:

name: todo_app
description: A simple to-do list app template.

4. Run a Clean Rebuild

flutter clean
flutter pub get
flutter run

This clears cached builds and fetches dependencies.

5. Test Installation

Confirm the new app installs without replacing any existing app.
Open your app drawer and verify the new name/icon.

✅ Summary Checklist

build.gradle.kts: update namespace and applicationId
MainActivity.kt: update package and folder structure
AndroidManifest.xml: update package and activity android:name
pubspec.yaml: update name and description (optional)
Run flutter clean, flutter pub get, and flutter run

⚠️ Extra Tips

Folder mismatch = crash: If package com.example.todo but folders are com/example/template, it won’t work.
Changing applicationId avoids overwrite: Keeps your new app from replacing the original.
Always qualify MainActivity in the manifest: Required even if folder is correct.

Visit Emlekezik.com