# How two-way sync works

> For the complete documentation index, see [llms.txt](https://falconer.com/docs/llms.txt).

Keep a Falconer space and a GitHub repository in sync, in both directions.


Keep a Falconer space and a GitHub repository in sync, in both directions.

Two-way sync is built for teams that keep their docs as Markdown in a repository. Engineers keep working in Git, and everyone else edits the same docs in Falconer.

## How it works

A synced space mirrors one path of a repository on one branch.

- **From GitHub to Falconer:** commits to the synced branch are pulled into the space automatically.
- **From Falconer to GitHub:** edits you make in Falconer are pushed as a commit or a pull request when you're ready.

Nothing reaches GitHub until someone pushes it, so you can draft and edit in Falconer without touching the repository.

When the same document changes on both sides, Falconer shows a conflict and lets you choose which changes to keep.

## What maps to what

| In the repository | In Falconer |
| --- | --- |
| `.md` and `.mdx` files | Documents in the **Docs** tab |
| Directories | Folders |
| Images and every other file | Files in the **Files** tab |

## The sync loop

1. [Set up two-way sync](https://falconer.com/docs/two-way-sync/set-up-two-way-sync.md) on a space and import the repository.
2. Edit documents in Falconer. [Sync status](https://falconer.com/docs/two-way-sync/sync-status.md) shows what hasn't been pushed yet.
3. [Push your changes](https://falconer.com/docs/two-way-sync/push-changes.md) as a commit or a pull request.
4. [Changes made on GitHub](https://falconer.com/docs/two-way-sync/pull-changes-from-github.md) flow back into Falconer.

## Learn more

- [Move, rename, and delete](https://falconer.com/docs/two-way-sync/move-rename-delete.md)
- [Images and other files](https://falconer.com/docs/two-way-sync/images-and-files.md)
- [Manage or disconnect sync](https://falconer.com/docs/two-way-sync/manage-sync.md)
- [Supported Markdown and limits](https://falconer.com/docs/two-way-sync/supported-markdown.md)

> **Note:** Two-way sync is different from [keeping docs in sync with PRs](https://falconer.com/docs/update/keep-docs-in-sync-with-prs.md), which proposes doc updates when merged code changes affect your documentation.