Skip to content

docs: add file sync to coder desktop docs #17463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

EdwardAngert
Copy link
Contributor

@EdwardAngert EdwardAngert commented Apr 17, 2025

closes #16869

section could use more about:

  • sync direction options?
  • how to resolve conflicts
  • Windows?

preview

@EdwardAngert EdwardAngert added the docs Area: coder.com/docs label Apr 17, 2025
@EdwardAngert EdwardAngert self-assigned this Apr 17, 2025
@EdwardAngert EdwardAngert requested a review from matifali April 17, 2025 23:07
@matifali
Copy link
Member

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
Copy link
Member

ethanndickson commented Apr 18, 2025

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
Copy link
Member

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
Copy link
Member

matifali commented Apr 18, 2025

@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
Copy link
Contributor Author

@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

  1. set up
  2. 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

@EdwardAngert EdwardAngert marked this pull request as ready for review April 21, 2025 19:56
Comment on lines 165 to 189
## 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts on adding a Windows section here, too?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@EdwardAngert EdwardAngert Apr 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@github-actions github-actions bot added the stale This issue is like stale bread. label Apr 30, 2025
@matifali matifali removed the stale This issue is like stale bread. label Apr 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Area: coder.com/docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

docs: Coder Desktop - file sync
3 participants