Rename a project in Azure DevOps

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

In this article, learn how to rename a project. A project rename 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.

Open organization settings

Organization settings configure resources for all projects or the entire organization. For an overview of all organization settings, see Project collection administrator role and managing collections of projects.

  1. Choose the Azure DevOps logo to open Projects, and then choose Collection settings.

    Open Organization settings

  2. Select a service from the sidebar. Settings are organized based on the service they support. Expand or collapse the major sections such as Boards and Pipelines to choose a page.

    Organization settings, Projects

  1. Choose the Azure DevOps logo to open Projects, and then choose Organization settings.

    Open Collection settings

  2. Select a service from the sidebar. Settings are organized based on the service they support. Expand or collapse the major sections such as Boards and Pipelines to choose a page.

    Organization settings, Projects

  1. Choose the gear icon to open Collection Settings.

    Organization settings, Policy page, Security policies

  2. From there, you can choose a page. Settings are organized based on the service they support.

    Organization settings, Projects

Rename a project

  1. Sign in to your organization (https://dev.azure.com/{yourorganization}), and then open the project that you want to rename.

  2. Select Project settings > Overview, and then enter a new name and select Save.

    Enter a new name, and then select Save to rename your project

  3. 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.

    Enter new project name, check the box, and then save

    Your project is renamed.

  1. From the Projects page, open the actions icon menu for the project that you want to rename and choose Rename.

    Enter a new project name

  2. Edit the name.

    Enter a new project 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.

  1. From the Overview tab, open the context icon menu for the project that you want to rename and choose Rename.

    Enter a new project name

  2. Edit the name.

    Enter a new project 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

  1. Connect to the repo.

    Connect to the repository

  2. Open the project settings.

    Project settings

  3. Open the repo settings.

    Repository settings

  4. Edit the fetch and push remote references and paste the URL that you copied from the remote repo.

    Edit remote

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:

  1. Open the Git command prompt.

  2. 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

  1. Refresh Team Explorer.

    Refresh Team Explorer

  2. Team Explorer now shows the updated repo name.

    Team Explorer Updated

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:

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.

  1. Shelve your changes.

  2. Create a new workspace mapped to the new project name.

  3. 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