Fossil Forum

"login-group join" documentation improvement
Login

"login-group join" documentation improvement

"login-group join" documentation improvement

(1) By Alex Canales (nales0) on 2022-09-15 07:14:26 [source]

I was toying recently for the first time with the login-group join command, and I was confused by the documentation. Here are some thoughts for improving the documentation and avoiding the same confusion for other users.

The current documentation is the following:

Usage: fossil login-group ?SUBCOMMAND? ?OPTIONS?

Run various subcommands to manage login-group related settings of the open
repository or of the repository identified by the -R or --repository option.

...

fossil login-group join ?--name NAME?

 Add this repository to login group to which REPO belongs, or creates a
 new login group between itself and REPO if REPO does not already belong
 to a login-group.  When creating a new login-group, the name of the new
 group is determined by the "--name" option.

...

Options valid for all subcommands:

    -R|--repository REPO       Run commands on repository REPO

The command

The real command is

fossil login-goup join ?-R REPO? ?--name NAME? REPO-TO-JOIN

An argument containing the path to REPO-TO-JOIN is mandatory, this is not indicated by the documentation.I thought that if I were in an open repository I could join REPO-TO-JOIN using this command:

fossil login-goup join -R PATH-TO-REPO-TO-JOIN

The REPO-TO-JOIN argument should be added into the documentation.

The group name

In the documentation, the group name is optional. This is incorrect when the two repositories are not part of any login-group. This fails:

$ fossil login-group join -R REPO REPO-TO-JOIN
Not currently a part of any login-group

This works:

$ fossil login-group join --name G -R REPO REPO-TO-JOIN
Now part of login-group "G" with:

I thought that a default login-group name would have been used because it is an optional argument. The last sentence explains that the created group name is determined by the --name option, but it should be more explicit that this option is mandatory in this case.

(2) By Stephan Beal (stephan) on 2022-09-15 07:36:03 in reply to 1 [link] [source]

In the documentation, the group name is optional. This is incorrect when the two repositories are not part of any login-group. This fails:

We have no help text syntax for "optional unless..." conditions. The documentation for that command clarifies that --name is needed when creating a new group.

An argument containing the path to REPO-TO-JOIN is mandatory, this is not indicated by the documentation.

i think that one was addressed by afe25dae91d7b335.

We have a couple of closely-related pending topics to resolve regarding login groups via threads 240b6d856a3dd4b5 and 83619633d1d64504. They are marked as "to investigate" in my inbox but current priorities and a pending move will likely keep me from getting to them until early next year.

If someone else would like to pick this/these up, it would be much appreciated :).

(3) By Alex Canales (nales0) on 2022-09-15 08:29:30 in reply to 2 [link] [source]

We have no help text syntax for "optional unless..." conditions. The documentation for that command clarifies that --name is needed when creating a new group.

I understand your point about the syntax. What I meant was that instead of the current sentence:

When creating a new login-group, the name of the new group is determined by the "--name" option.

Using a more explicit sentence:

When creating a new login-group, the "--name" option is mandatory and determines the name of the new group.

Often when a parameter is optional, there is a default value used when it is not given. I thought that was the case here and that the name would be some "random string".

But maybe for an native English speaker the sentence currently in the documentation is obvious, and the misunderstanding was completely my fault. Va savoir!