Rename a project in Azure DevOps

09/17/2019
6 minutes to read

Azure DevOps Services | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015

In this article, learn how to rename a project. When you rename a project, it updates all of your version control paths, work items, queries, and other project artifacts to reflect the new name. Projects can be renamed multiple times and older names can be reused. Post rename, there might be some actions required from team members. We recommend performing this action during off-hours to minimize any impact.

Warning

Renaming a project sends email notifications to everyone in the project, if there are less than 1,000 users. If there are greater than 1,000 users in your project, only PCAs receive email notifications.

Rename a project

Sign in to your organization (https://dev.azure.com/{yourorganization}), and then open the project that you want to rename.
Select Project settings > Overview, and then enter a new name and select Save.
To confirm the rename, enter the new project name, check the box next to, "I understand the consequences of renaming this project," and then select Save.

Your project is renamed.

Sign in to your organization.
From the Projects page, open the actions icon menu for the project that you want to rename and choose Rename.
Edit the name.

If the Rename Project dialog doesn't appear, then you're not a member of the Project Administrators group for that particular project. Learn how to get added to the Project Administrators group.

Sign in to your organization.
From the Overview tab, open the context icon menu for the project that you want to rename and choose Rename.
Edit the name.

If the Rename Project dialog doesn't appear, then you're not a member of the Project Administrators group for that particular project. Learn how to get added to the Project Administrators group.

Let your team know what they have to do

Now that you've renamed your project, your team must restart their clients and perform additional actions based on the features they use.

Restart your clients

Opened clients keep a cache of all project names in memory and this cache isn't automatically cleared after a project is renamed. To clear the cache, all that is necessary is to restart the client so it populates the new project name. If you don't restart the client, then operations that use the cached project name fails with a project not found exception.

For the following clients, save your work in each and restart:

Visual Studio/Team Explorer
Eclipse, if your team uses the Team Foundation Server plugin (Team Explorer Everywhere)
Microsoft Excel, PowerPoint, or Project, if your team uses the Team Foundation Server Extension for these Office products
Any additional clients which use the .NET Team Foundation Server Client Object Model

Update your Git remotes

If your project uses Git, then your remote references for each repository from the renamed project need to be updated. This is due to the fact that the remote repository URL contains the project and the repository name. Git uses remote references to fetch and push changes between your local copy of a repository and the remote version stored on the server. Each member of your team must update their local Git repos to continue connecting from their dev machines to the repo in the project.

Get the new URL for the repo

Copy the repository URL to your clipboard.

Git code explorer tab

Remote URL for the repository

Update your remote in Visual Studio 2015

Connect to the repo.
Open the project settings.
Open the repo settings.
Edit the fetch and push remote references and paste the URL that you copied from the remote repo.

Update your remote in older versions of Visual Studio from the command prompt

If you use an older version of Visual Studio or work with Git from the command prompt:

Open the Git command prompt.
Go to the local repository and update the remote to the URL you copied from the remote repo.
```
 git remote set-url origin {URL_you_copied_from_the_remote_repo}
```

Refresh Team Explorer

Refresh Team Explorer.
Team Explorer now shows the updated repo name.

Update your TFVC server workspaces

If your project uses TFVC with server workspaces, these workspaces need to be updated with the new project name. For the following clients, execute a get or check-in and the workspace mapping is corrected to use the new project name:

Visual Studio 2015 (RC or newer)
Visual Studio 2013
Visual Studio 2012
Visual Studio 2010 (Only supports server workspaces)
Team Explorer Everywhere (2012 or later versions)

Source control explorer, get latest version

Update your TFVC local workspaces

If your team uses TFVC with local workspaces, these workspaces need to be updated with the new project name. For the following clients, execute a get or check-in and the workspace mapping is corrected to use the new project name:

Visual Studio 2015 (RC or later versions)
Visual Studio 2012 with Update 5 (RC or later versions)
Team Foundation Server plugin Team Explorer Everywhere 2015

We recommend that you update your clients to the latest update or release, if possible. For all other supported Visual Studio versions, except for Visual Studio 2010 which only supports server workspaces, and Team Foundation Server plugin for Eclipse, you must create a new local workspace mapped to the new project name.

Shelve your changes.
Create a new workspace mapped to the new project name.
Unshelve your changes.

Since local workspaces are managed locally and not on the server, older clients without the updated rename logic are unable to update local workspaces to the new project name on the next get or check-in.

Update your Team Foundation Server SharePoint and Reporting Integrations (on-premises)

Both SharePoint and Reporting Services integrations continue to work, but some reports don't work as expected until the new project name is populated. The old project name is still present until caches are updated with the new name. The reporting and SharePoint server administrator can manually run these jobs to immediately populate the new name.

If your team uses reports, they reflect the new names after the next incremental analysis job runs for the data warehouse. By default it runs every two hours. To expedite the process,manually run the warehouse jobs and incremental analysis job, so the new name is synced to warehouse and reports start using the new name. Reports don't work as expected until the jobs have run.
If your team uses SharePoint Integration and has custom queries or web parts which directly reference the project name, update the name in each to the new project name. All default queries and web parts don't need to be updated and continue to work. Use of @project also continues to work after a project rename and also don't need to be updated.
Excel reports and Excel web parts on MOSS don't show the right data until you execute the following.
1. Warehouse job - Run the warehouse jobs so that Excel reports contain the correct data. If the new project name is not synced to the warehouse, Excel reports don't show the correct data. To avoid this, manually run warehouse jobs.
2. SharePoint timer job - Run the "Team Foundation Server Dashboard Update" job from the SharePoint central admin to update Excel web parts on the dashboard. By default, it runs every 30 minutes. Until this job runs, the Excel web parts on the dashboard and the web parts that show reports directly from the reporting folder won't work because they'll use either the wrong project name or the wrong reporting folder.
3. SharePoint cache - Manually clear the SharePoint cache to avoid stale data, such as report folder locations, appearing in the dashboards. By default, this cache clears about every hour. You can also clear some TFS specific cache using the tfs redirect url and providing a "clearcache" parameter. For example:
```
http://<SharePointServer>/sites/<TeamProjectCollectionName>/<TeamProjectName>/_layouts/TfsRedirect.aspx?tf:type=Report&tf:clearcache=1
```