Detailed command proposal for google/clasp#989

clasp-proposal-remotes-details.md

Main proposal: google/clasp#989

New remote command

add <name> <scriptId>

Adds a remote named <name> pointing to the GAS project at <scriptId>. Analogous to git remote add.

• --project or -g (for "Google Cloud") to set projectId.

• --parent or -p to set parentId.

• --shared or -s to share this remote in .clasp.json.

• --default or -d to set this remote as defaultRemote in .clasprc.json.

• --pull or -f (for "fetch") to immediately pull this remote.

• Error if a remote with name <name> already exists.

• Warn if a remote for <scriptId> already exists, suggest remote update --(un)set-shared.

list

Lists configured remotes. Analogous to git remote with no arguments. I opted for a specific subcommand for consistency with version(s) and deploy(ments).

• --shared or -s to only list shared remotes.
• --private or -p to only list private remotes.

show <name> [...<option>]

Show properties of a specific remote. If no options are specified all will be shown. Analogous to git remote show and git remote get-url..

• --default or -d to show if remote is configured as defaultRemote.
• --shared or -s to show if remote is shared.

rename <old> <new>

Renames remote <old> to <new>. Analogous to git remote rename.

• Error if a remote with name <new> already exists.

update <name> [...<option> <value>]

Updates one or more properties of remote <name>. Analogous to git remote set-head, git remote set-branches and git remote set-url.

• --(un)set-default to configure if the remote is the defaultRemote.

• --(un)set-shared to configure if the remote is shared.

• Warn if --(un)set-default/shared doesn't change anything.

remove [...<name>]

Remove reference to GAS project remote(s) <name>. Analogous to git remote remove.

• --delete to also delete GAS project itself.

• Warn if there is no remote for <name>.

Adjustments to other commands

push and pull

• Add --set-default (-d) flag to configure the specified remote as defaultRemote, analogous to git's --set-upstream.

pull and open

• An ad-hoc specified scriptId should be treated as a value for [remote].
• If a specified [remote] is not configured as a remote it should be treated as an ad-hoc scriptId.

undeploy

• Add --all-remotes flag for undeploying all versions across all remotes. The existing --all should undeploy all versions for a specific remote.

create and clone

• Add --shared (-s) flag to share the created/cloned remote. Private by default.
• Add --remote-name (-n) to specify the name of the created/cloned remote. Defaults to defaultRemoteName. Analogous to git clone's --origin.
• Add --remote-default (-d) flag to immediately set the created/cloned remote as the defaultRemote.

setting

• Add ability to set the new defaultRemote and defaultRemoteName options in .clasprc.json.
• Add --global flag to set .clasprc.json settings in the "global" file in the user's home directory, analogous to git config's --global.
• Deprecate setting the 'root keys' remote pointer options, suggest remote add/update.