Two documentation enhancements
(1) By Torsten Berg (torstenberg) on 2021-05-06 07:20:46 [source]
I have two suggestions to improve the fossil documentation:
1. fossil remote REF
The documentation for this command says:
Make REF the new default URL. The prior default URL is replaced. REF can be either an explicit URL or a NAME from a prior "add".
From this, I wasn't aware that this command can (should?) be used when you need to supply an explicit username when you local username is different from the remote one. The command fossil user ... was my first suspect for this, but it does not do the same, right?
I had the situation that a user cloned the repository and it was not necessary to provide a username. But afterwards, when commit changes from the clone to the remote repository, a user name must be supplied. As the username in the repository was different from the local one, fossil push failed. Had the documentation said something like this (hoping I now got the correct interpretation!) ...
fossil remote URI
Make URI the new default URL. The URI can be formatted as specified under the 'fossil clone' command.
The prior default URL is replaced. URI can be either an explicit URL or a NAME from a prior "add". This
command is also used to set the username associated with a remote URI if it is different from the local
username. You will be prompted for the corresponding password and fossil can store this password
locally.
... it would have been clear to me that I can do things such as
fossil remote http://username@192.168.xxx.xxx
to make the push/sync work.
2. fossil branch list | ls
The documentation does not make clear that the branch marked with an asterisk is the branch of the current checkout. Suggestion:
fossil branch list|ls ?OPTIONS? ?GLOB?
List all branches. The branch of the current checkout as returned by 'fossil branch current'
is marked with an asterisk. Options:
... and so on ...
Thanks for considering this.
(2) By Warren Young (wyoung) on 2021-05-06 10:29:51 in reply to 1 [link] [source]
I wasn't aware that this command can (should?) be used when you need to supply an explicit username when you local username is different from the remote one.
Above the part of the fossil help remote output you quote is this bit:
See "fossil help clone" for the format of these sync URLs.
...And the output of "fossil help clone" does explain this.
The command fossil user ... was my first suspect for this, but it does not do the same, right?
Correct. The user name given as part of the sync URL is used by the remote server to determine whether clone, sync, push, pull, etc. is allowed according to the given user's capabilities.
The user name set by the fossil user command is used when committing to the local repository prior to the sync.
It is possible to have them be different, causing artifacts to be committed to the local repo under one name but pushed under another. Usually this isn't what you want, though, so you sync them up.
The usual way they become de-synchronized is that the default for the second user name is the local login name, but if you have an account on the remote Fossil instance with a different name, you use the "fossil user" command to fix this up so local commits happen under the proper user name.
The documentation does not make clear that the branch marked with an asterisk is the branch of the current checkout.
(3.1) By Andy Bradford (andybradford) on 2021-05-06 14:20:31 edited from 3.0 in reply to 2 [link] [source]
> It is possible to have them be different, causing artifacts to be > committed to the local repo under one name but pushed under another. > Usually this isn't what you want, though, so you sync them up. In my workflows using SSH, this is almost always what I _do_ want. The account under which the Fossils are hosted with a remote SSH server may or may not reflect the commiter info that I want displayed. I've always regretted this commit: https://www.fossil-scm.org/home/info/64aa75260f48781c Because it makes SSH users have to go through extra hoops if they are using a shared account for Fossil access ala ssh://fossil@remote (similar to GitHub's and Git's ssh://git@remote). This is the one thing that Git does get right over Fossil in my opinion. Over the years, I've contemplated submitting a patch to exclude SSH from this behavior and return to the original behavior of setting the Fossil user from the local information, but didn't think it would be widely accepted. In my mind, when using SSH, there is a clear distinction between the push/pull account information, and the committer information and they need not be the same. Thanks, Andy
(4) By Torsten Berg (torstenberg) on 2021-05-07 21:43:40 in reply to 2 [link] [source]
Thanks for that! It is much clearer to me now how the fossil user and the fossil remote command differ.
While you are certainly right that the URL formats are explained under fossil clone, I still find it difficult to mentally make the connection when I read a sentence such as
Make REF the new default URL
My mind tends to take the term "URL" literally without thinking about the possibility to add a user name to it. But that maybe just me.
(5) By Warren Young (wyoung) on 2021-05-08 00:49:00 in reply to 4 [link] [source]
My mind tends to take the term "URL" literally without thinking about the possibility to add a user name to it.
User names literally are part of a URL; they're just optional, is all. I assume from your reply that you're thinking URLs are only for web sites, and indeed, most web sites have no use for the username@ part, but Fossil isn't unique or nonstandard in making use of the syntax.
User names are commonly added to many other URL schemes.