Support windows #26

c0rychu · 2025-11-28T21:59:28Z

Great work by @ldkv

--------- Co-authored-by: Cory Chu <[email protected]>

Copilot

Pull request overview

This PR adds comprehensive Windows support to uvlink by implementing Windows junction support as a fallback when symlinks cannot be created (typically due to permission restrictions on Windows).

Key Changes:

Introduced new path_utils.py module with Windows-specific utilities for junction creation and cross-platform path checking
Updated symlink/junction detection logic throughout the codebase to handle both symlinks and Windows junctions
Added Windows to the CI test matrix and updated workflow triggers

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`src/uvlink/path_utils.py`	New utility module providing Windows junction support, cross-platform symlink creation with fallback, and helper functions for detecting links/junctions
`src/uvlink/project.py`	Updated `rm_rf()` and `get_list()` to handle Windows junctions; improved `get_uvlink_dir()` Windows path handling
`src/uvlink/cli.py`	Replaced direct symlink operations with new utilities from `path_utils`; fixed grammar in user-facing messages
`tests/test_path_utils.py`	New test file covering junction creation, symlink fallback behavior, and error handling for invalid targets
`tests/test_project.py`	Enhanced tests for Windows compatibility with platform-specific hash expectations; refactored tilde expansion tests; replaced direct symlink creation with utility function
`tests/test_cli.py`	Updated assertions to check for both symlinks and junctions; simplified symlink removal logic; fixed cache location verification
`.github/workflows/ci-tests.yml`	Added Windows to test matrix and enabled CI on `support-windows` branch
`.github/workflows/ci-checks.yml`	Updated workflow triggers to include `support-windows` branch

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

Copilot · 2025-11-28T22:03:13Z

src/uvlink/path_utils.py

+    return path.is_symlink() or path.is_junction()
+
+
+def path_exists(path: Path) -> bool:


Missing docstring for path_exists() function. Consider adding documentation:

def path_exists(path: Path) -> bool: \"\"\"Check if a path exists, including broken symlinks or junctions. Args: path: The path to check. Returns: bool: True if the path exists or is a symlink/junction (even if broken), False otherwise. \"\"\"

Suggested change

def path_exists(path: Path) -> bool:

def path_exists(path: Path) -> bool:

"""

Check if a path exists, including broken symlinks or junctions.

Args:

path (Path): The path to check.

Returns:

bool: True if the path exists or is a symlink/junction (even if broken), False otherwise.

"""

Copilot · 2025-11-28T22:03:13Z

tests/test_cli.py

    symlink2 = project2_dir / ".venv"
-    if symlink2.exists() or symlink2.is_symlink():
-        symlink2.unlink()
+    symlink2.unlink(missing_ok=True)


Using unlink(missing_ok=True) is cleaner than the previous conditional, but consider also verifying that the symlink was successfully removed by adding assert not symlink2.exists() after the unlink call to ensure the test state is as expected.

Copilot · 2025-11-28T22:03:13Z

tests/test_project.py

+    def test_project_init_path_resolution_with_tilde(self) -> None:
+        """Test with tilde expansion and parent directory (e.g., "~/../xxx")."""
+        user_home_path = Path.home()
+        test_dir = user_home_path / "test_project"
+
+        # Test ~/test_project resolves correctly
+        p2 = Project(project_dir="~/test_project")
+        assert p2.project_dir == test_dir.resolve()
+        assert p2.project_dir.is_absolute()


This test creates a Project with path "~/test_project" but never creates the actual directory. While the test checks path resolution, it doesn't verify that the Project initialization works correctly when the directory doesn't exist. Consider either creating the directory with test_dir.mkdir(parents=True, exist_ok=True) before creating the Project, or add a separate test case to verify behavior with non-existent directories.

Copilot · 2025-11-28T22:03:14Z

src/uvlink/path_utils.py

+    subprocess.check_call(cmd, shell=True)
+
+
+def create_symlink(symlink: Path, target: Path) -> None:


Missing docstring for create_symlink() function. Consider adding comprehensive documentation:

def create_symlink(symlink: Path, target: Path) -> None: \"\"\"Create a symlink to the target directory, with Windows junction fallback. Creates the target directory if it doesn't exist. On Windows, falls back to creating a junction if symlink creation fails (e.g., due to permissions). Args: symlink: The path where the symlink should be created. target: The target directory the symlink should point to. Raises: OSError: If symlink creation fails on non-Windows platforms. \"\"\"

Suggested change

def create_symlink(symlink: Path, target: Path) -> None:

def create_symlink(symlink: Path, target: Path) -> None:

"""

Create a symlink to the target directory, with Windows junction fallback.

Ensures the target directory exists. On Windows, if symlink creation fails

(e.g., due to insufficient permissions), falls back to creating a junction.

Args:

symlink (Path): The path where the symlink should be created.

target (Path): The target directory the symlink should point to.

Raises:

OSError: If symlink creation fails on non-Windows platforms.

ValueError: If the target is not a directory when creating a junction.

"""

Copilot · 2025-11-28T22:03:14Z

tests/test_path_utils.py

+def test_create_symlink(tmp_path: Path):
+    target_dir = tmp_path / "target"
+    symlink_dir = tmp_path / "symlink"
+    create_symlink(symlink=symlink_dir, target=target_dir)
+
+    assert symlink_dir.exists()
+    assert symlink_dir.is_symlink() or (is_windows() and symlink_dir.is_junction())
+    assert symlink_dir.resolve() == target_dir.resolve()


The test test_create_symlink doesn't verify that the target directory is created by create_symlink. Consider adding an assertion before calling create_symlink to verify the target doesn't exist, and after to verify both symlink and target were created:

assert not target_dir.exists() # Before create_symlink(symlink=symlink_dir, target=target_dir) assert target_dir.exists() # After

Copilot · 2025-11-28T22:03:14Z

src/uvlink/path_utils.py

+def create_windows_junction(symlink: Path, target: Path) -> None:
+    """
+    Windows junctions are similar to symlinks but specifically for directories.
+    Does not require admin privileges as symlink_to.


Grammar error: "as symlink_to" should be "as symlink_to does" or "unlike symlink_to" for clarity. The sentence is missing a verb.

Suggested change

Does not require admin privileges as symlink_to.

Does not require admin privileges, unlike symlink_to.

Copilot · 2025-11-28T22:03:14Z

src/uvlink/path_utils.py

+    cmd = f'mklink /J "{symlink.absolute()}" "{target.absolute()}"'
+    subprocess.check_call(cmd, shell=True)


Security risk: Using shell=True with f-string formatting can lead to command injection vulnerabilities if symlink or target paths contain shell metacharacters. Use subprocess.run() with a list of arguments instead:

subprocess.check_call(['cmd', '/c', 'mklink', '/J', str(symlink.absolute()), str(target.absolute())])

Suggested change

cmd = f'mklink /J "{symlink.absolute()}" "{target.absolute()}"'

subprocess.check_call(cmd, shell=True)

cmd = ['cmd', '/c', 'mklink', '/J', str(symlink.absolute()), str(target.absolute())]

subprocess.check_call(cmd)

Copilot · 2025-11-28T22:03:15Z

tests/test_path_utils.py

+def test_create_windows_junction_invalid_target(tmp_path: Path):
+    with pytest.raises(ValueError):
+        create_windows_junction(
+            symlink=tmp_path / "any", target=tmp_path / "nonexistent"
+        )


Test test_create_windows_junction_invalid_target should be skipped on non-Windows platforms since create_windows_junction is Windows-specific. Add @pytest.mark.skipif(not is_windows(), reason="Windows junctions are only applicable on Windows.") decorator to match the pattern used in test_create_windows_junction.

Copilot · 2025-11-28T22:03:15Z

src/uvlink/path_utils.py

+from pathlib import Path
+
+
+def is_windows() -> bool:


Missing docstring for is_windows() function. Consider adding documentation explaining what this function checks and when it returns True:

def is_windows() -> bool: \"\"\"Check if the current platform is Windows. Returns: bool: True if running on Windows (win32 or nt), False otherwise. \"\"\"

Suggested change

def is_windows() -> bool:

def is_windows() -> bool:

"""

Check if the current platform is Windows.

Returns:

bool: True if running on Windows (win32 or nt), False otherwise.

"""

Copilot · 2025-11-28T22:03:15Z

src/uvlink/path_utils.py

+    return sys.platform == "win32" or os.name == "nt"
+
+
+def is_link_or_junction(path: Path) -> bool:


Missing docstring for is_link_or_junction() function. Consider adding documentation:

def is_link_or_junction(path: Path) -> bool: \"\"\"Check if a path is a symlink or Windows junction. Args: path: The path to check. Returns: bool: True if the path is a symlink or junction, False otherwise. \"\"\"

Suggested change

def is_link_or_junction(path: Path) -> bool:

def is_link_or_junction(path: Path) -> bool:

"""

Check if a path is a symlink or Windows junction.

Args:

path (Path): The path to check.

Returns:

bool: True if the path is a symlink or junction, False otherwise.

"""

c0rychu and others added 4 commits November 27, 2025 21:35

chore: update CI to include windows

36d2352

chore: update CI workflows to support-windows branch

f1f17f6

feat: use junction instead of symlink for Windows (#23)

9d73d95

--------- Co-authored-by: Cory Chu <[email protected]>

fix: adapt tests for Windows (#24)

d8694f1

c0rychu requested a review from Copilot November 28, 2025 21:59

Copilot started reviewing on behalf of c0rychu November 28, 2025 21:59 View session

Copilot finished reviewing on behalf of c0rychu November 28, 2025 22:02

Copilot AI reviewed Nov 28, 2025

View reviewed changes

c0rychu merged commit 6f9dce5 into main Nov 28, 2025
29 checks passed

c0rychu deleted the support-windows branch November 28, 2025 22:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support windows #26

Support windows #26

Uh oh!

c0rychu commented Nov 28, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Copilot AI Nov 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		return path.is_symlink() or path.is_junction()


		def path_exists(path: Path) -> bool:

-def path_exists(path: Path) -> bool:
+def path_exists(path: Path) -> bool:
+    """
+    Check if a path exists, including broken symlinks or junctions.
+    Args:
+        path (Path): The path to check.
+    Returns:
+        bool: True if the path exists or is a symlink/junction (even if broken), False otherwise.
+    """

		subprocess.check_call(cmd, shell=True)


		def create_symlink(symlink: Path, target: Path) -> None:

-def create_symlink(symlink: Path, target: Path) -> None:
+def create_symlink(symlink: Path, target: Path) -> None:
+    """
+    Create a symlink to the target directory, with Windows junction fallback.
+    Ensures the target directory exists. On Windows, if symlink creation fails
+    (e.g., due to insufficient permissions), falls back to creating a junction.
+    Args:
+        symlink (Path): The path where the symlink should be created.
+        target (Path): The target directory the symlink should point to.
+    Raises:
+        OSError: If symlink creation fails on non-Windows platforms.
+        ValueError: If the target is not a directory when creating a junction.
+    """

	Does not require admin privileges as symlink_to.
	Does not require admin privileges, unlike symlink_to.

		cmd = f'mklink /J "{symlink.absolute()}" "{target.absolute()}"'
		subprocess.check_call(cmd, shell=True)

		return sys.platform == "win32" or os.name == "nt"


		def is_link_or_junction(path: Path) -> bool:

Support windows #26

Support windows #26

Uh oh!

Conversation

c0rychu commented Nov 28, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants