docs: add notes for Windows users

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](https://github.com/martinvonz/jj/issues/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
+```
+
+[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
+
+## 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.

mkdocs.yml

@@ -1,15 +1,15 @@
 site_name: Jujutsu docs
-site_dir:  'rendered-docs'
+site_dir: "rendered-docs"
 # Not having this (or viewing the site locally, or from any place other than the
 # site_url) leads to version switching failing to preserve the current path.
-site_url: !ENV [SITE_URL_FOR_MKDOCS, 'https://martinvonz.github.io/jj/']
+site_url: !ENV [SITE_URL_FOR_MKDOCS, "https://martinvonz.github.io/jj/"]
 theme:
-  name: 'material'
-  language: 'en'
+  name: "material"
+  language: "en"
   features:
     # - navigation.top
 
-  # Respect the users default settings and add a toggle for manually choosing 
+  # Respect the users default settings and add a toggle for manually choosing
   # automatic/light/dark palette.
   # taken from https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
   palette:
@@ -32,9 +32,9 @@ extra:
   version:
     provider: mike
 plugins:
-    - search
-    - redirects:
-        redirect_maps:
+  - search
+  - redirects:
+      redirect_maps:
 
 # Not all of these may be necessary, especially since the material
 # theme substitutes for some of them
@@ -68,50 +68,49 @@ markdown_extensions:
   - pymdownx.snippets
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_generator:
+        !!python/name:material.extensions.emoji.to_svg # This lists all the files that become part of the documentation
 
-# This lists all the files that become part of the documentation
 nav:
-- 'Home': 'index.md'
+  - "Home": "index.md"
 
-- 'Getting started':
-      - 'Installation and Setup': 'install-and-setup.md'
-      - 'Tutorial and Birds-Eye View': 'tutorial.md'
-      - 'Working with GitHub': 'github.md'
+  - "Getting started":
+      - "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'
+  - FAQ: "FAQ.md"
 
-- Concepts:
-      - 'Working Copy': 'working-copy.md'
-      - 'Branches': 'branches.md'
-      - 'Conflicts': 'conflicts.md'
-      - 'Operation Log': 'operation-log.md'
-      - 'Glossary': 'glossary.md'
+  - Concepts:
+      - "Working Copy": "working-copy.md"
+      - "Branches": "branches.md"
+      - "Conflicts": "conflicts.md"
+      - "Operation Log": "operation-log.md"
+      - "Glossary": "glossary.md"
 
-- 'Configuration':
-      - 'Settings': 'config.md'
-      - 'Revset language': 'revsets.md'
-      - 'Templating language': 'templates.md'
+  - "Configuration":
+      - "Settings": "config.md"
+      - "Revset language": "revsets.md"
+      - "Templating language": "templates.md"
 
-- 'Comparisons':
-      - 'Git comparison': 'git-comparison.md'
-      - 'Git compatibility': 'git-compatibility.md'
-      - 'Sapling': 'sapling-comparison.md'
-      - 'Other related work': 'related-work.md'
+  - "Comparisons":
+      - "Git comparison": "git-comparison.md"
+      - "Git compatibility": "git-compatibility.md"
+      - "Sapling": "sapling-comparison.md"
+      - "Other related work": "related-work.md"
 
-- 'Technical details':
-      - 'Architecture': 'technical/architecture.md'
-      - 'Concurrency': 'technical/concurrency.md'
-      - 'Conflicts': 'technical/conflicts.md'
-
-- Contributing:
-      - 'Guidelines and "How to...?"': 'contributing.md'
-      - 'Code of conduct': 'code-of-conduct.md'
-
-- 'Design docs': 
-    - 'git-submodules': 'design/git-submodules.md'
-    - 'git-submodule-storage': 'design/git-submodule-storage.md'
-    - 'JJ run': 'design/run.md'
-    - 'Tracking branches': 'design/tracking-branches.md'
+  - "Technical details":
+      - "Architecture": "technical/architecture.md"
+      - "Concurrency": "technical/concurrency.md"
+      - "Conflicts": "technical/conflicts.md"
 
+  - Contributing:
+      - 'Guidelines and "How to...?"': "contributing.md"
+      - "Code of conduct": "code-of-conduct.md"
 
+  - "Design docs":
+      - "git-submodules": "design/git-submodules.md"
+      - "git-submodule-storage": "design/git-submodule-storage.md"
+      - "JJ run": "design/run.md"
+      - "Tracking branches": "design/tracking-branches.md"