This project has moved and is read-only. For the latest updates, please go here.

Moving/renaming branches in TFS2010

May 17, 2011 at 7:47 AM

I need to move some branches around next week if possible. (I’ve already put this off longer than I should have by over-researching potential side-effects.)

Planned Rename + Move Actions:

  1. Int\Main      to Dev\Int
  2. QA\Main     to Mainline\Main             
  3. Prod\Main to Release\ProdLegacy

I have five questions that I could not answer from reading existing posts on various sites (including this branching guide and great discussion list). Does anyone have

Q1. Any issues you know of that will mess up our ability to merge existing branches after we rename + move our “Dev” and “Main” branches to different subfolders?

For example,
Will RI from child branch /Dev/Feature1 to relocated $/Platform/Dev/Int (previously named $/Platform/Int/Main) cause serious merge issues?
If yes then what should we expect and will it just be a one-time hit to correct?
Will RI from relocated child branch $/Platform/Dev/Int to relocated parent branch $/Platform/Mainline/Main cause serious merge issues?

I’ve tried reducing pending and committed changes in child branches, but many things just can’t be merged at this time (especially RI Int à Main).

Q2. How strongly would you recommend waiting to rename until after upgrading TFS2010 RTM (+latest updates) to SP1?

FYI, I’ll be scheduling a consultant to help get our partial TFS-SharePoint configuration uninstalled and then apply TFS2010 SP1.

Q3. Do you agree with ChandruR’s steps for renaming a branch in TFS 2010 - or do you have your own steps (or better yet an example/template script! J)?

Merge all changes from the branch you wish to rename to all related branches, check in these merges.
Rename the branch and checkin the rename.
Re-merge to all related branches
iv.      Look at any items which have a merge, undelete from step c). Undo the merge on them and re-merge using /discard. e.g. if $/proj/target/1.txt has a merge, undelete on it

Q4. Can we treat the original ancestor branch as a child branch (just reversing the term RI and FI) or should we go through steps (and related risks) to reparent renamed ancestor branch?

* There is a reasonable chance that future livesite hotfixes from the ancestor root branch (soon renamed to Release\ProdLegacy) will need to be merged back into Main (new root branch). Even though this is the ancestor branch such merges (FIs technically) it should be OK as long as only one Dev has rights to do these merges and RIs from Main to ProdLegacy are forbidden.

Q5. What happens to shelved changes if branch is renamed and then changes are unshelved?

My guess is that shelved changes might have the old branch path when unshelved. This could cause a bad move back to original location if checked in?
I think running the shelveset migration Power Tool command on each shelveset might be required to fix up paths for shelveset changes.

tfpt unshelve [MY_SHELVESET_NAME] /migrate /source:CURRENT_BRANCH_PATH /target:NEW_BRANCH_PATH 

Thanks in advance! -Zephan


Below are some additional thoughts and references I used to get as far as I can answering these questions online. Read on if you have spare time AND interest.


My ideal plan would be pretty straightforward:

  1. Tell all devs to commit (or delete) shelvesets they own and ask all branch owners to merge what they can before the rename date
    1. At least FI (forward integrate) to all child branches to reduce real pre-existing conflicts.
    2. Warn all devs what rename will do to their shelvesets and child branches (so they don’t get caught by surprise).
       I’d love a clear list of known impacts to developers that have shelvesets and locally mapped workspaces before a branch is renamed. 
  2. Take a full backup of TFS
  3. Rename + move the 3 branches
    I would like to assume renaming/moving a branch is a fully supported action in TFS2010 that does not trigger unexpected post-move/rename-related merge issues.
  4. Tell devs to wipe and remap their workspace (so they don’t have lingering directory structure confusion).
    I’d love to have clear steps and script commands to help devs easily get back to clean working state after a branch rename
  5. Fix build definitions to point to renamed locations
  6. Verify clean remapped local machine workspace and build definitions are working, make another backup of TFS, then call the rename a success

 I feel like I’m being paranoid, but I haven't gotten a clear sense of how disruptive (=safe/risky) to rename branches is safe in TFS2010 per this 2/25/2011 branching guide discussion (bold added for emphasis):

“…Renaming in and of itself might not be bad. But renaming and then reusing the old name might be something to avoid.


Branch Structure Before & After:

Current structure:

$/<Team Project Name>

        \Main  (Root branch)


New structure (changes in bold):

$/<Team Project Name>
(Root branch - was QA/Main)
         \ProdLegacy (Root branch - was QA/Main)


Branch Renaming discussions:

1. How to Transition from Basic to Standard to Advance discussion (Bill Heys) – 2/25/2011

Like you have seen nothing but problems arise from renaming. Periodically I get cases referred to me from Premier support where things don't seem to be working correctly (merging issues, upgrade issues from 2008 to 2010, and so on). Almost everyone of these cases has a *hidden* rename issue. Or the user deleted a file and added a different one with the same name. I don't *think* you will have a problem if you follow option one and rename Release to Service Pack and branch a new Release from it (just don't use exactly the same name as the old banch :), maybe use RTM instead) . So I suppose you will be ok following that course of action. Most of the rename issues I have seen have been on the development side. I think 2010 handles these situations better so I wouldn't be overly concerned. Renaming in and of itself might not be bad. But renaming and then reusing the old name might be something to avoid.


2. Renaming branches in TFS2010 - But it works on my PC! – by Richard Fennell (MVP) on 2/4/2011

“In TFS 2010 behind the scenes a rename is actually a branch and delete process, this meant we ended up with the new branch, but also a deleted branch of the old name. This is not obvious unless you have ‘show deleted items in source control explorer’ enabled…”

Related thread: Moved items in TFS 2010 leave 'deleted' ghosts behind


3. Renaming Branches in TFS 2010 (ChandruR’s Blog) – by Chandru R. (MSFT) on 6/9/2010

So my recommendations for this case:

1. Avoid renaming branches - a cleaner solution would be to, at the right point in your release merge all changes to a parent branch and then re-branch to create a new branch hierarchy.

Or for the brave of heart :) 

2. You will need to time the rename of your branch, to a point in your release where you can merge to all related branches. The steps to follow are: (see Q3 above)…


4. TFS 2010 wants to branch / merge every file - thread ~8/25/2010

I believe the problem was that we had created the development branches, then deleted them, then recreated them. We ran into a problem similar to this in the past where a file was deleted, then a new file was added with the same name. The fix for the past problem was to do a baseless merge. Rather than go through that we decided to just delete the development branches and rebranch them with different names.


5. TFS: Overwrite a branch with another - thread ~1/19/2010

"Delete + rebranch in <TFS> 2005/2008 runs the risk of nightmarish-to-debug namespace conflicts in the future. " - Amen to that! – AakashM Jan 19 '10 at 15:11

No problems that I can think of (apart from the fact that un-deleting the old branch would be difficult if you ever wanted to do that) – Martin Woodward Jan 20 '10 at 16:01

(*Notice date is early 2010 so any TFS2010-specific issues likely unknown at the time.)


TFS 2010 SP1 rename/move fixes:

  • A lock on a file is orphaned on check in when the parent is renamed and checked in in another workspace.
  • A candidate delete is lost when you perform a merge in a folder rename.
  • When you try to merge a rename and a delete on a file, the results cause inconsistencies in the version control database.
  • When you convert a folder that has subfolders to a branch folder on a hierarchy root folder, and then you rename the folder and its subfolders, Visual Studio crashes.
  • Unshelve reports bogus errors about a null DownloadUrl when dependent renames are shelved, and child item names overlap.
  • An issue in merge causes a conflict not to be generated when there is a rename in the target and source.

Hopefully the above questions and background research give others a single location to make informed decisions regarding branch renaming. All comments are welcome, so chime in on any pieces or the whole thing.

Thanks! - ZephanS


(PS: Some content and lots of formatting got lost moving this from an e-mail I drafted. Sorry if I missed anything.)

May 17, 2011 at 1:44 PM

As I mentioned previously in discussions in this forum, renaming files, folders, and branches has been an ongoing source of problems in TFS. Many of these problems were noticed for the first time when migrating from TFS 2008 to TFS 2010 and had to do with the new (slote mode) way of indentifying items in TFS 2010.

Chandru, in his blog, cautions: "With the switch over to slot mode in TFS 2010 renaming branch roots can lead to situations where the next merge from the renamed branch to related branches will generate more than necessary conflicts. The reason for this is that when you rename the root of a branch, the source of the rename is considered out of scope of the merge - hence we do not consider the merge history of the source name - so items where the content differs between the source and target since the last merge will be baseless merged. Below is an example which demonstrates this behavior"

Rather than renaming multiple branches, is it possible to rename/move the branch that will become your new root branch, and create new branches from there?

Bill Heys
VS ALM Ranger

May 17, 2011 at 1:46 PM

I would definitely upgrade to SP1 before beginning the rename process.


May 17, 2011 at 6:32 PM
Edited May 17, 2011 at 9:10 PM

Bill: Thanks as always for your insights and opinions.

I forgot to mention that I have at least 6 active developer branches that are children of the current Int/Main branch :-(. I could move QA\Main to be Mainline\Main and then branch fresh new structure from this new root node, but I would have several grandchild branches (through another renamed branch) that would effectively produce the same baseless merge situation :-(. I will have to think much harder and act strategically to come up with a process and timeframe when all branches can be merged (or changes abandoned) to do a consolidated rename without lots of loose ends.

NOTE TO ALL READERS: This isn't just a TFS issue. 

I understand it is very challenging to implement branch renaming. For simple branch structures the existing rename functionality is sufficient and quite useful.

I spoke with a CM Dev lead who recently told me that they had equal challenges renaming branches in ClearCase. Their process is what Bill suggests: Create new branch, then branch from that new root branch and obsolete (retire/delete) the old branch. In fact this is what TFS does under the hood (branch source branch to new name, then mark source branch as deleted). The challenge is when you have children of originally named branch (hence Chandru's recommendation to merge all in, then rename).

TFS FEATURE SUGGESTION: For 3+ level branch hierarchies I'd recommend a rename warning appear stating next merge with child branches may treat differences as baseless merges. Better yet, consider also creating a branch renaming power tool (check branch depth, then if there are pending changes in children or parent walks the user through steps to inform them (and impacted developers) of potential baseless merges and help guide through steps to mitigate impact of rename (perhaps helping by creating a merge checklist to complete before rename to reduce conflicts).


Remaining questions (anyone is free to answer or comment based on experience):

Q3. Do you agree with ChandruR’s steps for renaming a branch in TFS 2010 - or do you have your own steps (or better yet an example/template script!)?

Idea: This looks like a good place for a new "Branch Rename" power tool

Q4. Can we treat the original ancestor branch as a child branch (just reversing the term RI and FI)... Moving this question to a separate discussion post because it is independant of whether a rename is made or not.

Q5. What happens to shelved changes if branch is renamed and then changes are unshelved?

May 17, 2011 at 6:50 PM

In and of itself, if you *understand* what happens during a baseless merge, you should be able to manage around it. For example, deletes are not propagated with a baseless merge. This explains some of the Chandru's comments. With a based merge, you can use the history to better understand how the merge should happen. You will know the difference between a file is added to the source branch and not yet merged (added) to the target branch. Or a file is deleted in the source branch and must be deleted from the target branch. Now you understand why baseless merges do NOT propagate deletes. It doesn't have a common base and history to properly identify how to handle a delete.

Similarly when you have changes to a file in both the source and target branches you have merge conflicts to resolve. Without a common base and history, you will simply have more conflicts to understand and resolve.

Once the baseless merge takes place, a new merge relationship is established. Future merges are not baseless.

I am not sure about creating a branch renaming power tool. Doing so might encourage more frequent (reckless) branch renaming. I would prefer to make it painful rather than automatic.

I tend to agree with Chandru's recommended steps for renaming a branch. (Q3)

I see no particular reason why you can't logicall invert the relationship between parent and child (Q4).

I do not know what happens with shelved changes. I might post that question internally and drive for an answer. (Q5).

Bill Heys
VS ALM Ranger


May 17, 2011 at 6:56 PM

According to Brian Harry, TFS 2010 will handle shelvesets just fine after a branch is subsequently renamed.


May 17, 2011 at 7:56 PM

Clarification from the product group

I want to clarify some behavior here.  In TFS 2010 Unshelve will follow pending renames but it will not follow renames committed between when the shelveset was created and the current workspace version.  So, let’s look at this in two cases.


Case 1:


  1. In some workspace, an edit is made to $/Proj/Main/foo.txt and is shelved in a shelveset named “changes”.
  1. In your workspace, you have a pending rename on the branch such that $/Proj/Main will become $/Proj/Main2010.
  1. You try to unshelve the shelveset named “changes” into your workspace.


In this case, the change on foo.txt will be unshelved in the local folder that corresponds to $/Proj/Main2010 since that rename is currently pending in your workspace.


Case 2:


  1. In some workspace, an edit is made to $/Proj/Main/foo.txt and is shelved in a shelveset named “changes”.
  1. In your workspace, you pend rename on the branch such that $/Proj/Main will become $/Proj/Main2010.
  1. You check in your changes to rename $/Proj/Main to $/Proj/Main2010.
  1. You try to unshelve the shelveset named “changes”.


In this case, the change on foo.txt will be unshelved in the local folder that corresponds to $/Proj/Main and not the newly renamed branch.  In order to fix this, you can issue a “Get” for your workspace.  Get will file conflicts that will force you to select the proper location for this change and allow you to move the unshelved changes under the renamed branch.


I am happy to say that we will be improving the behavior in case 2 for TFS 2012.


Let me know if you have any other questions.

May 17, 2011 at 8:19 PM

Outstanding answers Bill. Thank you for taking the time to answer all my questions in such depth (including clarification of unshelve behavior after related branch rename has been committed).




May 17, 2011 at 9:07 PM

One more point from the product group:

If you aren’t aware already, renaming branches in TFS 2010 is a very bad idea unless you follow a very specific set of steps:

Bill Heys
VS ALM Ranger

May 17, 2011 at 9:25 PM
Edited May 18, 2011 at 5:50 PM

Chandru's "Renaming-branches-in-tfs-2010" link is reference #3 in my original post. I agree it is important enough to point out separately.

Hmm, on further thought I half-share your preference of renaming being painful over recklessly automated. It would have been really easy for me to nievely renamed my three branches, then wonder why unexpected baseless merge behaviors start occuring sometime later after the rename is forgotten. The dialog (or wizard if multiple screens with logic) I'd like to see would notice I have several other child branches that will be impacted by the rename and present additional information that tells me what kind of pain I might be in for if I choose to continue the rename.

Rename confirmation dialog:

  • Warning: You have X child branches (excluding deleted branches) that may treat any pending differences as baseless merge the first time you merge with them after renaming this branch. Open the following link for more Rename Branch information.

Branch renaming is probably a good topic to also touch on in the next TFS Branching Guide under branch maintenance.

Thanks again! - ZephanS