How does it work?

In a nutshell, devspace sync does the following:

Inject a tiny sync binary into the container and establish a real-time connection between the local devspace sync process and the binary running inside the container. Perform the initial sync of the files between the container and the filesystem on your local machine. Start a file-watcher on both sides to monitor files and sync them right when they are being changed.

If you need more than just file sync (e.g. log streaming, a terminal session or port-forwarding), take a look at the devspace dev command.

0. Select Pod & Container

Running the sync command will show you an output similar to this one:

[info] Using kube context 'docker-desktop'

[info] Using namespace 'blog-local' ? Select a pod

[Use arrows to move, space to select, type to filter]

> blog-7876b6fcd6-nzvs6

database-2123098109-jsk2la

tiller-deploy-55956c5789-cxzs8

If you only have a single pod, DevSpace will skip this question and just use the pod. To skip the question, you can also specify the --pod flag.

If the pod you choose has multiple containers, DevSpace will also ask you to select which container you want to establish the file sync connection to. To skip this question, you can provide the --container flag.

1. Inject Sync Binary

This step is the reason why DevSpace is so much faster and more reliable than any other file sync command, including kubectl cp . Most other tools have the issue that:

they transfer each file individually which is very slow or

they archive all files, then transfer them, then unpack them which takes very long until you see any changes or

they are unable to watch for changes inside the container or do this via polling (i.e. run ls -l && stat over and over again) or

over and over again) or they only support certain types of storage (e.g. only multi-read-write persistent volumes) or

they require certain libraries to be installed inside the container or

they start side-car containers

By injecting a binary directly into the running container, DevSpace ships everything needed for a reliable and super fast bi-directional code synchronization. This allows DevSpace to:

track file changes in real-time (faster and more reliable than polling)

establish a stream connection which means that the receiving end already unpacks and processes changes without having to wait for all changes (e.g. archive with updated files) to arrive first

make smart decisions about bundling and archiving many small files and transferring larger files separately

overcome minor connectivity issues through reliable retry attempts

devspace dev works out of the box with any Docker container running inside a Kubernetes cluster. The only requirement is that the tar command is available inside the container.

2. Initial Sync

The initial sync process runs a comparison of both filesystem trees before starting the real-time sync. This process makes sure that both filesystems are in sync before starting to listen to newly upcoming file changes. By default, the initial sync algorithm ensures that:

all files which exist locally but not inside the container will be uploaded to the container

all files which exist in the container but not on the local filesystem will be downloaded from the container

all files which have different content inside the container than their counterparts on the local filesystem will be overwritten with the local files, i.e. local filesystem is the single source of truth and wins in case of conflicts

If you want to run devspace sync as a one-time operation, you can provide the --no-watch flag and DevSpace will terminate after completing the initial sync process.

3. Real-Time Sync

Unless you provide the --no-watch flag, DevSpace will start the real-time sync after the initial sync is finished. Real-time sync means that DevSpace sets up file watchers on both sides (inside the container and on the local filesystem) and watches for all file changes. If a file change is detected on one side, DevSpace synchronizes the file to the other side.

When many files change at once or very quickly after each other, most file sync algorithms fail (e.g. with a fatal error) or miss important changes (e.g. due to buffer overflow). However, this is a very common scenario when you are programming. It happens for example when switching a branch with git or when installing dependencies. DevSpace reliably handles thousands of file changes which occur in parallel. If DevSpace detects that many files change in a short period of time, it does two things: