Tfs Flow

TFS / TFVC Workflow

This skill applies when the project uses Team Foundation Version Control (TFVC) instead of Git. If you see a .git directory, use the git-flow skill instead. If you see a $tf/ workspace mapping or *.vssscc files, use this skill.

Detecting TFVC vs Git

Before any version control operation, check which system the project uses:

# If this succeeds, it's a git repo — use git-flow
git rev-parse --is-inside-work-tree 2>/dev/null && echo "GIT"

# If no .git, check for TFVC workspace
tf vc workspaces 2>/dev/null && echo "TFVC"

Workspace Setup

TFVC uses server workspaces (or local workspaces) mapped to local folders.

# List current workspace mappings
tf vc workspaces

# Show workspace details
tf vc workfold

# Get latest from server
tf vc get /recursive

Workspace Types

Branching Strategy

TFVC branches are server-side copies, not lightweight like Git branches.

$/Project
 ├── Main                              # Always deployable
 ├── Dev                                # Integration branch
 │    ├── Features/user-authentication  # Feature work
 │    ├── Features/payment-processing   # Feature work
 │    └── Bugfix/fix-rounding-error     # Bug fixes
 └── Releases/v1.2                      # Release stabilization

Branch Naming

Branch Commands

# Create a feature branch from Main
tf vc branch "$/Project/Main" "$/Project/Features/user-authentication"

# Merge feature into Dev (forward integration)
tf vc merge "$/Project/Features/user-authentication" "$/Project/Dev" /recursive

# Merge Dev into Main (reverse integration — after testing)
tf vc merge "$/Project/Dev" "$/Project/Main" /recursive

# Delete a completed feature branch
tf vc destroy "$/Project/Features/user-authentication"

Integration Rules

1. Forward integrate (FI): Feature → Dev. Developer merges their feature into Dev for integration testing.
2. Reverse integrate (RI): Dev → Main. After integration tests pass, merge Dev into Main.
3. Never merge directly from Feature → Main. Always go through Dev.
4. Keep branches short-lived. Merge frequently to minimize conflicts.

Adding New Files

CRITICAL: TFVC does NOT automatically track new files. Unlike Git (where git add stages everything) or .NET projects (where .csproj includes trigger VS to add files), TFVC requires you to explicitly add new files to version control. This applies to ALL file types — .ts, .js, .json, .css, .md, .html, config files, etc.

C# files created via Visual Studio may be auto-added if the project system handles it, but files created outside VS (by CLI tools, code generators, agents, or manual creation) are never auto-tracked.

# Add a single new file
tf vc add "src/components/LoginForm.tsx"

# Add all new files in a directory recursively
tf vc add "src/components/" /recursive

# Add all new files matching a pattern
tf vc add "src/**/*.ts" /recursive

# Check what's new but NOT tracked (these will be missed on checkin!)
tf vc status /recursive
# Look for files NOT listed — they're invisible to TFVC

After Creating New Files — Always Run This

After any operation that creates files (scaffolding, npm init, code generation, agent work), run:

# Find and add all untracked files in the working directory
tf vc add . /recursive 2>/dev/null

# Then verify everything is pending
tf vc status /recursive

Common Gotchas

Renaming and Moving Files

Never rename or move files using OS commands or file explorer — TFVC loses the history. Always use:

# Rename a file
tf vc rename "src/OldName.ts" "src/NewName.ts"

# Move a file to a different directory
tf vc rename "src/utils/helper.ts" "src/services/helper.ts"

Checkin Workflow

Getting Latest

# Always get latest before starting work
tf vc get /recursive

# Get latest for a specific path
tf vc get "$/Project/Main/src" /recursive

Checking Out (Edit)

# Check out a file for editing (server workspace only — local workspaces auto-detect)
tf vc checkout "src/Services/PaymentService.cs"

# Check out multiple files
tf vc checkout "src/Services/*.cs"

Viewing Pending Changes

# Show all pending changes in your workspace
tf vc status

# Show pending changes for a specific path
tf vc status "src/" /recursive

Shelving (TFVC's equivalent of stashing/draft PRs)

Shelvesets store pending changes on the server without committing them. Use shelvesets for:

• Code review before checkin
• Saving work-in-progress
• Sharing changes with another developer
• Backing up local work

# Create a shelveset
tf vc shelve "my-feature-wip" /comment:"Work in progress on user auth"

# Create and preserve local changes (don't undo local edits)
tf vc shelve "my-feature-wip" /noprompt /move:false

# List shelvesets
tf vc shelvesets

# Unshelve (restore to workspace)
tf vc unshelve "my-feature-wip"

# Delete a shelveset
tf vc shelve /delete "my-feature-wip"

Checking In

# Check in all pending changes
tf vc checkin /comment:"feat(auth): add JWT token validation"

# Check in specific files
tf vc checkin "src/Services/AuthService.cs" "src/Models/Token.cs" /comment:"feat(auth): add JWT token validation"

# Check in and associate a work item
tf vc checkin /comment:"feat(auth): add JWT token validation" /associate:12345

# Check in and resolve a work item
tf vc checkin /comment:"fix(payment): correct rounding error" /resolve:12340

# Check in with checkin notes
tf vc checkin /comment:"feat(auth): add JWT token validation" /notes:"Code Reviewer=John Smith"

Checkin Message Format

Use the same conventional commit format as git-flow — consistency across projects matters more than tool differences:

<type>(<scope>): <summary>

<body -- optional>

<footer -- optional>

Types

Summary Rules

• Imperative mood: "add" not "added" or "adds"
• Lowercase first letter
• No period at end
• Max 72 chars
• Specific: "add pagination to user list endpoint" not "improve users"

Examples — Good Checkin Messages

feat(auth): add JWT refresh token rotation

Implements automatic token rotation on refresh. Old refresh tokens
are invalidated immediately after use to prevent replay attacks.

Work Item: #12345

fix(db): prevent stale references after record deletion

Cascade cleanup now runs before confirming deletion.

Resolves: #12340

Examples — Bad Checkin Messages

# Too vague
Updated files

# No type or scope
fixed the bug

# Past tense
feat(auth): added token rotation

Work Item Association

Every checkin should associate or resolve a work item. This is how TFVC tracks what changed and why.

# Associate (link without closing)
tf vc checkin /associate:12345

# Resolve (link and set to resolved)
tf vc checkin /resolve:12340

# Multiple work items
tf vc checkin /associate:12345 /resolve:12340

Work Item Types

Before Every Checkin

# 1. Get latest and resolve conflicts
tf vc get /recursive

# 2. Add any new files that aren't tracked yet
tf vc add . /recursive 2>/dev/null

# 3. Build — must pass
<project-specific build command>

# 4. Run tests — must all pass
<project-specific test runner>

# 5. Review pending changes — verify new files appear
tf vc status /recursive

# 6. Check in
tf vc checkin /comment:"<message>" /associate:<work-item-id>

All checks must pass. Step 2 is critical — without it, new files silently stay local and break the server build.

Handling Merge Conflicts

# Merge and resolve conflicts
tf vc merge "$/Project/Features/my-feature" "$/Project/Dev" /recursive

# If conflicts arise:
# 1. tf vc resolve to launch the merge tool
tf vc resolve /auto:acceptmerge   # Auto-resolve non-conflicting
tf vc resolve "src/file.cs"       # Manual resolve for conflicting files

# 2. After resolving, verify the build
<project-specific build command>

# 3. Check in the merge result
tf vc checkin /comment:"merge(dev): integrate feature/my-feature"

Code Review via Shelvesets

TFVC doesn't have pull requests natively. Use shelvesets for code review:

1. Developer creates a shelveset: tf vc shelve "review/auth-feature"
2. Reviewer unshelves into their workspace: tf vc unshelve "review/auth-feature"
3. Reviewer reviews the code, provides feedback
4. Developer makes changes, creates a new shelveset
5. Once approved, developer checks in from their workspace

If Azure DevOps is configured, you can also use the web-based code review workflow with shelvesets.

History and Comparison

# View changeset history
tf vc history "$/Project/Main" /recursive /format:detailed

# View history for a specific file
tf vc history "src/Services/AuthService.cs"

# Compare a file with a specific changeset
tf vc diff "src/Services/AuthService.cs" /version:C12345

# View changeset details
tf vc changeset 12345

Key Differences from Git

.tfignore

Create a .tfignore file in the workspace root to exclude files from version control:

# Build outputs
bin
obj
*.dll
*.exe
*.pdb

# IDE
.vs
*.suo
*.user

# OS
Thumbs.db
.DS_Store

# Dependencies
node_modules
packages

# Environment
.env
*.local