usethis-python · Copilot · Feb 10, 2026 · Feb 10, 2026 · Feb 10, 2026
diff --git a/src/usethis/_tool/base.py b/src/usethis/_tool/base.py
@@ -681,6 +681,11 @@ def update_bitbucket_steps(self, *, matrix_python: bool = True) -> None:
         # If pre-commit is being used and this is not the PreCommitTool itself,
         # don't add Bitbucket steps (the tool will run via pre-commit instead)
         if is_pre_commit_used():
+            # Remove any stale Bitbucket steps before returning, but only if the
+            # tool is actually used (to avoid removing steps for tools that were
+            # never configured in this project)
+            if is_bitbucket_used() and self.is_used():
+                self.remove_bitbucket_steps()
             return
 
         self._unconditional_update_bitbucket_steps(matrix_python=matrix_python)

diff --git a/tests/usethis/_tool/impl/test_ruff.py b/tests/usethis/_tool/impl/test_ruff.py
@@ -399,3 +399,89 @@ def test_latest_version(self, tmp_path: Path):
                     "Failed to fetch GitHub tags (connection issues); skipping test"
                 )
             raise err
+
+    class TestUpdateBitbucketSteps:
+        def test_remove_stale_steps_when_pre_commit_used(
+            self, tmp_path: Path, capfd: pytest.CaptureFixture[str]
+        ):
+            """When pre-commit is enabled, stale Bitbucket steps should be removed."""
+            # Arrange - first add Bitbucket steps for Ruff
+            (tmp_path / "ruff.toml").touch()
+            (tmp_path / "pyproject.toml").write_text(
+                """\
+[project]
+name = "example"
+version = "0.1.0"
+"""
+            )
+            with change_cwd(tmp_path), files_manager():
+                from usethis._integrations.ci.bitbucket.steps import (
+                    add_placeholder_step_in_default,
+                )
+
+                add_placeholder_step_in_default(report_placeholder=False)
+                RuffTool().update_bitbucket_steps()
+
+            # Verify steps were added
+            contents_before = (tmp_path / "bitbucket-pipelines.yml").read_text()
+            assert "Run Ruff" in contents_before
+            assert "Run Ruff Formatter" in contents_before
+            capfd.readouterr()  # Clear captured output
+
+            # Act - enable pre-commit and run update_bitbucket_steps again
+            (tmp_path / ".pre-commit-config.yaml").touch()
+            with change_cwd(tmp_path), files_manager():
+                RuffTool().update_bitbucket_steps()
+
+            # Assert - stale steps should be removed
+            contents_after = (tmp_path / "bitbucket-pipelines.yml").read_text()
+            assert "Run Ruff" not in contents_after
+            assert "Run Ruff Formatter" not in contents_after
+            out, err = capfd.readouterr()
+            assert not err
+            assert "Removing 'Run Ruff'" in out
+            assert "Removing 'Run Ruff Formatter'" in out
+
+        def test_dont_remove_steps_when_tool_not_used(
+            self, tmp_path: Path, capfd: pytest.CaptureFixture[str]
+        ):
+            """When pre-commit is enabled but tool isn't used, don't remove steps."""
+            # Arrange - create Bitbucket steps manually (simulating legacy config)
+            # but DON'T create ruff.toml (tool is not actually used)
+            (tmp_path / "pyproject.toml").write_text(
+                """\
+[project]
+name = "example"
+version = "0.1.0"
+"""
+            )
+            (tmp_path / "bitbucket-pipelines.yml").write_text(
+                """\
+image: atlassian/default-image:3
+pipelines:
+    default:
+      - step:
+            name: Run Ruff
+            script:
+              - ruff check
+      - step:
+            name: Some Other Step
+            script:
+              - echo "hello"
+"""
+            )
+
+            # Act - enable pre-commit and run update_bitbucket_steps
+            # (tool is NOT used, so steps should NOT be removed)
+            (tmp_path / ".pre-commit-config.yaml").touch()
+            with change_cwd(tmp_path), files_manager():
+                RuffTool().update_bitbucket_steps()
+
+            # Assert - steps should NOT be removed because tool is not used
+            contents_after = (tmp_path / "bitbucket-pipelines.yml").read_text()
+            assert "Run Ruff" in contents_after
+            assert "Some Other Step" in contents_after
+            out, err = capfd.readouterr()
+            assert not err
+            # Should not contain any removal messages
+            assert "Removing" not in out