search

git-for-windows / git

A fork of Git containing Windows-specific patches.
http://gitforwindows.org/
Other
8.25k stars 2.5k forks source link

Could you include manpages for the included programs? #696

Closed gonsolo closed 8 years ago

gonsolo commented 8 years ago

I am tired of switching between cygwin and git bash or looking up manpages on the internet. Can you add manpages for the provided programs like git, egrep and so on?

Setup

2.7.1 windows

64 bit.

Defaults.

No.

Details

Bash.

man egrep

A manpage listed.

Nothing. There is no man program in the git for Windows distribution.

No specific repository. Just downloaded git for Windows as is.

dscho commented 8 years ago

Man pages are something for developers who seek a software distribution that is based on a package management software. Git for Windows is not such a software distribution. You are looking for MSYS2.

gonsolo commented 8 years ago

I see.

But: :)

  1. It's not only for developers, also users. You include programs like vim, grep, tail, tar etc. Why not provide manpages as well, to be able to look up options? Developers and Users do this all the time.
  2. What does package management have to do with this?

But thanks for the answer. g

dscho commented 8 years ago

It's not only for developers, also users.

Git for Windows is for users.

You include programs like vim, grep, tail, tar

Only insofar required as per Git. tar is included only for historical reasons.

What does package management have to do with this?

Everything.

Do you know how much larger the installer would be, were we to include the man pages? A hint is given by the size of the mingw-w64-x86_64-git-doc-man package: 787 kB. That does not sound a lot to you? How about granting everybody's wish (which would only be fair if I were to include the man pages that next to no typical Windows user will ever even know how to read), in which case we can easily end up with a 100+MB installer.

So: no, just because a few Linux users want to have their man pages on Windows does not mean that everybody has to download them.

Instead, you need to look at the link I gave you. You will see that there is a package management tool, pacman, with which you (and every other power user) can install exactly the package you want. And nobody else needs to download a larger installer just to satisfy your pleasure.

gonsolo commented 8 years ago

Ok. Thanks anyway. :)

dscho commented 8 years ago

Why "anyway"? In what way was my answer not helpful?

gonsolo commented 8 years ago

Yes it was helpful. Sorry to be ambiguous. "Anyway" because I don't get to have my manpages. (It's hard to be one of those last remaining Windows command line users.) :)

Regards, g

dscho commented 8 years ago

I don't get to have my manpages

Why? Why don't you install the Git for Windows SDK (which is essentially an MSYS2 environment with preinstalled packages to compile Git for Windows)? I really don't get it.

nancym commented 8 years ago

I also would like manpages and currently I ssh to a nix server to read them, but it would be great to have them locally. I've use Cygwin in the past, but don't want to install it on my new computer. I'll install the SDK if that's my best option, but before I do, I have a few thoughts:

Thanks! א

dscho commented 8 years ago

Is installing the "Git for Windows SDK" the best way to get the man pages locally for a regular user (not a developer)?

Right now, yes. In the future, installing MSYS2 and then installing the package that contains the man page will be the best course of action.

It would be great if you could add info about man pages to the docs.

It would be even greater if you could help me with that. Please ask me anything that is unclear.

nancym commented 8 years ago

Thank you. Any idea how far in the future? If it's not too long, I'll wait. I'd be happy to contribute to your docs and will (I hope) do that once I figure out how I'm going to get the man pages on my Windows system. Here's another question: I have some vague memory from years ago that there's a nix command-line tool called something like "rman" or "remote-man" that one can type and get a remote man page to display in a local terminal window. I know I could use a web browser, but usually I don't want to mess with that and just want a quick reminder of the command-line arguments for a nix tool. I also know about --help but often I'm looking for more info and examples.

dscho commented 8 years ago

Any idea how far in the future?

No, unfortunately not.

I'd be happy to contribute to your docs and will (I hope) do that once I figure out how I'm going to get the man pages on my Windows system.

Use Pacman: pacman -Sy man mingw-w64-x86_64-git-doc-man (you obviously need to use i686 in 32-bit installations instead).

ElTopo commented 8 years ago

I also prefer manpage to HTML pages. I would have said "OK, thanks anyway" too, and that means "no contest, but you are not necessarily right".

dscho commented 8 years ago

So what is exactly the point of keeping this conversation going? Is anybody going to do anything, or is there only talk to be had?

Zitrax commented 8 years ago

The discussion seem to be focused on the man part of this. Personally I was simply interested in getting more help in the console. A user must not know about man pages or Linux to type "git help command" in the console.

I have no idea how tightly the internals of this is connected to man though, so I understand that it could be an issue.

kostix commented 8 years ago

@Zitrax, you have to draw a line somewhere.

I'm pretty sure any decent book aimed at teaching Git to complete novices mentions how to call git help <command> somewhere on its first few pages. And calling such command just works in GfW in the most natural way possible (for a Windows user).

Now let's suppose this is not enough. So what would be a sure way to improve discoverability of the help system? Since GfW is a Windows-native program, supposedly placing an entry in the Git's start menu menu pointing to the root documentation page would be a good addition. May be an entry pointing at http://git-scm.com/documentation would be a good addition, too.

I, personally, can't think of anything other in this venue which would also not get in the way of experienced users.

And by the way:

~% git foo
git: 'foo' is not a git command. See 'git --help'.

Did you mean this?
        log

And running git --help actually works. Also please try just running git, unadorned, and see what it outputs. So is there anything more to it?

Zitrax commented 8 years ago

Yes I understand that it works fine for for most, it would just be convenient to have for some of us.

But putting that aside I can mention the reason why I was extra annoyed and started to look into this, I am running this on an offline machine with no internet access. And in that case each opening of a HTML help page takes over 11 seconds which is super slow when you are used to instantly displaying man pages. The reason seem to be that the html pages are trying to load an external font file using:

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">

this seem to delay even the display of the page to after the network timeout at ~= 10 seconds. So fixing that problem would of course remove quite a bit of the annoyance in my case too.

dscho commented 8 years ago

@Zitrax I invite you to give it a try to solve this problem and to contribute back a fix.

In your case, it might simply be a network misconfiguration: when you are offline, your webbrowser should get a negative answer very quickly, and then ignore the missing stylesheet.

(And please note that this is a very different problem from the one described in this here ticket, so it would be much better to discuss it in a new ticket.)

In any case, we have worked very hard to make this Open Source software so accessible that you are empowered to do something about any problem you encounter. This comes, of course, with the responsibility to use that empowerment.

In this case, I could imagine that the use of the Google Font APIs is overzealous: we should be able to cope with the built-in "Sans" font just as well. What you could do to see this issue addressed is to install the Git for Windows SDK, build the documentation and figure out where it embeds that stylesheet declaration (it is not part of Git's source code), and then figure out a way how to turn it off.

bambams commented 4 years ago

The command prompt is a foreign concept to Windows users. Most Windows users are using a GUI to interact (minimally) with Git. Most don't even install Git for Windows. Those that are interacting with the Git CLI probably expect a similar experience to other platforms. Launching a Web browser to view manpages (which even the HTML pages are modeled after) is kind of a ridiculous workaround from YEARS ago when getting man support on Windows was difficult.

Now that MSYS2 has a package it should be feasible to REMOVE the HTML documentation and instead ship manpages. Any Windows users that wishes to view the manual in their Web browser can look up the documentation on the Web site. IMO, making git help work exclusively from the console makes the most sense, and is the most efficient use of resources. It should not impact any users to make this change.

Every time it launches a Web browser I curse the developers that thought that was an acceptable solution. I'd rather you piped a plaintext version of the manpage through the built-in more command than launch a damn Web page in a browser.

dscho commented 4 years ago

Every time it launches a Web browser I curse the developers that thought that was an acceptable solution. I'd rather you piped a plaintext version of the manpage through the built-in more command than launch a damn Web page in a browser.

Rather than wasting your good karma by talking ill about developers from whose work you benefit handsomely every day, you might want to simply execute these commands once, and have your wish fulfilled:


printf '#!/bin/sh\n\nexec more "${1%%.html}.txt"\n' >~/bin/git-doc-viewer
git config --global web.browser=more
git config --global browser.more.cmd="$HOME/bin/git-doc-viewer"
bambams commented 4 years ago

That is actually a clever workaround, but it requires some additional steps because at least my distribution of GFW did not include text versions of the manual pages. I don't see an html2text available in the MSYS2 repos either, but there is an elinks-git package which can be used to do the conversion. elinks doesn't seem to care for the path being passed to it by Git so instead from an MSYS shell I executed this to get acceptable text manuals:

cd /c/Program Files/Git/mingw64/share/doc/git-doc
for f in *.html; do
    elinks -dump "$f" >"${f%%.html}.txt";
done

(You require appropriate ACLs to create those text files so edit the folder permissions as necessary first)

And since we have less already shipped with Git use that instead of more.

While this works adequately, it requires some flaky preparation first that inexperienced developers would likely struggle with, and even experienced developers would likely fumble with in 6 months when this conversation isn't fresh in their mind, and it is still a hack of a workaround in place of a proper solution.

Shipping the manpages along with man(1) is still the right thing to do.

dscho commented 4 years ago

Shipping the manpages along with man(1) is still the right thing to do.

From my perspective, this sounds more like a wish of very few users who would be better served using Cygwin or MSYS2 because you are clearly not only interested in Git but also in man.

Git for Windows is not intended as a replacement for MSYS2.

The price of increasing the size of Git for Windows' installer would just be too high, and the majority of the users that are totally uninterested in man pages would have to pay that price.

PhilipOakley commented 4 years ago

As a 'Windows' user, I like the use of the web interface with its hyperlinks between pages. Any time I've used WSL I've been annoyed by the man interface because of that lack.

I'm generally with @dscho on this, at least the default linkages. If there was a well argued PR for inclusion of man (i.e. great justification and low size overhead) than I'm sure dscho would consider it carefully, but as he says...

The price of increasing the size of Git for Windows' installer would just be too high, and the majority of the users that are totally uninterested in man pages would have to pay that price.

dscho commented 4 years ago

BTW here is something interested people can do easily: unpack a recent Portable Git, pack it with 7-Zip, then add the relevant files from [https://gitforwindows.org/#download-sdk](the Git for Windows SDK) (most definitely /usr/bin/man.exe, the */git-*.1 files, possibly more), then pack that with 7-Zip, and report back the size difference of the packs.

sp-white commented 3 years ago

Just adding a thought to the conversation. If one of the main reasons for not including the plain-text man files in the Git for Windows installation is because it would make the installation too large, I wonder if Microsoft might have an appropriate solution...

The PowerShell team realises that not everyone wants or needs help files, and so they don't include any in the main installation (aside from bare-bones requirements). If a user does want the help files, they can run the Update-Help cmdlet, and all the latest help files get downloaded. Once downloaded, users can view the help files directly within the shell, or they can add an -Online flag if they want to see a help file displayed on its dedicated web page.

I've no idea about the practicalities of implementing such an approach in Git for Windows, but it seems like a win-win: the download size is minimised and the help files are still available to those that want them.

PhilipOakley commented 3 years ago

plain-text man files in the Git for Windows installation

I don't believe that the man pages (as delivered by the man() program) are actually text. I had the feeling that the man pages were essentially 'compiled' to a stylistic format that allows them to be delivered by the man() programme. [I could be wrong]

The Git for Windows install already does deliver the pdf versions of the Git manual pages, but none for any of the Msys/bash/ support layer. I believe it's the latter area that folks are wanting the man pages for as they are looking for a full up Msys experience I.e. https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper , which isn't what Git-for-Windows is about.

The idea of having a suitable small extra 'installer' for extras would be a possibility, it just needs something to deliver, and a separation of data packs, etc. But it needs to be driven by active contributors, as it's not something to load onto the volunteer maintainer.