Standardize the CLI commands of SnowFS

[sebastianrath]

This issue is a proposal for modifications of the CLI API. The focus is a balance between easy-to-use and already established commands in Git.

snow-branch

Create, or delete branches.

Description

Create and delete a branch.

$ snow branch branch-foo
A branch 'branch-foo' got created.

Create an existing branch

$ snow branch branch-foo
fatal: A branch named 'branch-foo' already exists.

Create an existing branch with a commit hash as a starting point

$ snow branch branch-bar 768FF3AA8273DFEB81E7A111572C823EA0850499
A branch 'branch-foo' got created.

Create a branch that already exists

$ snow branch -f branch-foo
A branch named 'branch-foo' got created.

Delete a branch

$ snow branch --delete branch-foo
A branch named 'branch-foo' got deleted.

Delete a non-existing branch.

$ snow branch --delete branch-foo
error: branch 'branch-foo' not found.

For more information see: git-branch

snow-switch

Switch branches. Any modifications in the stage area, or in the worktree are brought over to the switched branch.

Description

Switch to an existing branch.

$ snow switch branch-foo
# Silently switch to branch

Switch to a non-existing branch.

$ snow switch branch-123
fatal: A branch named 'branch-123' does not exist.

Switch incorrectly to a commit. To checkout a commit see snow-checkout.

$ snow switch 6cfb01e83d18fa63761e964c329273d292d23bb4
fatal: a branch is expected, got commit '6cfb01e83d18fa63761e964c329273d292d23bb4'

Create and switch to a branch. Short command for snow-branch and snow-switch

$ snow switch -c branch-bar
A branch 'branch-bar' got created.
# Afterwards silently switch to branch

Create and switch to a branch with a start-point.

$ snow switch -c branch-bas 768FF3AA8273DFEB81E7A111572C823EA0850499
A branch 'branch-bas' got created.

For more information see: git-switch

snow-checkout

Switch to branches, commit or reference. Modifications of any kind of known files to SnowFS will make the command fail.

Description

Checkout an existing branch.

$ snow checkout branch-foo
# Silently switch to branch-foo

Switch to a branch, commit or reference.

$ snow checkout 768FF3AA8273DFEB81E7A111572C823EA0850499
# Silently switch to commit 768FF3AA8273DFEB81E7A111572C823EA0850499

Modify a file and checkout an existing branch

$ echo "Hello" > existing-foo.txt
$ snow checkout branch-foo
fatal: Your local changes to the following files would be overwritten by checkout:
        existing-foo.txt
Please commit your changes before you checking out.
Aborting

For more information see: git-checkout

snow-restore

Restore files or directories. Restoring a file that is unknown to SnowFS will make the command fail. For such case, use snow-clean.

Description

Restore a known file in the worktree (default), aka unstages foo.txt.

$ snow restore foo.txt
# Silently discard changes of foo.txt or restore the file if deleted (in stage)

Restore a known file in the staged area, aka unstages foo.txt. Basically reverts snow add foo.txt

$ snow restore --staged foo.txt
# Silently discard changes of foo.txt or restore the file if deleted (in stage)

Restore a known file in the staged area and the worktree

$ snow restore --staged --worktree foo.txt
# Silently discard changes of foo.txt or restore the file if deleted (stage and worktree)

For more information see: git-restore

snow-clean

Restore files or directories. Restoring a file that is unknown to SnowFS will make the command fail. For such case, use snow-clean.

Description

Remove all untracked files from the working tree in cwd and all subdirectories of it.

$ snow clean .
# Silently delete all untracked files in the current directory

Remove all untracked files from the working tree from the current and all subdirectories.

$ snow clean *
# Silently delete all untracked files in the entire worktree.

Remove a specific untracked file from the working tree.

$ snow clean foo.txt
# Silently delete untracked foo.txt

For more information see: git-clean

[daniellanner]

Typos

Switch incorrectly to a commit. To checkout a commit see snow-checkout.

$ snow switch git 6cfb01e83d18fa63761e964c329273d292d23bb4
fatal: a branch is expected, got commit '6cfb01e83d18fa63761e964c329273d292d23bb4'

• snow switch git

Remove all untracked files from the working tree.

$ snow clean *
# Silently delete all untracked files in the current directory

• current directory and all sub-directories

Needs clarification

# Silently discard changes of foo.txt or restore the file if deleted.

All snow restore variations have the same output. Where is the difference between restoring from the staging area and restoring from the working area.

Missing

snow log commands are currently not present.

[sebastianrath]

Typos fixed. About log vs. branch I would use the log command to report more detailed information about the branches. branch on the other side would simply list all branches

[daniellanner]

Snow Log

I propose to have all information regarding the repository accessible via snow log with context as options.

• snow log --status
• snow log --branches
• snow log --tags
• snow log --history

Further formatting options, such as --output=json and --verbose affect the returned information.

Example

A call to receive the current stage area and the commit history (two steps presumably executed in sequence quite commonly by plugins using SnowFS) can be called as thus snow log --status --history --output=json --verbose returning a single json with the relevant information in subsections.

Verbosity

Furthermore, I propose renaming --verbose to --detail for the above purposes and add --verbose as an option to all commands to output computational steps for debugging purposes. This would replace and expand --debug.

[sebastianrath]

Awesome, I like 👍 Edit: Just had an idea, what about --contains-info=branches,commits,history,files

[daniellanner]

To be honest, it seems a little redundant to me. What are the upsides of --contains-info?

[sebastianrath]

--debug/--verbose is a functionality where--branch/--history somehow is different, but just a detail, we can go with latter

[daniellanner]

I believe that sentiment stems from the fact that these are dedicated commands in git.

If we consider log to be the command to print information and, for the sake of this demonstration only, prefix a 'show' to the options we see that:

snow log --show-history --show-status --show-verbose --show-output=json

The options merely edit the resulting output as any other option.

[sebastianrath]

Makes sense!

[daniellanner]

I do not understand the behavioural differences between snow restore --staged and snow restore --worktree. Could you please demonstrate with an example how the outcome of the two options differ?

[daniellanner]

Personally, I always found the commands git add and git rm to be a little non-descriptive and misleading of the actual behaviour.

I propose to rename these commands snow stage and snow unstage respectively and have a clear distinction between interacting with files and interacting with the state of the repository.

snow stage

This command stages files to the current staging area.

• Add an untracked file snow stage untracked.txt
• Stop tracking a deleted file snow stage deleted_file.txt

snow unstage

This command is the opposite of snow stage. With this you can remove a file from the staging area.

• snow stage untracked.txt and snow unstage untracked.txt will result in the status before any command was entered.

No file editing

The idea is to have a clear distinction between adding/deleting files in the directory and staging/unstaging files. git add and git rm have become a mix of both with options changing the behaviour.

[daniellanner]

Linking issue #144 for detailed snow log file view.

[daniellanner]

We need a command to edit documenting properties after submission.

I propose a command edit which takes in

A) argument what to edit

• --commit <SHA>
• --tag <name or SHA>
• --file <SHA and filepath>
• --branch <name or SHA>

B) argument what information to edit

• --title
• --notes
• --user-data
• --tags (this is actually not very convenient... we should consider renaming the tag list you can set when committing to labels as to not confuse with git tags)

Example

For certain use cases we may want to just append information. We will have to discuss which is the default behaviour. Intuitively I would suggest having --append per default and a --replace being have to set manually.

snow edit --commit hf763b --title --replace "Add my specific new file"

These two commands would be identical:

snow edit --commit hf763b --notes "This version has come color bleeding in the upper left corner" snow edit --commit hf763b --notes --append "This version has come color bleeding in the upper left corner"