joyously
commented
6 months ago Is this like #3130?
Open khionu opened 6 months ago
joyously
commented
6 months ago Is this like #3130?
khionu
commented
6 months ago Hrmm... maybe similar enough to where it could be implemented the same way? Maybe similar enough to be redundant? Though there is a distinction between docs and explanations.
Explanations would be more for providing nuance for specific contexts. An error might return a message long enough for a more experienced user, and say "run jj explain E1234 for more details" to help those that haven't run into the error before.
mhammond
commented
6 months ago Is this like https://github.com/martinvonz/jj/pull/3130?
I think it's complimentary - the <ident> here is interesting. I just noticed in the cli:
If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
I can imagine, eg,
You might be asked for a description - see 'jj docs edits-descriptions'
The usual working-copy semantics apply - see 'jj docs edits-and-working-copy'
Something like this would make "help" be both more concise and informative.
joyously
commented
6 months ago I don't see why we need more commands (docs or explain). Both Git and Breezy use help for commands and other topics which have pages of text (Git's are longer).
khionu
commented
6 months ago There is prior art for this, namely rustc.
I'm not familiar with Breezy, but Git is definitely a tool I think that could benefit from an explain command as well. Docs (including commands that take the place of) have different forms, and different times where one form is more optimal than another. Separating them makes it easier to organize without overwhelming readers. There would be overlap, but that's ok, docs shouldn't try to follow DRY.
As an example, I might break up help commands into:
docs, for explaining concepts and guides to do specific thingsexplain, for more contextual things users will run intohelp, as a reference for the surface-level of using the CLI
And I might add more depending on the tool itself. On the Discord, @thoughtpolice had the idea of making a tutor command, like Vim, and I could see that being excellent.In short, the more ways we present the knowledge around and of the tools we make, the more accessible we make them, and the more we enable our users to make the most of them.
joyously
commented
6 months ago For reference:
$ brz help
Breezy 3.2.1 -- a free distributed version-control tool
https://www.breezy-vcs.org/
Basic commands:
brz init makes this directory a versioned branch
brz branch make a copy of another branch
brz add make files or directories versioned
brz ignore ignore a file or pattern
brz mv move or rename a versioned file
brz status summarize changes in working copy
brz diff show detailed diffs
brz merge pull in changes from another branch
brz commit save some or all changes
brz send send changes via email
brz log show history of changes
brz check validate storage
brz help init more help on e.g. init command
brz help commands list all commands
brz help topics list all help topics
$ brz help topics
authentication Information on configuring authentication
basic Basic commands
branches Information on what a branch is
bugs Bug tracker settings
checkouts Information on what a checkout is
commands Basic help for all commands
configuration Details on the configuration settings available
conflict-types Types of conflicts and what to do about them
content-filters Conversion of content into/from working trees
criss-cross Information on criss-cross merging
current-formats Current storage formats
debug-flags Options to show or record debug information
diverged-branches How to fix diverged branches
env-variables Environment variable names and values
eol Information on end-of-line handling
files Information on configuration and log files
formats Information on choosing a storage format
git Using Bazaar with Git
global-options Options that control how Breezy runs
glossary Glossary
hidden-commands All hidden commands
hooks Points at which custom processing can be added
launchpad Using Bazaar with Launchpad.net
location-alias Aliases for remembered locations
log-formats Details on the logging formats available
missing-extensions What to do when compiled extensions are missing
other-formats Experimental and deprecated storage formats
patterns Information on the pattern syntax
repositories Basic information on shared repositories.
revisionspec Explain how to use --revision
rules Information on defining rule-based preferences
standalone-trees Information on what a standalone tree is
standard-options Options that can be used with any command
status-flags Help on status flags
sync-for-reconfigure Steps to resolve "out-of-sync" when reconfiguring
topics Topics list
url-special-chars Special character handling in URLs
urlspec Supported transport protocols
working-trees Information on working trees$ git help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
[--super-prefix=<path>] [--config-env=<name>=<envvar>]
<command> [<args>]
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
work on the current change (see also: git help everyday)
add Add file contents to the index
mv Move or rename a file, a directory, or a symlink
restore Restore working tree files
rm Remove files from the working tree and from the index
examine the history and state (see also: git help revisions)
bisect Use binary search to find the commit that introduced a bug
diff Show changes between commits, commit and working tree, etc
grep Print lines matching a pattern
log Show commit logs
show Show various types of objects
status Show the working tree status
grow, mark and tweak your common history
branch List, create, or delete branches
commit Record changes to the repository
merge Join two or more development histories together
rebase Reapply commits on top of another base tip
reset Reset current HEAD to the specified state
switch Switch branches
tag Create, list, delete or verify a tag object signed with GPG
collaborate (see also: git help workflows)
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.
$ git help -g
The Git concept guides are:
attributes Defining attributes per path
cli Git command-line interface and conventions
core-tutorial A Git core tutorial for developers
credentials Providing usernames and passwords to Git
cvs-migration Git for CVS users
diffcore Tweaking diff output
everyday A useful minimum set of commands for Everyday Git
faq Frequently asked questions about using Git
glossary A Git Glossary
hooks Hooks used by Git
ignore Specifies intentionally untracked files to ignore
mailmap Map author/committer names and/or E-Mail addresses
modules Defining submodule properties
namespaces Git namespaces
remote-helpers Helper programs to interact with remote repositories
repository-layout Git Repository Layout
revisions Specifying revisions and ranges for Git
submodules Mounting one repository inside another
tutorial A tutorial introduction to Git
tutorial-2 A tutorial introduction to Git: part two
workflows An overview of recommended workflows with Git
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.I paged through a few of the guides to see how much text there is.
git help tutorial has 9 screens.
git help revisions has 6 screens.
git help everyday has 7 screens.
5 screens of text for git help workflows.
23 screens of text for git help git.
$ darcs help
Usage: darcs COMMAND ...
Commands:
help Display help about darcs and darcs commands.
Most used/starting out:
initialize Create an empty repository.
add Add new files to version control.
whatsnew List unrecorded changes in the working tree.
record Create a patch from unrecorded changes.
clone Make a copy of an existing repository.
pull Copy and apply patches from another repository to this one.
push Copy and apply patches from this repository to another one.
Preparing patches before recording:
move Move or rename files.
remove Remove files from version control.
replace Substitute one word for another.
Querying the repository:
log List patches in the repository.
annotate Annotate lines of a file with the last patch that modified it.
diff Create a diff between two versions of the repository.
show Show information about the given repository.
test Run tests and search for the patch that introduced a bug.
Undoing and correcting:
revert Discard unrecorded changes.
unrevert Undo the last revert.
amend Improve a patch before it leaves your repository.
rebase Edit several patches at once.
rollback Apply the inverse of recorded changes to the working tree.
unrecord Remove recorded patches without changing the working tree.
obliterate Delete selected patches from the repository.
Direct modification of the repository:
tag Name the current repository state for future reference.
setpref Set a preference (test, predist, boringfile, or binariesfile).
Exchanging patches by e-mail:
send Prepare a bundle of patches to be applied to some target repository.
apply Apply a patch bundle created by `darcs send'.
Other commands:
optimize Optimize the repository.
dist Create a distribution archive.
mark-conflicts Mark unresolved conflicts in working tree, for manual resolution.
repair Repair a corrupted repository.
convert Convert repositories between various formats.
fetch Fetch patches from another repository, but don't apply them.
Use 'darcs COMMAND --help' for help on a single command.
Use 'darcs --version' to see the darcs version number.
Use 'darcs --exact-version' to see a detailed darcs version.
Use 'darcs help patterns' for help on patch matching.
Use 'darcs help environment' for help on environment variables.
Use 'darcs help manpage' to display help in the manpage format.
Use 'darcs help markdown' to display help in the markdown format.
Check bug reports at http://bugs.darcs.net/Oh, I didn't know about those git commands. Having checked them out, the git help subcommands demonstrate what I'm talking about wrt different forms, even though they use the same output format. git help revisions is a indepth explanation of references and how you can specify them. git help everyday is prescriptive of what people can expect their workflows to be like.
poliorcetics
commented
6 months ago the issue with jj help <topic> is that help is a subcommand generated by clap, we can't control its output that much.
Having one subcommand for exploring other subcommands (jj help) and one for more in-depth documentation (jj docs/explain) seems fine to me, it allows the first to stay concise (and auto generated) and the second to have the exact output we want. It would also make it possible to have both jj help rebase and jj docs rebase, with very different content, which I think is neat, but I have no strong opinion either way.
khionu
commented
6 months ago I could see strong value in having one of these commands mirror jj help, but at the same time, I can see wanting to bundle more than just doc-command pairings.
I think of explain commands as something like an FAQ, but not bounded by the "Frequently" of FAQs.
arxanas
commented
5 months ago One related feature is hg githelp <git-command>, which processes a Git command and prints the semantic Mercurial equivalent.
khionu
commented
5 months ago That is really nifty, and I'd love to work on that kind of thing.
Is your feature request related to a problem? Please describe. As jj promotes a different mindset than will be familiar to most people who try it, it might be useful to have a
jj explain <ident>command. Explanations would be a catch-all place to add in-depth documentation to help people understand various concepts and issues. This would be a place that deprecation reasonings could be outlined.Describe the solution you'd like
E000_short_description.txt--rev-a XX --rev-b YYcould allow examples to be filled in with commands that are ready for direct usage.Describe alternatives you've considered The most minimal implementation of this would infer the ID and short description from the file name, then use nothing but plain text, without annotations, for the body.