docs: add file sync to coder desktop docs #17463

EdwardAngert · 2025-04-17T23:00:04Z

closes #16869

section could use more about:

sync direction options?
how to resolve conflicts
EA --> Beta

preview

matifali · 2025-04-18T05:44:44Z

Sync direction is bi directional and settings for this are currently out of scope.

Merge conflict resolution is also out of scope for now.

@ethanndickson to confirm please.

ethanndickson · 2025-04-18T05:53:04Z

Sync direction is bi directional and settings for this are currently out of scope.
Merge conflict resolution is also out of scope for now.

Correct. We're using the two-way-safe Mutagen bi-directional sync mode:

In this bidirectional synchronization mode, both endpoints are treated with equal precedence, and conflicts are only automatically resolved if they don’t result in data loss (for example, modifications on one endpoint can can overwrite deletions of the corresponding content on the other endpoint). If conflicts can’t be automatically resolved, they are stored in the session state (and can be enumerated with the mutagen sync list command).

There's no easy way to configure Coder Desktop to use another of the Mutagen modes (i.e. non-bidi sync) right now.

For conflicts that aren't automatically resolved, the user can just delete the conflicting file on the side that has the version they'd like to discard.

One thing to note is that VCS directories (namely, .git/) are excluded from all sync sessions. See the Mutagen documentation as to why. A GitHub repo should be cloned onto whichever side you would like to run git commands from. You won't be able to run them from both sides.

matifali · 2025-04-18T10:27:41Z

For conflicts that aren't automatically resolved, the user can just delete the conflicting file on the side that has the version they'd like to discard.

@EdwardAngert, this is a good enough explanation to put in the docs for conflict resolution.

matifali · 2025-04-18T10:32:26Z

@EdwardAngert, I feel the page is too long.
I suggest we split this into multiple pages. WDYT?

Coder Desktop/
├── Installation and Setup
├── Coder Connect
└── File Sync

EdwardAngert · 2025-04-21T19:52:56Z

@EdwardAngert, I feel the page is too long. I suggest we split this into multiple pages. WDYT?
Coder Desktop/
├── Installation and Setup
├── Coder Connect
└── File Sync

I think we're close to that

I think the screenshots make this feel longer than it is + file sync would look pretty lonely on its own page, but we might be able to cut it into

set up
use

but I'm having some trouble with "Coder Connect" because it doesn't really tell a user what it does, and if I'm a Coder Desktop user, I don't really know what Coder Connect is aside from being the button I click. Splitting things up should be another PR

matifali · 2025-04-21T20:06:55Z

docs/user-guides/desktop/index.md

+## Sync a local directory with your workspace
+
+Coder Desktop file sync provides bidirectional synchronization between a local directory and your workspace.
+You can work offline, add screenshots to documentation, or use local development tools while keeping your files in sync with your workspace.
+
+1. Create a new local directory.
+
+   If you select an existing clone of your repository, Desktop will recognize it as conflicting files.
+
+1. In the Coder Desktop app, select **File sync**.
+
+   ![Coder Desktop File Sync screen](../../images/user-guides/desktop/coder-desktop-file-sync.png)
+
+1. Select the **+** in the corner to select the local path, workspace, and remote path, then select **Add**:
+
+   ![Coder Desktop File Sync add paths](../../images/user-guides/desktop/coder-desktop-file-sync-add.png)
+
+1. File sync clones your workspace directory to your local directory, then watches for changes:
+
+   ![Coder Desktop File Sync watching](../../images/user-guides/desktop/coder-desktop-file-sync-watching.png)
+
+File sync excludes version control system directories like `.git/` from synchronization, so keep your Git-cloned repository wherever you run Git commands.
+This means that if you use an IDE with a built-in terminal to edit files on your remote workspace, that should be the Git clone and your local directory should be for file syncs.
+
+If you encounter a synchronization conflict, delete the conflicting file that contains changes you don't want to keep.


Thoughts on adding a Windows section here, too?

Can we also add a note or two on what Ethan described here in the comment?

the mutagen stuff?

I guess we could - I skipped it for user-facing documentation. it's good for us to know how it works or why it could change one day, but there doesn't seem to be anything a Desktop user could do about it. Is there? Mutagen docs @ethanndickson linked to say that the git stuff should be excluded, so even if there is a workaround, we're probably safer not suggesting it

ethanndickson · 2025-04-22T02:17:25Z

docs/images/user-guides/desktop/coder-desktop-file-sync-staging.png

One thing users might not pick up on is that they can hover over the Status (or either path, or the size) for a longer description of it, or, in the case of file sync conflicts, to see what files are conflicting. Can one of these screenshots include the user hovering over the status?

I added a line to the steps about the mouseover, and added a File sync conflicts section in 42e7648

EdwardAngert · 2025-05-05T19:34:43Z

@matifali @ethanndickson is there anything we want to add to this PR before release? @ethanndickson would a windows screenshot add anything? do you have one on hand?

ethanndickson

Looking good, just one comment on something that's changed.

@deansheather is there any Windows functionality that you think we should include a screenshot of? Both platforms are pretty much identical feature-wise, so I think it's fine like this.

ethanndickson · 2025-05-06T02:20:45Z

docs/user-guides/desktop/index.md

+> [!NOTE]
+> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.


This is no longer true if the user is running a Coder deployment of version 2.22 or later. IDE extensions connected to older server versions still have this issue.

Better to remove the note instead of making it more explicit to explain the difference in behaviour.

Why's that?

I am in favor of simpler docs. Eventually, all users, when upgraded to version 2.22, will be using the Coder Connect tunnels. So IMO its better to leave this out.

Or we can say, as per version 2.22 of Coder IDE, extensions can also make use of the Coder Connect tunnel to improve performance

Suggested change

> [!NOTE]

> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.

> [!NOTE]

> For Coder versions v2.21.3 and earlier: the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.

@matifali - does this feel like a good balance?

for now, because it's all but the newest version, I think we need to have some indication of who's affected

It's perfect.

deansheather · 2025-05-06T02:28:05Z

They're pretty much the same but with different UIs. The latest release on GitHub has it all included if you want to take a look @EdwardAngert

matifali · 2025-05-06T03:30:43Z

@EdwardAngert can you also move the docs labels to Beta in same PR?

EdwardAngert · 2025-05-06T03:49:45Z

@EdwardAngert can you also move the docs labels to Beta in same PR?

@matifali I thought I caught the early access tags - did you find one I missed?

matifali · 2025-05-06T06:03:16Z

It's all good.

EdwardAngert and others added 3 commits April 17, 2025 21:50

beta tag; confirm steps

940bfe6

desktop file sync

749d839

Merge branch 'main' into 16869-desktop-file-sync

9dd403e

EdwardAngert added the docs Area: coder.com/docs label Apr 17, 2025

EdwardAngert self-assigned this Apr 17, 2025

EdwardAngert requested a review from matifali April 17, 2025 23:07

sync direction and merge conflict resolution

b1f9356

EdwardAngert marked this pull request as ready for review April 21, 2025 19:56

matifali reviewed Apr 21, 2025

View reviewed changes

ethanndickson reviewed Apr 22, 2025

View reviewed changes

add status tooltip

c43c528

matifali approved these changes Apr 22, 2025

View reviewed changes

EdwardAngert and others added 2 commits April 22, 2025 15:27

file sync conflicts

42e7648

Merge branch 'main' into 16869-desktop-file-sync

e02a3ab

github-actions bot added the stale This issue is like stale bread. label Apr 30, 2025

matifali removed the stale This issue is like stale bread. label Apr 30, 2025

ethanndickson approved these changes May 6, 2025

View reviewed changes

EdwardAngert added 3 commits May 9, 2025 15:27

md images

006439a

alpha beta

55c7334

Merge branch 'main' into 16869-desktop-file-sync

b57d879

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add file sync to coder desktop docs #17463

docs: add file sync to coder desktop docs #17463

EdwardAngert commented Apr 17, 2025 •

edited

Loading

matifali commented Apr 18, 2025

ethanndickson commented Apr 18, 2025 •

edited

Loading

matifali commented Apr 18, 2025

matifali commented Apr 18, 2025 •

edited

Loading

EdwardAngert commented Apr 21, 2025

matifali Apr 21, 2025

matifali Apr 21, 2025

EdwardAngert Apr 22, 2025 •

edited

Loading

ethanndickson Apr 22, 2025

EdwardAngert Apr 22, 2025

EdwardAngert commented May 5, 2025

ethanndickson left a comment

ethanndickson May 6, 2025

matifali May 6, 2025

ethanndickson May 6, 2025

matifali May 6, 2025

EdwardAngert May 6, 2025

EdwardAngert May 6, 2025

matifali May 6, 2025

deansheather commented May 6, 2025

matifali commented May 6, 2025

EdwardAngert commented May 6, 2025

matifali commented May 6, 2025

		> [!NOTE]
		> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.

docs: add file sync to coder desktop docs #17463

Are you sure you want to change the base?

docs: add file sync to coder desktop docs #17463

Conversation

EdwardAngert commented Apr 17, 2025 • edited Loading

matifali commented Apr 18, 2025

ethanndickson commented Apr 18, 2025 • edited Loading

matifali commented Apr 18, 2025

matifali commented Apr 18, 2025 • edited Loading

EdwardAngert commented Apr 21, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

EdwardAngert Apr 22, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

EdwardAngert commented May 5, 2025

ethanndickson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deansheather commented May 6, 2025

matifali commented May 6, 2025

EdwardAngert commented May 6, 2025

matifali commented May 6, 2025

EdwardAngert commented Apr 17, 2025 •

edited

Loading

ethanndickson commented Apr 18, 2025 •

edited

Loading

matifali commented Apr 18, 2025 •

edited

Loading

EdwardAngert Apr 22, 2025 •

edited

Loading