Skip to main content

Git Workflows

Step-by-step workflows for common development scenarios using SuiteCloud Development Framework (SDF) in VSCode.

Branch Strategy Overview​

main ─────●─────────────────────────●───────●─── (Production)
          │                         │       ↑
          │                    hotfix/fix   │
          │                         └───────┘
          │
          ↓
develop ──●────●────●────●────●────●────●─────── (Integration)
               │    ↑    │    ↑
               │    │    │    │
      feature/NS-123    bugfix/NS-456
               └────┘    └────┘

Branch Types Summary​

Branch TypeSourceTargetPurpose
feature/developdevelopNew functionality
bugfix/developdevelopNon-critical fixes
hotfix/mainmain → developCritical production fixes
New to the Team?

If you're a new employee, start with the New Employee Onboarding guide to set up your development environment first.

Want Hands-On Practice?

After reading this guide, try the SDF + Git Practice Guide for real-world scenarios with two developers collaborating, including conflict creation and resolution exercises.

When to Use PR vs Direct Merge​

When to Use Each Approach​

ScenarioUse PRUse Direct Merge
Team of 2+ developers✅
Code needs review✅
Complex/critical changes✅
Learning/new team member✅
Solo developer✅
Very small fix (typo, comment)✅
Urgent hotfix (with IT Lead approval)✅
Team policy requires PR✅
Team Policy

Check with your IT Lead about which approach your team uses. Many teams require PRs for all changes to maintain code quality and history.

Moving Between Branches​

Switching branches is a fundamental skill you'll use constantly during development. This section covers the systematic approach to safely navigate between branches.

Basic Branch Switching​

# Check which branch you're on
git branch                    # Shows all local branches, * marks current

# Switch to an existing branch
git checkout develop          # Traditional command
git switch develop            # Modern alternative (Git 2.23+)

# Switch and create a new branch in one command
git checkout -b feature/NS-123-new-feature
git switch -c feature/NS-123-new-feature    # Modern alternative

The Golden Rule: Clean Working Directory​

Before switching branches, your working directory should be "clean" (no uncommitted changes). Here's the systematic approach:

Handling Uncommitted Changes​

When you have work in progress and need to switch branches, you have three options:

# Stage and commit your changes
git add .
git commit -m "[NS-XXX] WIP: description of changes"

# Now safe to switch
git checkout other-branch

Stashing saves your changes temporarily without committing:

# Save current changes to stash
git stash                           # Stash with default message
git stash push -m "WIP: feature X"  # Stash with descriptive message

# Now safe to switch
git checkout other-branch

# ... do your work on other branch ...

# Return to original branch
git checkout original-branch

# Restore your stashed changes
git stash pop                       # Apply and remove from stash
# OR
git stash apply                     # Apply but keep in stash

Useful stash commands:

git stash list                      # View all stashed changes
git stash show                      # Preview most recent stash
git stash drop                      # Delete most recent stash
git stash clear                     # Delete ALL stashes (careful!)

Option 3: Discard Changes (When changes are not needed)​

# Discard changes in specific file
git checkout -- filename.js

# Discard ALL uncommitted changes (DESTRUCTIVE - cannot undo!)
git checkout -- .
# OR
git restore .                       # Modern alternative
Destructive Command

git checkout -- . permanently discards all uncommitted changes. Only use this when you're certain you don't need the changes.

Practical Scenarios​

Scenario 1: Quick Context Switch​

You're working on a feature but need to quickly check something on develop:

# Save current work
git stash push -m "WIP: vendor invoice form"

# Switch to develop
git checkout develop

# ... review code, check something ...

# Return to feature branch
git checkout feature/NS-123-invoice

# Restore your work
git stash pop

Scenario 2: Urgent Bug While Working on Feature​

An urgent bug appears while you're mid-feature:

# Save incomplete feature work
git stash push -m "WIP: halfway through invoice validation"

# Create bugfix branch from develop
git checkout develop
git pull origin develop
git checkout -b bugfix/NS-456-urgent-fix

# ... fix the bug, commit, merge ...

# Return to feature work
git checkout feature/NS-123-invoice
git stash pop

Scenario 3: Forgot to Create Branch Before Starting Work​

You started coding on develop but should have created a feature branch:

# You're on develop with uncommitted changes
git status                          # Verify changes exist

# Create new branch (carries your uncommitted changes with you!)
git checkout -b feature/NS-789-new-work

# Now commit on the correct branch
git add .
git commit -m "[NS-789] Add new functionality"

Quick Reference: Branch Navigation Commands​

TaskCommand
See current branchgit branch
See all branches (including remote)git branch -a
Switch to existing branchgit checkout <branch>
Create and switch to new branchgit checkout -b <branch>
Stash current changesgit stash
Restore stashed changesgit stash pop
View stash listgit stash list
Discard file changesgit checkout -- <file>

Best Practices​

  1. Always check git status before switching - Know what you're leaving behind
  2. Use descriptive stash messages - git stash push -m "description" helps when you have multiple stashes
  3. Don't leave stashes for too long - Apply or drop them promptly to avoid confusion
  4. Pull after switching to shared branches - Always git pull after switching to develop or main
# Good habit: pull after switching to shared branches
git checkout develop
git pull origin develop

Feature Development Workflow​

When to Use​

  • Adding new SuiteScript (Suitelet, RESTlet, Map/Reduce, etc.)
  • Creating new custom records or fields
  • Implementing workflow enhancements
  • Building new reports or saved searches
  • Any non-urgent development work

Flow Diagram (With PR and Without PR)​

Detailed Steps with SDF Commands​

Step 1-2: Setup Branch​

# Switch to develop and get latest
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/vendor-NS123-new-suitelet

Step 3: VSCode SDF Setup​

  1. Open your SDF project folder in VSCode
  2. Verify authentication:
    • Press Ctrl+Shift+P → Type "SuiteCloud: Set Up Account"
    • Or check terminal: suitecloud account:setup
  3. Verify project configuration: 
    📁 YourProject/
    ├── 📄 suitecloud.config.js    ← Project config
    ├── 📁 src/
    │   ├── 📁 FileCabinet/
    │   │   └── 📁 SuiteScripts/   ← Your scripts here
    │   └── 📁 Objects/            ← Custom objects (XML)
    └── 📄 manifest.xml            ← Deployment manifest

Step 4: Development in VSCode​

Creating a new Suitelet:

Ctrl+Shift+P → SuiteCloud: Create SuiteScript
→ Select "Suitelet"
→ Enter filename
→ Script created in FileCabinet/SuiteScripts/

Validating your changes:

Ctrl+Shift+P → SuiteCloud: Validate Project

Common file locations:

TypeLocation
SuiteScriptssrc/FileCabinet/SuiteScripts/
Custom Recordssrc/Objects/customrecord_*.xml
Custom Fieldssrc/Objects/customfield_*.xml
Workflowssrc/Objects/workflow_*.xml
Saved Searchessrc/Objects/savedsearch_*.xml

Step 5: Commit Changes​

# Stage all changes
git add .

# Commit with ticket reference
git commit -m "[NS-123] Add vendor invoice automation suitelet

- Created vendor_invoice_suitelet.js
- Added custom record for tracking
- Configured deployment"

Step 6: Deploy to Sandbox (Testing)​

Ctrl+Shift+P → SuiteCloud: Deploy to Account
→ Select your Sandbox account
→ Wait for deployment to complete

Or via terminal:

suitecloud project:deploy --account SANDBOX_ACCOUNT_ID

Step 6.5: Sync with Develop​

Before merging (with or without PR), always sync your branch with the latest develop:

git fetch origin
git merge origin/develop
Merge Conflicts?

If you get conflicts during the merge, see Managing Merge Conflicts for step-by-step resolution guide.

Step 7a-8a: Push and Create PR​

# Push branch to GitHub
git push -u origin feature/vendor-NS123-new-suitelet

Then on GitHub:

  1. Navigate to your repository
  2. Click "Compare & pull request"
  3. Set base: develop ← compare: feature/vendor-NS123-new-suitelet
  4. Fill in the PR template
  5. Assign reviewers

Step 9a-10a: Review, Merge on GitHub​

After approval:

  • Click "Squash and merge" (recommended)
  • Delete remote feature branch on GitHub

Step 11: Local Cleanup (Both Paths)​

# After merge (PR or direct)
git checkout develop
git pull origin develop

# Delete local feature branch
git branch -d feature/vendor-NS123-new-suitelet

PATH B: Without PR (Direct Merge)​

Use this path for solo developers or when team policy allows direct merges.

Step 7b: Merge Locally to Develop​

# Switch to develop and get latest
git checkout develop
git pull origin develop

# Merge your feature branch into develop
git merge feature/vendor-NS123-new-suitelet
Merge Conflicts?

If conflicts occur, resolve them following Managing Merge Conflicts, then continue.

Step 8b: Push Develop to GitHub​

# Push the merged develop branch
git push origin develop

Step 11: Local Cleanup (Both Paths)​

# Delete local feature branch
git branch -d feature/vendor-NS123-new-suitelet

# Optional: Delete remote feature branch if you pushed it
git push origin --delete feature/vendor-NS123-new-suitelet

Quick Comparison: PR vs Direct Merge​

StepWith PRDirect Merge
Push feature branchgit push -u origin feature/...Not required
Create PROn GitHubSkip
Code ReviewRequiredSelf-review
Merge locationOn GitHubLocally
Push after mergeNot needed (GitHub did it)git push origin develop

Bug Fix Workflow​

When to Use​

  • Fixing non-critical bugs found in develop
  • Issues that can wait for next release cycle
  • Problems discovered during testing
  • Minor corrections to existing functionality

Flow Diagram (With PR and Without PR)​

Detailed Steps​

Step 1: Document the Bug​

Before starting, gather information:

**Bug Report:**
- Ticket: NS-456
- Script: vendor_invoice_suitelet.js
- Error: "Cannot read property 'getValue' of null"
- Steps to reproduce:
  1. Open Suitelet
  2. Leave vendor field empty
  3. Click Submit
- Expected: Validation error message
- Actual: Script crashes

Step 2-3: Create Bugfix Branch​

git checkout develop
git pull origin develop
git checkout -b bugfix/vendor-NS456-null-vendor-check

Step 4: Locate Issue in VSCode​

Using SuiteScript Debugger:

  1. Open script file in VSCode
  2. Set breakpoints on suspicious lines
  3. Ctrl+Shift+P → "SuiteCloud: Debug SuiteScript"
  4. Trigger the bug scenario
  5. Inspect variable values

Checking NetSuite Execution Log:

  1. Go to Customization → Scripting → Script Execution Logs
  2. Filter by your script
  3. Look for error stack traces

Step 5: Implement Minimal Fix​

// BEFORE (buggy)
const vendorId = record.getValue({ fieldId: 'entity' });
const vendorName = search.lookupFields({
    type: 'vendor',
    id: vendorId,  // Crashes if vendorId is null
    columns: ['companyname']
});

// AFTER (fixed)
const vendorId = record.getValue({ fieldId: 'entity' });
if (!vendorId) {
    throw error.create({
        name: 'MISSING_VENDOR',
        message: 'Please select a vendor before submitting.'
    });
}
const vendorName = search.lookupFields({
    type: 'vendor',
    id: vendorId,
    columns: ['companyname']
});

Step 6: Test in Sandbox​

Ctrl+Shift+P → SuiteCloud: Deploy to Account
→ Select Sandbox
→ Test the fix
→ Verify no side effects

Step 7: Commit Changes​

# Commit with clear message
git add .
git commit -m "[NS-456] Fix: Add null check for vendor field

Root cause: Script crashed when vendor field was empty
Fix: Added validation before vendor lookup
Testing: Verified in sandbox, error message now displays correctly"

Step 7.5: Sync with Develop​

Before merging (with or without PR), always sync your branch:

git fetch origin
git merge origin/develop
Bugfix Conflict Strategy

If conflicts occur, your bugfix logic takes priority, but apply it to the new code structure from develop. See Managing Merge Conflicts for detailed examples.

Step 8a-9a: Push and Create PR​

# Push branch to GitHub
git push -u origin bugfix/vendor-NS456-null-vendor-check

Then on GitHub:

  1. Navigate to your repository
  2. Click "Compare & pull request"
  3. Set base: develop ← compare: bugfix/vendor-NS456-null-vendor-check
  4. Reference the bug ticket number
  5. Describe the root cause and fix
  6. Assign reviewers

Step 10a: Review and Merge on GitHub​

After approval:

  • Click "Squash and merge" (recommended)
  • Delete remote bugfix branch on GitHub

PATH B: Without PR (Direct Merge)​

Use this path for solo developers or when team policy allows direct merges.

Step 8b: Merge Locally to Develop​

# Switch to develop and get latest
git checkout develop
git pull origin develop

# Merge your bugfix branch into develop
git merge bugfix/vendor-NS456-null-vendor-check

Step 9b: Push Develop to GitHub​

# Push the merged develop branch
git push origin develop

Step 10: Local Cleanup (Both Paths)​

# Delete local bugfix branch
git checkout develop
git pull origin develop
git branch -d bugfix/vendor-NS456-null-vendor-check

# Optional: Delete remote bugfix branch if you pushed it
git push origin --delete bugfix/vendor-NS456-null-vendor-check

Bugfix Best Practices​

DoDon't
Make minimal changesRefactor unrelated code
Document root causeJust fix symptoms
Test regressionOnly test the fix
Reference ticket numberUse vague commit messages

Hotfix Workflow​

When to Use​

Critical Situations Only
  • Production is broken for users
  • Security vulnerability discovered
  • Data corruption occurring
  • Financial calculations incorrect

Always notify IT Lead before starting a hotfix!

Flow Diagram (With PR and Without PR)​

Hotfix Direct Merge

Direct merge (PATH B) for hotfixes should only be used when:

  • IT Lead explicitly approves skipping PR due to extreme urgency
  • You are the IT Lead and can self-approve
  • Review must still happen (code walkthrough via call/screen share)

Visual: Hotfix Branch Flow​

main ────●──────────────●────●─── (Production)
         │              │    ↑
         │         hotfix/NS999
         │              └────┘
         ↓                   │
develop ─●────●──────────────●─── (Integration - synced)

Detailed Steps​

Step 1: Notify IT Lead​

Before writing any code:

Message/Call IT Lead:
"URGENT: Production issue with [script/feature]
Impact: [describe user impact]
Error: [error message if available]
I'm ready to create a hotfix. Approval to proceed?"

Step 2: Create Hotfix from Main​

# IMPORTANT: Branch from main, not develop!
git checkout main
git pull origin main
git checkout -b hotfix/NS999-fix-payment-calculation

Step 3: Implement Emergency Fix​

Keep it minimal:

// ONLY fix the immediate issue
// Example: Fixing a calculation error

// BEFORE
const total = subtotal * taxRate;  // Wrong formula

// AFTER
const total = subtotal * (1 + taxRate);  // Correct formula

// Do NOT also refactor, add features, or "improve" other code

Step 4: Quick Testing​

# Deploy to Sandbox first (ALWAYS)
Ctrl+Shift+P → SuiteCloud: Deploy to Account → Sandbox

# Test the specific scenario that was failing
# Do quick regression check on related functionality

Step 5: Commit Changes​

git add .
git commit -m "[NS-999] HOTFIX: Correct payment calculation formula

CRITICAL: Payment amounts were being calculated incorrectly
Impact: All payments since [date] affected
Fix: Corrected tax calculation formula
Tested: Verified in sandbox with sample transactions"

Step 6a: Push to GitHub​

git push -u origin hotfix/NS999-fix-payment-calculation

Step 7a: Create PR to Main​

Create PR on GitHub:

  • Base: main ← Compare: hotfix/NS999-fix-payment-calculation
  • Title: [HOTFIX] NS-999: Fix payment calculation
  • Add "urgent" or "critical" label
  • Request IT Lead as reviewer

Step 8a: Emergency Review and Merge​

  • IT Lead reviews and approves
  • Merge using "Squash and merge"
  • Do NOT delete branch yet (needed for sync to develop)

PATH B: Without PR (Direct Merge - Emergency Only)​

Use this path only when IT Lead explicitly approves skipping PR due to extreme urgency.

Step 6b: Merge Locally to Main​

# Switch to main and get latest
git checkout main
git pull origin main

# Merge your hotfix branch into main
git merge hotfix/NS999-fix-payment-calculation

Step 7b: Push Main to GitHub​

# Push the merged main branch
git push origin main

Step 9: Deploy to Production​

# Deploy to Production account via SDF
Ctrl+Shift+P → SuiteCloud: Deploy to Account → Production

# Or via terminal
suitecloud project:deploy --account PRODUCTION_ACCOUNT_ID

Post-deployment verification:

  1. Test the fix in production
  2. Check Script Execution Logs for errors
  3. Monitor for 15-30 minutes

Step 10: Sync to Develop​

# This ensures develop has the fix too
git checkout develop
git pull origin develop
git merge main
git push origin develop
Hotfix Sync Conflicts

If conflicts occur when syncing to develop, the hotfix code takes priority since it's been tested in production. See Managing Merge Conflicts for resolution strategy.

Step 11: Cleanup and Document​

# Delete local and remote hotfix branch
git branch -d hotfix/NS999-fix-payment-calculation
git push origin --delete hotfix/NS999-fix-payment-calculation

Document the incident:

## Hotfix Report - NS-999

**Date:** 2024-01-15
**Severity:** Critical
**Resolution Time:** 45 minutes

**Issue:** Payment calculation formula incorrect
**Root Cause:** Tax rate was multiplied instead of added
**Fix:** Corrected formula in payment_processor.js line 234
**Impact:** ~50 transactions affected, corrections applied

**Lessons Learned:**
- Add unit tests for calculation functions
- Review formulas more carefully in code review

Hotfix Checklist​

StepCompleted
IT Lead notified☐
Branch from main (not develop)☐
Fix is minimal and focused☐
Tested in Sandbox☐
PR targets main branch☐
IT Lead approved☐
Deployed to Production☐
Verified in Production☐
Synced to develop☐
Branch deleted☐
Incident documented☐

SDF Project Structure Reference​

For all workflows, your SDF project should follow this structure:

📁 MyNetSuiteProject/
├── 📄 suitecloud.config.js      # SDF configuration
├── 📄 manifest.xml              # Deployment manifest
├── 📁 src/
│   ├── 📁 FileCabinet/
│   │   └── 📁 SuiteScripts/
│   │       ├── 📁 Suitelets/    # Suitelet scripts
│   │       ├── 📁 UserEvents/   # User Event scripts
│   │       ├── 📁 ClientScripts/# Client scripts
│   │       ├── 📁 MapReduce/    # Map/Reduce scripts
│   │       ├── 📁 RESTlets/     # RESTlet scripts
│   │       └── 📁 Libraries/    # Shared libraries
│   ├── 📁 Objects/
│   │   ├── customrecord_*.xml   # Custom records
│   │   ├── customfield_*.xml    # Custom fields
│   │   ├── workflow_*.xml       # Workflows
│   │   └── savedsearch_*.xml    # Saved searches
│   └── 📁 Templates/
│       └── *.html               # HTML templates
└── 📁 .git/                     # Git repository

VSCode SDF Commands Quick Reference​

ActionCommand Palette (Ctrl+Shift+P)
Set up accountSuiteCloud: Set Up Account
Create scriptSuiteCloud: Create SuiteScript
Import objectsSuiteCloud: Import Objects
Validate projectSuiteCloud: Validate Project
Deploy to accountSuiteCloud: Deploy to Account
Debug scriptSuiteCloud: Debug SuiteScript

Syncing Changes from NetSuite UI​

When to Use​

Sometimes changes are made directly in NetSuite's web interface:

  • Script edited via UI during debugging
  • Custom record modified by an admin
  • Workflow updated via point-and-click
  • Emergency fix applied without SDF

These changes need to be imported and version controlled.

Sync Workflow​

Step-by-Step​

# 1. Create sync branch
git checkout develop
git pull origin develop
git checkout -b sync/NS-888-import-ui-changes

2. Import Files from NetSuite:

  • Press Ctrl+Shift+P → SuiteCloud: Import Files
  • Select account → Navigate to script location → Import

3. Import Objects from NetSuite:

  • Press Ctrl+Shift+P → SuiteCloud: Import Objects
  • Select object type (e.g., usereventscript) → Select objects → Import
# 4. Commit and merge
git add .
git commit -m "[NS-888] Sync changes from NetSuite UI

- Imported updated script files
- Imported modified object definitions"

git push origin sync/NS-888-import-ui-changes

# 5. Merge to develop
git checkout develop
git merge sync/NS-888-import-ui-changes
git push origin develop
Best Practice

Discourage direct NetSuite UI edits. Always prefer SDF deployment for proper version control. Use sync branches only when UI changes were unavoidable.

Quick Reference​

ScenarioBranch FromMerge ToPrefixUrgency
New featuredevelopdevelopfeature/Normal
Bug fixdevelopdevelopbugfix/Normal
Hotfixmainmain → develophotfix/Critical
UI syncdevelopdevelopsync/Normal

Branch Naming​

[type]/[team]-[TICKET]-[short-description]

Examples:

  • feature/vendor-NS123-invoice-automation
  • bugfix/it-NS456-fix-calculation
  • hotfix/NS999-critical-payment-fix

Need Help with Merge Conflicts?​

For comprehensive guidance on understanding, resolving, and preventing merge conflicts, see the dedicated Managing Merge Conflicts guide.

Quick tips:

  • Don't panic! Conflicts are normal and fixable
  • Use VSCode's built-in merge editor for easier resolution
  • When in doubt, ask the person who wrote the conflicting code
  • See Managing Merge Conflicts for step-by-step resolution