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 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.
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:
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
!
You can use yarn or npm to download ggt. But yarn is required to add additional packages to a Gadget project.
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 identicalggt sync ~/gadget/example-appggt 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 identicalggt syncggt 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-appggt 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.
TerminalShell$ ggt syncLocal 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 onesReset 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.
.ignoreignore.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