They don't have --json, which would be a necessary first step.
This was considered in
this_todo
when adding --json to many commands, and the thinking for not adding it
was:
git-annex-sync (while it would be pretty easy to support, it outputs
different types of messages depending on what remotes it syncs with and
what needs to be done. Eg, copy to remote, or export to remote, or import
from remote. Each would be a different format of json message, which
violates the principle that all git-annex json output should be
discoverable by simply running the command. And of course, everything it
does can be done by other commands, which can support json without having
that problem.)
sync had not been split into pull and push at that point. Being split does
reduce the space of different things, but it's still multiple things, so
still a problem for json output discoverability.
(Also push and pull can drop from a remote or locally, and of course there are
the git operations they do, which would probably have to become silent in
json mode.)
To me, the purpose of any progress message is twofold: 1) let the user know the program is not stuck and 2) provide information about what was happening if it does get stuck. Push and pull do this now without JSON.
I agree the same JSON progress object format should be used for all commands. Currently the action progress information includes: command, file, input, byte-progress, total-size, and percent-progress.
The calling application is able to "know" which command it issued to cause the progress reports.
A separate, optional field could be added for the particular remote involved. For example, messages like "Copy file A to remote-one X% complete" and "Export file B to remote-two X% complete" should be possible.
I'm in favor of documenting data structures. Forcing developers to reverse-engineer the structure is inefficient at best. While the principle that all git-annex json output should be discoverable by simply running the command sounds good, I find it leaves much to be desired. Just to find out what's available, someone must setup and run the command. I suggest updating the requirement to "All git-annex JSON output objects are documented."
Users will get impatient and grow frustrated without some type of indication work is in progress.
I'm OK with leaving Git operations silent for now.
Please improve the end-user experience by devising a way to inform the user git-annex is making progress with JSON.
1) JSON allows optional fields. That is, fields which are only present when needed. I am specifically saying not to include all fields every time with null values as needed.
2) Occasionally tacking the remote name onto the end of a string named command is not discoverable. The command key would have to be renamed to something like commandAndSometimesRemote to be discoverable. jstritch's naming rule #5: If a name needs a conjunction to accurately describe it, the design can be improved.
3) The optional field name is more easily observed than the optional string content.
4) Consider the application code consuming the JSON. A test for the presence of the remote name is required either way. Do you want those applications writing the test "if the command value contains one space" or "if the remote key is present"? Code is written once and read hundreds of times. The second test conveys the intent, reducing maintenance cost.
5) The application code to deal with splitting the string and handling each part becomes unnecessary with the optional field.
6) The documentation of the JSON could include a matrix showing the key name and its data type versus the commands, similar to a feature comparison table.
7) Documenting the JSON does not make it less discoverable.
I hope you find this information helpful to improve the end-user experience. Let me know if you have any questions.
Rather than using git-annex push/pull/sync with a complex json format,
complications of knowing what remote it's acting on, etc, a program can
simply use git-annex get/copy/drop/import/export to do the same operations,
all of which already support json.
I'm OK with leaving Git operations silent for now.
In the case where the git operation needs to prompt for a password, this
would leave the user with a password prompt with no prior indication of what is
being done. I don't think that's acceptable.
Please improve the end-user experience by devising a way to inform the
user git-annex is making progress with JSON.
I hope you find this information helpful to improve the end-user experience.
Let me know if you have any questions.
They don't have --json, which would be a necessary first step.
This was considered in this_todo when adding --json to many commands, and the thinking for not adding it was:
sync had not been split into pull and push at that point. Being split does reduce the space of different things, but it's still multiple things, so still a problem for json output discoverability.
(Also push and pull can drop from a remote or locally, and of course there are the git operations they do, which would probably have to become silent in json mode.)
To me, the purpose of any progress message is twofold: 1) let the user know the program is not stuck and 2) provide information about what was happening if it does get stuck. Push and pull do this now without JSON.
I agree the same JSON progress object format should be used for all commands. Currently the action progress information includes: command, file, input, byte-progress, total-size, and percent-progress.
The calling application is able to "know" which command it issued to cause the progress reports.
A separate, optional field could be added for the particular remote involved. For example, messages like "Copy file A to remote-one X% complete" and "Export file B to remote-two X% complete" should be possible.
I'm in favor of documenting data structures. Forcing developers to reverse-engineer the structure is inefficient at best. While the principle that all git-annex json output should be discoverable by simply running the command sounds good, I find it leaves much to be desired. Just to find out what's available, someone must setup and run the command. I suggest updating the requirement to "All git-annex JSON output objects are documented."
Users will get impatient and grow frustrated without some type of indication work is in progress.
I'm OK with leaving Git operations silent for now.
Please improve the end-user experience by devising a way to inform the user git-annex is making progress with JSON.
Additional clarification of my posts above:
1) JSON allows optional fields. That is, fields which are only present when needed. I am specifically saying not to include all fields every time with
nullvalues as needed.2) Occasionally tacking the remote name onto the end of a string named
commandis not discoverable. Thecommandkey would have to be renamed to something likecommandAndSometimesRemoteto be discoverable. jstritch's naming rule #5: If a name needs a conjunction to accurately describe it, the design can be improved.3) The optional field name is more easily observed than the optional string content.
4) Consider the application code consuming the JSON. A test for the presence of the remote name is required either way. Do you want those applications writing the test "if the command value contains one space" or "if the remote key is present"? Code is written once and read hundreds of times. The second test conveys the intent, reducing maintenance cost.
5) The application code to deal with splitting the string and handling each part becomes unnecessary with the optional field.
6) The documentation of the JSON could include a matrix showing the key name and its data type versus the commands, similar to a feature comparison table.
7) Documenting the JSON does not make it less discoverable.
I hope you find this information helpful to improve the end-user experience. Let me know if you have any questions.
Rather than using git-annex push/pull/sync with a complex json format, complications of knowing what remote it's acting on, etc, a program can simply use git-annex get/copy/drop/import/export to do the same operations, all of which already support json.
In the case where the git operation needs to prompt for a password, this would leave the user with a password prompt with no prior indication of what is being done. I don't think that's acceptable.
Yikes, that almost triggered my ChatGPT detector.