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.

For in-depth documentation about ggt and its commands, visit the GitHub repository.

Filesync

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

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, allowing you to implement version control, and enabling multiple developers to contribute code to the same Gadget project.

Filesync syncs files to and from your local environment, but your Gadget app still runs in the cloud. Changes made locally are immediately reflected remotely, so you can build and test your app using the rest of Gadget's tools as you would normally. The Editor, API Playground, and your application's API will all live-update to reflect your changes and are suitable for testing your Filesynced files.

Getting Started

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

Terminal
Shell
npx @gadgetinc/ggt 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/ggt sync --app example-app ~/gadget/example-app is a great way to get started, but can be a bit tedious to type over and over again. Thankfully, theres a few things you can do to make it easier.

Step 1: Install ggt globally

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

Shell
// in Terminal
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.

Terminal
Shell
# 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.

Terminal
Shell
# 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/ggt 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:

Terminal
Shell
cd ~/gadget/example-app
ggt sync

Resolving Conflicts

If you make changes locally, or pull changes down from version control and then start run 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.

Shell
// in Terminal
$ 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

In the case 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
// in .ignore
.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.

The following files are always ignored whether or not you have an .ignore file

  • node_modules
  • .gadget
  • .git