feat: improve branch configuration flexibility and clarity

- Remove hardcoded 'main' branch forcing in UpstreamPrCommand
- Allow any upstream branch to be configured (main, master, develop, etc.)
- Improve setup command prompts with clear explanations
- Add detailed branch configuration documentation in README
- Clarify difference between upstream branch and local branch
- Add examples for different project scenarios (legacy, dev branches)
- Update environment variable documentation with comments

Now supports:
- UPSTREAM_BRANCH: Branch in upstream repo to pull from
- UPSTREAM_LOCAL_BRANCH: Your main project branch for PRs
- Clear setup prompts explaining what each branch is for
- Flexible configuration for any Git workflow

Fixes issues with projects using master/dev branches instead of main.

Author: nejc

README.md

@@ -103,6 +103,20 @@ php artisan laravelplus:setup --preset=custom --url=https://github.com/your-org/
 
 ## Configuration
 
+### Branch Configuration Explained
+
+The package uses two important branch settings:
+
+- **`UPSTREAM_BRANCH`**: The branch in the upstream repository to pull changes from (e.g., `main`, `master`, `develop`)
+- **`UPSTREAM_LOCAL_BRANCH`**: Your main project branch where PRs will be created against (e.g., `main`, `master`, `develop`)
+
+**Example scenarios:**
+- **Laravel Starter Kit**: `UPSTREAM_BRANCH=main` (upstream repo) → `UPSTREAM_LOCAL_BRANCH=main` (your repo)
+- **Legacy Project**: `UPSTREAM_BRANCH=main` (upstream repo) → `UPSTREAM_LOCAL_BRANCH=master` (your repo)
+- **Development Branch**: `UPSTREAM_BRANCH=develop` (upstream repo) → `UPSTREAM_LOCAL_BRANCH=develop` (your repo)
+
+### Publish Configuration
+
 Publish the configuration file:
 
 ```bash
@@ -142,21 +156,30 @@ return [
 Add these to your `.env` file:
 
 ```env
+# Upstream repository configuration
 UPSTREAM_URL=https://github.com/your-upstream/repo.git
-UPSTREAM_BRANCH=main
-UPSTREAM_LOCAL_BRANCH=main
+UPSTREAM_BRANCH=main                    # Branch in upstream repo to pull from
+UPSTREAM_LOCAL_BRANCH=main              # Your main project branch (PRs created against this)
 UPSTREAM_STRATEGY=merge
 UPSTREAM_COMMIT_MESSAGE="chore(upstream): sync from upstream"
 UPSTREAM_ALLOW_UNRELATED=true
+
+# Preset configuration
 UPSTREAM_DEFAULT_PRESET=vue
 UPSTREAM_AUTO_DETECT=true
+
+# PR configuration
 UPSTREAM_CREATE_PR=false
 UPSTREAM_PR_BRANCH_PREFIX=upstream-sync-
 UPSTREAM_PR_TITLE="chore: sync from upstream"
 UPSTREAM_PR_BODY="Automated upstream sync from {upstream_url}"
+
+# GitHub integration
 GITHUB_TOKEN=your_github_token
 GITHUB_OWNER=your_username
 GITHUB_REPO=your_repo
+
+# Git configuration
 GIT_BINARY=git
 ```
 

src/Console/Commands/UpstreamPrCommand.php

@@ -78,11 +78,8 @@ public function handle(): int
             $localBranch = $currentBranch;
         }
 
-        // Upstream branch is always 'main' for Laravel starter kits
-        if ($upstreamBranch !== 'main') {
-            $this->line("📍 Using upstream branch: <info>main</info> (configured: $upstreamBranch)");
-            $upstreamBranch = 'main';
-        }
+        // Use configured upstream branch (defaults to 'main' for Laravel starter kits)
+        $this->line("📍 Using upstream branch: <info>$upstreamBranch</info>");
         $allowUnrelated = (bool) $cfg['allow_unrelated_histories'];
         $dry = (bool) $this->option('dry-run');
 

src/Console/Commands/UpstreamSetupCommand.php

@@ -82,21 +82,26 @@ private function setupPreset(string $preset): int
         $this->info("Setting up upstream sync for Laravel $preset starter kit...");
         $this->newLine();
 
-        // Use main branch for Laravel starter kits (standard)
-        $branch = 'main';
-        $this->line("🌿 Upstream branch: <info>$branch</info> (standard for Laravel starter kits)");
+        // Ask for upstream branch (what branch to pull from in the upstream repo)
+        $upstreamBranch = $this->text(
+            'Which branch should we pull from in the upstream repository?',
+            default: 'main',
+            placeholder: 'e.g., main, master, develop (this is the branch in the upstream repo)'
+        );
+        
+        $this->line("🌿 Upstream branch: <info>$upstreamBranch</info> (branch in {$config['upstream_url']})");
 
-        // Ask for local branch
+        // Ask for local branch (what branch to create PRs against)
         $localBranch = $this->text(
-            'Which local branch should receive the updates?',
-            default: $branch,
-            placeholder: 'e.g., main, develop, feature-branch'
+            'Which local branch should receive the updates? (PRs will be created against this branch)',
+            default: 'main',
+            placeholder: 'e.g., main, master, develop (your main project branch)'
         );
 
         // Update .env file
         $this->updateEnvFile([
             'UPSTREAM_URL' => $config['upstream_url'],
-            'UPSTREAM_BRANCH' => $branch,
+            'UPSTREAM_BRANCH' => $upstreamBranch,
             'UPSTREAM_LOCAL_BRANCH' => $localBranch,
             'UPSTREAM_PRESET' => $preset,
         ]);
@@ -110,8 +115,8 @@ private function setupPreset(string $preset): int
         $this->info("✅ Setup complete for Laravel $preset starter kit!");
         $this->line('📝 Configuration added to .env file');
         $this->line("🔗 Upstream URL: {$config['upstream_url']}");
-        $this->line("🌿 Upstream Branch: $branch");
-        $this->line("📍 Local Branch: $localBranch");
+        $this->line("🌿 Upstream Branch: $upstreamBranch (branch in upstream repo)");
+        $this->line("📍 Local Branch: $localBranch (your main project branch)");
 
         $this->newLine();
         $this->line('💡 You can now run: <info>php artisan laravelplus:check</info>');
@@ -132,16 +137,16 @@ private function setupCustom(): int
             return self::FAILURE;
         }
 
-        $branch = $this->text(
-            'Enter upstream branch name',
+        $upstreamBranch = $this->text(
+            'Which branch should we pull from in the upstream repository?',
             default: 'main',
-            placeholder: 'usually "main" for Laravel projects'
+            placeholder: 'e.g., main, master, develop (this is the branch in the upstream repo)'
         );
 
         $localBranch = $this->text(
-            'Enter local branch name',
+            'Which local branch should receive the updates? (PRs will be created against this branch)',
             default: 'main',
-            placeholder: 'where updates will be applied'
+            placeholder: 'e.g., main, master, develop (your main project branch)'
         );
 
         $this->info('Setting up upstream sync for custom repository...');
@@ -150,7 +155,7 @@ private function setupCustom(): int
         // Update .env file
         $this->updateEnvFile([
             'UPSTREAM_URL' => $url,
-            'UPSTREAM_BRANCH' => $branch,
+            'UPSTREAM_BRANCH' => $upstreamBranch,
             'UPSTREAM_LOCAL_BRANCH' => $localBranch,
             'UPSTREAM_PRESET' => 'custom',
         ]);
@@ -159,8 +164,8 @@ private function setupCustom(): int
         $this->info('✅ Custom setup complete!');
         $this->line('📝 Configuration added to .env file');
         $this->line("🔗 Upstream URL: $url");
-        $this->line("🌿 Upstream Branch: $branch");
-        $this->line("📍 Local Branch: $localBranch");
+        $this->line("🌿 Upstream Branch: $upstreamBranch (branch in upstream repo)");
+        $this->line("📍 Local Branch: $localBranch (your main project branch)");
 
         $this->newLine();
         $this->line('💡 You can now run: <info>php artisan laravelplus:check</info>');