Skip to main content

Sync Across Multiple Devices using GitHub

info

This is a manual process and is still in early beta. If you have any issues with the process below, please do not hesitate to contact us.

This guide uses VS Code, since it is free and the steps for configuration are not too advanced. This can be replicated using any version control flow that you use.

This guide can, in theory, also be used on an unlimited number of computers. It is recommended to sync computers for which you are the only user to ensure there are no syncing issues.

Follow this entire guide in order. Going out of order or not completing the entire guide may result in a failure to sync your snippets or other unforeseen consequences.

Prerequisites​

  1. Two (2) computers with Pieces OS and Pieces Desktop App already installed
    • Computer #1: Computer where your saved snippets are currently saved
    • Computer #2: Other computer where you want to sync your snippets
  2. Both computers must have the same version of Pieces OS
    • If you are unsure, please update both computers to the latest version
  3. Version control account (GitHub, GitLab, etc.)

You should start this guide on the computer that has your snippets saved on it.

Setup Steps (15-20 minutes)​

  1. Backup your current Pieces Database (Computer #1)
    • This is very important to ensure you do not lose any snippets or files during the syncing process in case something goes wrong
  2. Quit/Turn off Pieces OS on both computers
    • Ensure it is off until the guide specifically tells you to turn it back on
  3. Ensure that you are on the computer where your snippets are the most up to date (Computer #1)
  4. Open the following folder in your IDE or terminal:
    • macOS: ~/Users/user/Library/com.pieces.os/production/Pieces
    • Windows: C:/Users/user/Documents/com.pieces.os/production/Pieces
    • Linux: ~/Users/user/Documents/com.pieces.os/production/Pieces
  5. In the VS Code terminal, run the following command to initialize a git repository: git init
  6. (Optional) Create a .gitignore file and paste the following into the file to ensure you don’t commit any IDE-specific files: 
    # VS Code
    .vscode

    # JetBrains
    .idea
    .iml

    # If you use another software that adds files to the project root
    # Add them here
  7. Now go to your browser and follow these steps to create a private repository (We used GitHub but is similar on other VCSs):
    1. If you are using VS Code, you can skip to step #7 because it will automatically create a new repository for you
    2. Go to https://github.com
      • If you are not signed in, please sign in to your GitHub account or create a new account if you do not already have one
    3. Click the “Create new…” dropdown button in the top right corner Create New Repo
    4. Click “New repository” from the dropdown
    5. Select the owner to be whoever you want to own this (We recommend your personal account)
    6. Name the repository anything you want (The recommended name is Pieces)
    7. Set the repository visibility to Private
    8. Click "Create repository"
    9. Copy the HTTPS link that should be in the “Quick setup” section of the page
      • This will be used to set your Pieces snippet folder to this GitHub repository
  8. Now we will commit and push your snippets to the remote repository:
    1. Go to your IDE or terminal you have open from step #3
    2. Stage and commit all changes
    3. Create a new repository or connect your previously created repository using the HTTPS link you copied
    4. Push your changes to the connected repository
  9. Switch to your other computer (Computer #2)
  10. Ensure that Pieces OS is turned off on this computer
  11. Open the following folder in your IDE or terminal:
    • macOS: ~/Users/user/Library/com.pieces.os/production
    • Windows: C:/Users/user/Documents/com.pieces.os/production
    • Linux: ~/Users/user/Documents/com.pieces.os/production
  12. Delete the following folder named Pieces:
    • macOS: ~/Users/user/Library/com.pieces.os/production/Pieces
    • Windows: C:/Users/user/Documents/com.pieces.os/production/Pieces
    • Linux: ~/Users/user/Documents/com.pieces.os/production/Pieces
  13. Go to https://github.com
    • If you are not signed in, please sign in to the same GitHub account you’ve been using
  14. Copy the clone URL of your remote repository
  15. If your cloned repository folder is not already named Pieces, you must rename the folder to Pieces

You should be all set up now! Go on to the Testing section to make sure everything is working properly.

Testing (On Computer #2)​

  1. Run Pieces OS
  2. Run Pieces Desktop App
    • You will have to go through the onboarding process

Once you complete onboarding, you should see all your snippets on Computer #2.

Now let’s test that snippets sync between your computers.

  1. Create a new snippet on Computer #2
  2. Turn Pieces OS off
  3. Go to the folder of your repository:
    • macOS: ~/Users/user/Library/com.pieces.os/production/Pieces
    • Windows: C:/Users/user/Documents/com.pieces.os/production/Pieces
    • Linux: ~/Users/user/Documents/com.pieces.os/production/Pieces
  4. Commit and Push all changes to your remote repository
  5. Go to computer #1 (Pieces OS should still be off on this computer)
  6. Go to the folder of your repository:
    • macOS: ~/Users/user/Library/com.pieces.os/production/Pieces
    • Windows: C:/Users/user/Documents/com.pieces.os/production/Pieces
    • Linux: ~/Users/user/Documents/com.pieces.os/production/Pieces
  7. If there are any pending changes for your repository, ensure you discard those changes before continuing the guide.
  8. Pull the latest changes from your remote repository:
    • If there are any merge conflicts, always accept the remote changes
  9. Run Pieces OS
  10. Run Pieces Desktop App
  11. You should see your newly created snippet from Computer #2

Sync Process​

In order to keep your snippets in sync between your computers, follow these steps. These steps are the same no matter which computer you are syncing to.

  • Computer #1: The most up-to-date
  • Computer #2: Out of date computer

On Computer #1:

  1. Turn Pieces OS Off
  2. Commit and push changes to your remote repository

On Computer #2:

  1. Turn Pieces OS Off
  2. Discard any pending changes
    • do not attempt any merges. If computer #2 has any changes at all, you must discard them.
  3. Pull the latest changes from the remote repository

Important Notes​

  • Pieces OS should be completely turned off during the entire syncing process
  • Both Pieces OS instances need to be on the same version for syncing to work properly
  • Local LLM models are not synced between computers, so you will have to install them on your other computer
  • If you are syncing Computer #1 to Computer #2 and there are any uncommitted changes on Computer #2, you must discard those changes.