Preserve local changes option

README.md

@@ -96,6 +96,12 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Default: true
     clean: ''
 
+    # Whether to preserve local changes during checkout. If true, tries to preserve
+    # local files that are not tracked by Git. By default, all files will be
+    # overwritten.
+    # Default: false
+    preserve-local-changes: ''
+
     # Partially clone against a given filter. Overrides sparse-checkout if set.
     # Default: null
     filter: ''
@@ -332,6 +338,21 @@ jobs:
 
 *NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
 
+## Preserve local changes during checkout
+
+```yaml
+steps:
+  - name: Create file before checkout
+    shell: pwsh
+    run: New-Item -Path . -Name "example.txt" -ItemType "File"
+
+  - name: Checkout with preserving local changes
+    uses: actions/checkout@v5
+    with:
+      clean: false
+      preserve-local-changes: true
+```
+
 # Recommended permissions
 
 When using the `checkout` action in your GitHub Actions workflow, it is recommended to set the following `GITHUB_TOKEN` permissions to ensure proper functionality, unless alternative auth is provided via the `token` or `ssh-key` inputs:

__test__/git-auth-helper.test.ts

@@ -814,6 +814,7 @@ async function setup(testName: string): Promise<void> {
     submodules: false,
     nestedSubmodules: false,
     persistCredentials: true,
+    preserveLocalChanges: false,
     ref: 'refs/heads/main',
     repositoryName: 'my-repo',
     repositoryOwner: 'my-org',

__test__/git-directory-helper.test.ts

@@ -143,12 +143,41 @@ describe('git-directory-helper tests', () => {
       repositoryPath,
       repositoryUrl,
       clean,
-      ref
+      ref,
+      false // preserveLocalChanges = false
     )
 
     // Assert
     const files = await fs.promises.readdir(repositoryPath)
-    expect(files).toHaveLength(0)
+    expect(files).toEqual(['.git']) // Expect just the .git directory to remain
+    expect(git.tryClean).toHaveBeenCalled()
+    expect(core.warning).toHaveBeenCalled()
+    expect(git.tryReset).not.toHaveBeenCalled()
+  })
+
+  const preservesContentsWhenCleanFailsAndPreserveLocalChanges = 'preserves contents when clean fails and preserve-local-changes is true'
+  it(preservesContentsWhenCleanFailsAndPreserveLocalChanges, async () => {
+    // Arrange
+    await setup(preservesContentsWhenCleanFailsAndPreserveLocalChanges)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    let mockTryClean = git.tryClean as jest.Mock<any, any>
+    mockTryClean.mockImplementation(async () => {
+      return false
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean,
+      ref,
+      true // preserveLocalChanges = true
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file']) // Expect both .git and user files to remain
     expect(git.tryClean).toHaveBeenCalled()
     expect(core.warning).toHaveBeenCalled()
     expect(git.tryReset).not.toHaveBeenCalled()
@@ -170,16 +199,50 @@ describe('git-directory-helper tests', () => {
       repositoryPath,
       differentRepositoryUrl,
       clean,
-      ref
+      ref,
+      false // preserveLocalChanges = false
     )
 
     // Assert
     const files = await fs.promises.readdir(repositoryPath)
-    expect(files).toHaveLength(0)
+    expect(files).toEqual(['.git']) // Expect just the .git directory to remain
     expect(core.warning).not.toHaveBeenCalled()
     expect(git.isDetached).not.toHaveBeenCalled()
   })
 
+  const keepsContentsWhenDifferentRepositoryUrlAndPreserveLocalChanges =
+    'keeps contents when different repository url and preserve-local-changes is true'
+  it(keepsContentsWhenDifferentRepositoryUrlAndPreserveLocalChanges, async () => {
+    // Arrange
+    await setup(keepsContentsWhenDifferentRepositoryUrlAndPreserveLocalChanges)
+    clean = false
+
+    // Create a file that we expect to be preserved
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    // Simulate a different repository by simply removing the .git directory
+    await io.rmRF(path.join(repositoryPath, '.git'))
+    await fs.promises.mkdir(path.join(repositoryPath, '.git'))
+
+    const differentRepositoryUrl = 'https://github.com/my-different-org/my-different-repo'
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      differentRepositoryUrl, // Use a different URL
+      clean,
+      ref,
+      true // preserveLocalChanges = true
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    console.log('Files after operation:', files)
+    // When preserveLocalChanges is true, files should be preserved even with different repo URL
+    expect(files.sort()).toEqual(['.git', 'my-file'].sort())
+  })
+
   const removesContentsWhenNoGitDirectory =
     'removes contents when no git directory'
   it(removesContentsWhenNoGitDirectory, async () => {
@@ -221,12 +284,41 @@ describe('git-directory-helper tests', () => {
       repositoryPath,
       repositoryUrl,
       clean,
-      ref
+      ref,
+      false // preserveLocalChanges = false
     )
 
     // Assert
     const files = await fs.promises.readdir(repositoryPath)
-    expect(files).toHaveLength(0)
+    expect(files).toEqual(['.git']) // Expect just the .git directory to remain
+    expect(git.tryClean).toHaveBeenCalled()
+    expect(git.tryReset).toHaveBeenCalled()
+    expect(core.warning).toHaveBeenCalled()
+  })
+
+  const preservesContentsWhenResetFailsAndPreserveLocalChanges = 'preserves contents when reset fails and preserve-local-changes is true'
+  it(preservesContentsWhenResetFailsAndPreserveLocalChanges, async () => {
+    // Arrange
+    await setup(preservesContentsWhenResetFailsAndPreserveLocalChanges)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+    let mockTryReset = git.tryReset as jest.Mock<any, any>
+    mockTryReset.mockImplementation(async () => {
+      return false
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean,
+      ref,
+      true // preserveLocalChanges = true
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file']) // Expect both .git and user files to remain
     expect(git.tryClean).toHaveBeenCalled()
     expect(git.tryReset).toHaveBeenCalled()
     expect(core.warning).toHaveBeenCalled()
@@ -246,12 +338,13 @@ describe('git-directory-helper tests', () => {
       repositoryPath,
       repositoryUrl,
       clean,
-      ref
+      ref,
+      false // preserveLocalChanges = false
     )
 
     // Assert
     const files = await fs.promises.readdir(repositoryPath)
-    expect(files).toHaveLength(0)
+    expect(files).toEqual(['.git']) // Expect just the .git directory to remain
     expect(core.warning).not.toHaveBeenCalled()
   })
 
@@ -302,12 +395,13 @@ describe('git-directory-helper tests', () => {
       repositoryPath,
       repositoryUrl,
       clean,
-      ref
+      ref,
+      false // preserveLocalChanges = false
     )
 
     // Assert
     const files = await fs.promises.readdir(repositoryPath)
-    expect(files).toHaveLength(0)
+    expect(files).toEqual(['.git']) // Expect just the .git directory to remain
     expect(git.tryClean).toHaveBeenCalled()
   })
 

action.yml

@@ -56,7 +56,10 @@ inputs:
     description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
   clean:
     description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
-    default: true
+    default: 'true'
+  preserve-local-changes:
+    description: 'Whether to preserve local changes during checkout. If true, tries to preserve local files that are not tracked by Git. By default, all files will be overwritten.'
+    default: 'false'
   filter:
     description: >
       Partially clone against a given filter.