Managing your code effectively on Bitbucket involves renaming repositories from time to time. 

Now you’ll see the step-by-step instructions to rename a Bitbucket repository, use the REST API, and even a workaround to move your code to a new repository. 

With careful instructions and essential precautions detailed, you're set for a seamless transition.

Let’s get started!

Rename a Repo in Bitbucket:

To change name of the Bitbucket repo:

1. You must be an admin. The ability to rename a repository in Bitbucket is typically limited to users with administrative access to that repository. This prevents unauthorized users from making major changes to the repository, such as changing its name.
2. The new name must be available. Repository names on Bitbucket must be unique within a user or team account, so you can't rename a repository to the name of an existing repository within the same account.
3. There is no specific requirement for repository size or number of files. However, if your repository is particularly large, you may experience some latency when renaming it.

Follow these steps to rename a Bitbucket repo:

1. Go to Bitbucket and log into your account.
2. Navigate to the repository you want to rename.
3. Click the "Repository settings" option in the left-hand navigation menu.
4. In the "Repository details" section, you should see an editable text box labeled "Name".
5. Change the name to whatever you want the new repository name to be.
6. Click on the "Save" button at the bottom of the screen.
7. After you rename your repository, you'll also need to update the remote URL on any local clones of the repository. This can be done using the ”git remote set-url” command.
   For example:

git remote set-url origin https://yourusername@bitbucket.org/yourusername/newreponame.git

8. This assumes that “origin” is the name of your remote. It's the default name when you clone a repo, but it could be different if you've renamed it.
9. Also note that renaming a repository could break existing links to your repository, so consider this action carefully

Rename a Bitbucket repo using REST API

Bitbucket Cloud offers Repository Access Tokens (RATs) as a way to grant scoped access to specific repositories. These tokens allow for more granular control compared to App Passwords.

To rename a Bitbucket repository using a Repository Access Token, follow these steps:

1. Generate a Repository Access Token: Log in to Bitbucket and navigate to the settings of the repository you wish to rename. Go to Access tokens under General and create a new access token with Write permissions.
2. Perform a PUT Request with the Repository Access Token: Use a tool like curl to perform a PUT request. Include the Repository Access Token in the Authorization header of the request.

Here's an example using curl:

curl --request PUT \
   --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}' \
   --header 'Authorization: Bearer YOUR_REPOSITORY_ACCESS_TOKEN' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{ "name": "NEW_REPOSITORY_NAME" }'

Replace the following placeholders with your actual values:

• {workspace}: Your workspace ID.
• {repo_slug}: The current name of your repository.
• YOUR_REPOSITORY_ACCESS_TOKEN: The Repository Access Token you generated.
• NEW_REPOSITORY_NAME: The new name you want to set for your repository.

Please be cautious that changing the name of the repository will also change its URL since the URL is derived from the name. If there is no conflict with an existing repository's slug, the new location will be returned in the Location header of the response.

Alternative: Create a new repository and move your code:

If you're looking for alternatives to renaming a repo, here's a workaround:

To create a new repository and move your code,

1. You must have write access to the old repository and admin access to the new one. You need to be able to clone (read) the old repository and push (write) to the new one. This usually means you must be at least a contributor for the old repository and an admin for the new one.
2. The new repository name must be available. As with renaming, the new repository name must be unique within your user or team account.
3. Git must be installed on your local machine. To clone the old repository and push to the new one, you need to have Git installed and be comfortable using it.

There are no specific requirements regarding repository size or number of files. However, the cloning and pushing process can take significant time for larger repositories.

You can follow these steps if you have the necessary authorization levels:

1. Create a new repository with the desired name.
2. Clone the old repository to your local machine if you haven't done so already.
3. Push the local copy of your old repository to the new repository.

Here are the git commands for steps 2 and 3:

# Clone the old repository
git clone https://yourusername@bitbucket.org/yourusername/oldreponame.git

# Navigate into the cloned repository
cd oldreponame

# Add the new repository as a remote
git remote add new-origin https://yourusername@bitbucket.org/yourusername/newreponame.git

# Push all branches and tags to the new remote
git push --all new-origin
git push --tags new-origin

Remember to replace “yourusername,” “oldreponame”, and “newreponame” with your actual username and the actual names of your old and new repositories, respectively.

This method essentially duplicates the repository under a new name. You can then delete the old repository if you wish.

Using Slack and Bitbucket?

Explore our Bitbucket apps for Slack

• Run Bitbucket pipelines in Slack
• Track pipeline status
• Automatically create Pull request channels
• Stay updated on check statuses, PR reviews, comments, and more within Slack.