Stashing

stash@{0}  <- Most recent
stash@{1}
stash@{2}  <- Oldest

// From app/src/lib/git/stash.ts
export const DesktopStashEntryMarker = '!!GitHub_Desktop'

// Pattern to identify Desktop-created stashes
const desktopStashEntryMessageRe = /!!GitHub_Desktop<(.+)>$/

// Stash message format
export function createDesktopStashMessage(branchName: string) {
  return `${DesktopStashEntryMarker}<${branchName}>`
}

export async function createDesktopStashEntry(
  repository: Repository,
  branch: Branch | string,
  untrackedFilesToStage: ReadonlyArray<WorkingDirectoryFileChange>
): Promise<boolean> {
  // Stage untracked files first
  const fullySelectedUntrackedFiles = untrackedFilesToStage.map(x =>
    x.withIncludeAll(true)
  )
  await stageFiles(repository, fullySelectedUntrackedFiles)
  
  const branchName = typeof branch === 'string' ? branch : branch.name
  const message = createDesktopStashMessage(branchName)
  const args = ['stash', 'push', '-m', message]
  
  const result = await git(args, repository.path, 'createStashEntry')
  
  // Git returns this when there's nothing to stash
  if (result.stdout === 'No local changes to save\n') {
    return false
  }
  
  return true
}

export async function getStashes(repository: Repository): Promise<StashResult> {
  const { formatArgs, parse } = createLogParser({
    name: '%gD',          // Stash name (stash@{0})
    stashSha: '%H',       // Commit SHA
    message: '%gs',       // Stash message  
    tree: '%T',           // Tree SHA
    parents: '%P',        // Parent commits
  })
  
  const result = await git(
    ['log', '-g', ...formatArgs, 'refs/stash', '--'],
    repository.path,
    'getStashEntries'
  )
  
  const desktopEntries: Array<IStashEntry> = []
  const entries = parse(result.stdout)
  
  // Filter for Desktop-created stashes
  for (const { name, message, stashSha, tree, parents } of entries) {
    const branchName = extractBranchFromMessage(message)
    
    if (branchName !== null) {
      desktopEntries.push({
        name,
        stashSha,
        branchName,
        tree,
        parents: parents.split(' '),
        files: { kind: StashedChangesLoadStates.NotLoaded },
      })
    }
  }
  
  return { 
    desktopEntries, 
    stashEntryCount: entries.length 
  }
}

export async function popStashEntry(
  repository: Repository,
  stashSha: string
): Promise<void> {
  const expectedErrors = new Set<DugiteError>([DugiteError.MergeConflicts])
  const stashToPop = await getStashEntryMatchingSha(repository, stashSha)
  
  if (stashToPop !== null) {
    const args = ['stash', 'pop', '--quiet', `${stashToPop.name}`]
    
    await git(args, repository.path, 'popStashEntry', {
      expectedErrors,
    }).catch(e => {
      // If pop succeeds but exits with 1 (conflicts with no stderr),
      // manually drop the stash
      if (e instanceof GitError && 
          e.result.exitCode === 1 && 
          e.result.stderr.length === 0) {
        return dropDesktopStashEntry(repository, stashSha)
      }
      return Promise.reject(e)
    })
  }
}

export async function dropDesktopStashEntry(
  repository: Repository,
  stashSha: string
) {
  const entryToDelete = await getStashEntryMatchingSha(repository, stashSha)
  
  if (entryToDelete !== null) {
    const args = ['stash', 'drop', entryToDelete.name]
    await git(args, repository.path, 'dropStashEntry')
  }
}

export async function moveStashEntry(
  repository: Repository,
  { stashSha, parents, tree }: IStashEntry,
  branchName: string
) {
  const message = `On ${branchName}: ${createDesktopStashMessage(branchName)}`
  const parentArgs = parents.flatMap(p => ['-p', p])
  
  // Create new commit with updated message
  const { stdout: commitId } = await git(
    ['commit-tree', ...parentArgs, '-m', message, '--no-gpg-sign', tree],
    repository.path,
    'moveStashEntryToBranch'
  )
  
  // Store the new stash
  await git(
    ['stash', 'store', '-m', message, commitId.trim()],
    repository.path,
    'moveStashEntryToBranch'
  )
  
  // Delete the old stash
  await dropDesktopStashEntry(repository, stashSha)
}

export async function getStashedFiles(
  repository: Repository,
  stashSha: string
): Promise<ReadonlyArray<CommittedFileChange>> {
  const args = [
    'stash',
    'show',
    stashSha,
    '--raw',
    '--numstat',
    '-z',
    '--format=format:',
    '--no-show-signature',
    '--',
  ]
  
  const { stdout } = await git(args, repository.path, 'getStashedFiles')
  
  return parseRawLogWithNumstat(stdout, stashSha, `${stashSha}^`).files
}

Scenario: Working on feature, need to quickly fix bug

1. Have uncommitted changes on feature-branch
2. Try to switch to main
3. Desktop prompts to stash
4. Select "Stash changes"
5. Fix bug on main, commit, push
6. Switch back to feature-branch
7. Desktop prompts to restore stash
8. Continue working

Scenario: Need to pull but have local changes

1. Stash current changes
2. Pull latest changes from remote
3. Restore stash
4. Resolve any conflicts
5. Continue working

Scenario: Want to try something without committing

1. Stash current work
2. Experiment with changes
3. If experiment works: commit it
4. If experiment fails: discard and restore stash

# Create stash
git stash push -m "!!GitHub_Desktop<branch-name>"

# List Desktop stashes
git log -g --grep="!!GitHub_Desktop" refs/stash

# Pop stash  
git stash pop stash@{0}

# Drop stash
git stash drop stash@{0}

# View stash contents
git stash show -p stash@{0}