From b2800f7f4474d2dbd8c7a41860a3690d8988f99d Mon Sep 17 00:00:00 2001
From: Stephen Jennings <stephen.g.jennings@gmail.com>
Date: Sat, 27 Jan 2024 11:56:36 -0800
Subject: [PATCH] docs: add notes for Windows users

---
 docs/windows.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml      |  1 +
 2 files changed, 65 insertions(+)
 create mode 100644 docs/windows.md

diff --git a/docs/windows.md b/docs/windows.md
new file mode 100644
index 000000000..5cc8759d7
--- /dev/null
+++ b/docs/windows.md
@@ -0,0 +1,64 @@
+# Working on Windows
+
+Jujutsu works the same on all platforms, but there are some caveats that Windows
+users should be aware of.
+
+## Line endings are not converted
+
+Jujutsu does not honor `.gitattributes` and does not have a setting like Git's
+`core.autocrlf`. This means that line endings will be checked out exactly as
+they are committed and committed exactly as authored. This is true on all
+platforms, but Windows users are most likely to miss CRLF conversion.
+
+## Pagination
+
+[Pagination is disabled by default on Windows][issue-2040] because Windows
+doesn't ship with a usable pager.
+
+If you have Git installed, you can use Git's pager and re-enable pagination:
+
+```powershell
+PS> jj config set --user ui.pager '["C:\\Program Files\\Git\\usr\\bin\\less.exe", "-FRX"]'
+PS> jj config set --user ui.paginate auto
+```
+
+## Typing `@` in PowerShell
+
+PowerShell uses `@` as part the [array sub-expression operator][array-op], so it
+often needs to be escaped or quoted in commands:
+
+```powershell
+PS> jj log -r `@
+PS> jj log -r '@'
+```
+
+One solution is to create a revset alias. For example, to make `HEAD` an alias
+for `@`:
+
+```powershell
+PS> jj config set --user revset-aliases.HEAD '@'
+PS> jj log -r HEAD
+```
+
+## WSL sets the execute bit on all files
+
+When viewing a Windows drive from WSL (via _/mnt/c_ or a similar path), Windows
+exposes all files with the execute bit set. Since Jujutsu automatically records
+changes to the working copy, this sets the execute bit on all files committed in
+your repository.
+
+If you only need to access the repository in WSL, the best solution is to clone
+the repository in the Linux file system (for example, in
+`~/my-repo`).
+
+If you need to use the repository in both WSL and Windows, one solution is to
+create a workspace in the Linux file system:
+
+```powershell
+PS> jj workspace add --name wsl ~/my-repo
+```
+
+Then only use the `~/my-repo` workspace from Linux.
+
+[issue-2040]: https://github.com/martinvonz/jj/issues/2040
+[array-op]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.4#the-array-sub-expression-operator
diff --git a/mkdocs.yml b/mkdocs.yml
index edc70dc68..764b24fef 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -78,6 +78,7 @@ nav:
       - 'Installation and Setup': 'install-and-setup.md'
       - 'Tutorial and Birds-Eye View': 'tutorial.md'
       - 'Working with GitHub': 'github.md'
+      - 'Working on Windows': 'windows.md'
 
 - FAQ: 'FAQ.md'