ggt - the Gadget CLI 

Gadget's CLI, named ggt, is the command-line interface for the Gadget platform.

ggt provides additional functionality for working with your Gadget applications using your existing tools on your machine. ggt isn't required for building end-to-end Gadget apps but supports syncing files locally (and more soon) for your preferred coding experience.

Filesync 

Filesync allows you to clone your app's files into a local directory and sync any changes between your local directory and the Gadget editor (in real time!).

With your app's files on your local computer, you can use your favorite code editor, like VSCode or Sublime, to work on your Gadget apps. You can set up your own lint rules, write and run unit tests like you would any other Node project, use your local command line to add npm modules, not to mention push your code to a repo such as GitHub. This allows you to implement version control and enables multiple developers to contribute code to the same Gadget project.

Getting Started 

The quickest way to try out Filesync is to run the following in your terminal:

npx @gadgetinc/[email protected] sync --app example-app ~/gadget/example-app

This will copy example-app's files into your ~/gadget/example-app directory.

Once started, ggt sync will continue to sync files between your app and your local directory. The syncing works in both directions: any file changes in your local directory will be synced back to Gadget, and changes in Gadget will be synced to your local directory.

ggt sync will continue to run in the background until you stop it manually.

Next steps 

Running npx @gadgetinc/[email protected] sync --app example-app ~/gadget/example-app is a great way to get started, but it can be a bit tedious to type over and over again. Thankfully, you can do a few things to make it easier.

Step 1: Install ggt globally

Installing ggt globally is as simple as running the following in your terminal:

yarn global add @gadgetinc/ggt

npm install --global @gadgetinc/ggt

You can verify that ggt was properly installed by running ggt --version. Once you have verified that the install was successful, you can use ggt anywhere in your terminal -- no need for npx!

Step 2: Skip the --app flag

ggt sync remembers which app was used to sync a local directory. Therefore, when you sync to the same directory again, you can skip the --app flag.

# After the first sync, the following are identical
ggt sync ~/gadget/example-app
ggt sync ~/gadget/example-app --app example-app

Step 3: Skip the directory

By default, ggt sync will sync to the directory that you are currently in.

# When you're already inside your local directory, the following are identical
ggt sync
ggt sync .
ggt sync ~/gadget/example-app

There we go! 🎉

We turned npx @gadgetinc/[email protected] sync --app example-app ~/gadget/example-app into a simple ggt sync.

Now, whenever you're ready to start developing your app locally, it's as simple as:

cd ~/gadget/example-app
ggt sync

Resolving conflicts 

If you make changes locally or pull changes down from version control and then start running ggt sync, you might find that you have conflicts. The same file may have been edited locally and in the Gadget app since the last sync was run.

Thankfully, ggt will detect conflicts for you. It will also give you a couple of different options for resolving conflicts:

• Cancel (Ctrl+C): You can choose to cancel the sync operation
• Merge local files with remote ones: Your local changes will overwrite any changes made in Gadget directly
• Reset local files to remote ones: Your local changes will be overwritten by the changes made in Gadget directly.

Note that these options will make changes for all file conflicts! In the example below, selecting either Merge or Reset options will overwrite local or remote changes to both GET.js and POST-order.js files.

Terminal
Shell
$ ggt sync
Local files have changed since the last sync
- routes/GET.js
- routes/POST-order.js

? Remote files have also changed. How would you like to proceed?
> Cancel (Ctrl+C)
  Merge local files with remote ones
  Reset local files to remote ones

If there are changes you want to keep from both local and remote sources, you will need to port all changes to your local or remote instance and then merge those changes with the other instance of your files. For example, I might port my remote changes over to my local instance and then “Merge local files with remote ones” to push all changes to my remote Gadget app.

Ignoring files 

Occasionally, you will want to prevent certain files from being sent to Gadget when you run ggt sync. For instance, you may have files that are only used for local development, such as .eslintrc, or an entire folder like .vscode.

To ignore these files, you can create a .ignore file in the root of your local directory.

.ignore
ignore
Copy
.eslintrc
.vscode

With that in place, ggt sync will no longer send those files up to Gadget when they're changed. The .ignore uses the same semantics as a .gitignore file. Take a look at their docs for more information.