Windows Installation: adding Hub html guide to Git help

[tajmone]

I've succesfully installed Hub under Windows 10 x64 (and Win 7, previously), but Windows setup requires a few more tweaks.

In order to access Hub's guide, the file hub.html should be copied inside the docs subfolder of Git's installation folder. Which usually is:

C:\Program Files\Git\mingw64\share\doc\git-doc\

But I also had to rename hub.html to github.html — I guess because of the aliasing of "hub" with "git".

So, now when I type git help github I get to see Hub's documentation (in HTML, via the browser, which is how Git on Windows shows help).

I've tried to preserve the filename hub.html, but then git help hub wouldn't show anything — by which I deduced the aliasing problem, and the renaming to github.html solution.

It would be nice to include this extra info in the Windows binary distribution of Hub. Or the install.bat could handle copying the html file — though, most users would think of git help hub as the correct way to access help, instead of git help github .

[mislav]

Thanks for sharing those steps!

Yes I'm also not really happy that Windows users would have to use git help github instead of git help hub. Do you have any idea about what kind of aliasing problem could be preventing this?

Also, does help for other hub commands work for you, such as hub help fork and hub help hub-clone?

[tajmone]

Yes, hub help fork and hub help hub-clone work. The first one outputs (in the bash):

usage: git fork [--no-remote]

Forks the original project (referenced by "origin" remote) on GitHub and
adds a new remote for it under your username.

Unlike other git help commands, these don't open a (local) web page in the browser, instead they output directly in the bash.

I'm quite positive that the issue git help github has to do with aliasing, because at the beginning of Hub setup (before adding the alias) I used to have its man page as hub.html file. Then I realised that the command didn't output anything so I changed its name to github.html — I tried a few times renaming it back, or having them both, but it no longer seems to work...

Mind you: I've just updated today Hub, before I had an early version of it. Maybe something changed in the meantime.

[tajmone]

I did a few tests and I can confirm that the problem IS the aliasing!

I've uncommented the hub aliasing part in my .bashrc file:

# eval "$(hub alias -s)"

and when I open Git Bash and type git help hub git opens the github.html document in my browser (which is Hub's Manual!).

I get the same help document by typying git help github — both hub and github seem to be considered synonims and point to the same html file (which I have manually renamed and placed in the git docs folder!)

I've also tried to place a copy of hub.html (unrenamed), but the help always points to github.html .

When I remove the comment to hub alias, and hub becomes again an alias of git, the command git help hub no longer produces anything (just a blank line on STDOUT), whilst git help github still works.

Any idea how this could be fixed while retaining the alias, and being able to get help on hub?

Any chance that there is a second aliasing behind the scenes, which makes looking for help on hub point to github html file? I find the whole thing a bit odd.

PS: I think that this is what might be going on behind the scenes — Git on Windows might be handling help requests by taking the git help <command> string, removing the help part, and joining the rest with whitespace stripping.

I've come to this conclusion because in the \Program Files\Git\mingw64\share\doc\git-doc\ folder there are quite a few html help docs like gittutorial.html and githooks.html — with no separting hyphen or space. If this was the case, git help hub would become -> git hub -> github -> github.html

[mislav]

with no separting hyphen or space. If this was the case, git help hub would become -> git hub -> github -> github.html

You're brilliant. That makes complete sense, but I would have never figured that out on my own.

We could definitely copy over our HTML version of the main man page to C:\Program Files\Git\mingw64\share\doc\git-doc\github.html as a part of the installation process. But I would prefer if we didn't write to git's installation directory. Is there a list of directories that git searches for .html files, sort of like MANPATH on Unix?

[tajmone]

I've tried to have a look around my USER folder and under Git setup folder, but to no avail — Git for Windows installs hundreds of little packages to emulate Linux bash and environment,, and its folders structure is a bit of a maze.

I didn't find anything in the basic configuration files either ...

Possibly the best thing would be to ask develepors at:

https://github.com/git-for-windows/git

[mislav]

I've looked into the source code of git-for-windows and found that the path where git searches for .html pages is hardcoded. There is no possibility for a list of paths to be searched.

However, that path can be changed with help.htmlpath config option. So, I propose that we detect when hub help <hub-command> was called, and forward that invocation to git in the format of:

git -c help.htmlpath C:\Path\To\Hub\Documentation help <hub-command>

We should only do this for existing hub commands, though. If we do the same for a native command, such as git help commit, that would break opening the appropriate HTML file.

What do you think?

[tajmone]

Sounds good. This would work both with hub aliased to git and without aliasing.

This would surely be better than touching the Git setup directory — which is in Programs, and would require admin priviledges for all file operations, and would also interfere with uninstallation of Git, for example.

I see that all other hub help commands (eg: git help fork) are showed in the bash STDOUT — contrary to Git, which uses the HMTL docs. I wonder if in Git for Windows future plans the HTML docs will be replaced by a more Linux-like in-shell solution, instead of the HTML docs solution.

But yes, I think your proposal is great, and it will be transparent to the final user.

[tajmone]

PS: Actually, not all git help commands call HTML pages, some output help-text to bash (for example git help help). So it wouldn't be unsual (under Windows) to have some help in HTML and other (usually the shorter ones) in-shell.

[mislav]

How does git on Windows determine which commands to open in html and which to display text info for?

[tajmone]

Without peeking at the source I can only guess that it must have an hard-coded internal list of help topics that are to be outputten to STDOUT, and that anything not in that list is seeked for in the docs folder as an html file with name git + <topic> or git- + <topic> — not sure which criterion it uses to determine if the - should be part of the html file name or not, but some topics use the hyphen (like branch, which calls git-branch.html) while others don't (like attributes, which calls git-gitattributes.html). Invoking git help gitattributes or git help git-branch will also work! But git help -branch will produce an error.

I'll try to peek in Git's repo source and see if I can spot the code that handles that, and then post back here.

[tajmone]

It seems that the hyphen is included in the html file name if the help topic refers to a command which comes as an .exe file in \Git\mingw64\libexec\git-core\ (which in windows all have the name git-<command>.exe — eg: git-branch.exe ), and that it doesn't use the hyphen when the topic is internal to Git's main binary (git-branch.exe).

I'm not 100% sure about this, but peeking at the help command source showed that there is indeed a commands-list handlig, and there are quite a few functions that try to establish if the help topic exists as a binary file in \Git\mingw64\libexec\git-core\ — link to help.c:

[tajmone]

git help looks into aliases!

I think these lines of code might be the culprits for the Hub aliasing issue in git help hub:

static int git_unknown_cmd_config(const char *var, const char *value, void *cb)
{
    const char *p;

    if (!strcmp(var, "help.autocorrect"))
        autocorrect = git_config_int(var,value);
    /* Also use aliases for command lookup */
    if (skip_prefix(var, "alias.", &p))
        add_cmdname(&aliases, p, strlen(p));

    return git_default_config(var, value, cb);
}

git help manages 3 cmds lists

Also, I notice that the help command source seems to refers constantly to three different commands lists:

• &main_cmds
• &other_cmds
• &aliases

But because Hub's binary doesn't reside in Git's binaries folder, it doesn't enter the &main_cmds list. It does though enter as an alias for git in the &aliases list.

Still not sure what the &other_cmds list handles...

Back to Hub's solution...

It seems that your solution for filtering help invocations within Hub's binary is the best solution: it intercepts it before Git, so the aliasing is not a problem.

The problem remains if the user didn't alias hub to git, in this case invoking git help hub would look for github.html — but asking git for help about hub is not a reasonable expectation (unless it's being aliased); after all we can't query git for help on non-git commands. So, the user should be still able to invoke hub help when not using aliasing. The tricky part is that Hub should handle both scenarios: when the user did alias git to hub, and when he didn't.

[mislav]

Thanks for the research! 🏆

The problem remains if the user didn't alias hub to git, in this case invoking git help hub would look for github.html

That's fine. In that case they will have to remember to use hub help hub.