git-bash: document the Windows initiator program #2357

PhilipOakley · 2019-10-16T14:10:13Z

Git-for-Windows provides analmost fully fledged Git operating on the
Windows OS despite some differences in OS operating philosophies.

The git-bash.exe programme provides a set of initiator options and
estabilished a terminal window into which to enter git and bash commands.

Tell the Windows user how it all works.

Signed-off-by: Philip Oakley philipoakley@iee.email

This starts the ball rolling for #1674

Reviewers - just write the text contribution into the code review comments on the something like this: It is located in repo .. style.

Git-for-Windows provides analmost fully fledged Git operating on the Windows OS despite some differences in OS operating philosophies. The git-bash.exe programme provides a set of initiator options and estabilished a terminal window into which to enter git and bash commands. Tell the Windows user how it all works. Signed-off-by: Philip Oakley <philipoakley@iee.email>

dscho

I would also strongly recommend to move this into MINGW-packages instead. It does not make sense in the git repository, as the source code for git-bash..exe does not live here.

dscho · 2019-10-17T22:12:56Z

Documentation/git-bash.txt

+
+NAME
+----
+git-bash - A Windows initialiser for the bash window on that OS


I am not sure that "initialiser" is a good term. Maybe git-bash - Starts an interactive Bash in a new terminal window instead?

I am not sure that "initialiser" is a good term.

The whole document was very much an initial (near empty) draft with content stolen from another page for simplicity, hence the remnants.

It's there to catch suggestions, rather than be even a good draft - there are still lots of bits that are behind that green curtain of ignorance..

Thanks for the comments and feedback.

dscho · 2019-10-17T22:13:22Z

Documentation/git-bash.txt

+SYNOPSIS
+--------
+
+git-bash [--cd-to-home] [--xx] []


I am fairly sure that --xx is not a valid option.

I wasn't sure what the valid options are...

dscho · 2019-10-17T22:13:35Z

Documentation/git-bash.txt

+-----------
+
+The `git-bash.exe` provides a windows run time executable that takes in a
+ few parameter and then starts (typically) the mintty terminal window


What's with the funny indentation?

dscho · 2019-10-17T22:14:22Z

Documentation/git-bash.txt

+ levels of redirection and misdirection so that it all 'just works'
+ despite severe incompatibilities in operating philosphy..
+
+include::glossary-content.txt[]


I don't think it would be a good idea to include the glossary here.

dscho · 2019-10-17T22:14:57Z

Documentation/git-bash.txt

+--------
+
+C:\git-sdk-64\usr\src\MINGW-packages\mingw-w64-git\git-bash.rc
+ describe this (and the .rc extension) for basic windows users.


That's not a "SEE ALSO". That would need to go into a chapter above, something like "Technical Details".

dscho · 2019-10-17T22:15:26Z

Documentation/git-bash.txt

+C:\git-sdk-64\usr\src\MINGW-packages\mingw-w64-git\git-bash.rc
+ describe this (and the .rc extension) for basic windows users.
+
+C:\git-sdk-64\usr\src\MINGW-packages\mingw-w64-git\compat-bash.rc


That has nothing to do with git-bash.exe. Those are the resources to be used for <Git>\bin\bash.exe.

dscho · 2019-10-17T22:15:55Z

Documentation/git-bash.txt

+C:\git-sdk-64\usr\src\MINGW-packages\mingw-w64-git\compat-bash.rc
+
+
+C:\git-sdk-64\usr\src\git\contrib\mw-to-git\bin-wrapper\


MediaWiki to Git? What does that have to do with git-bash.exe?

dscho · 2019-10-17T22:16:13Z

Documentation/git-bash.txt

+ various wrappers to describe.
+
+
+https://github.com/git-for-windows/git/issues/1674


That should not go into the text, but into the commit message.

PhilipOakley · 2019-10-18T12:25:42Z

I would also strongly recommend to move this into MINGW-packages instead. It does not make sense in the git repository, as the source code for git-bash..exe does not live here.

My main issue here was that of discoverability sticking it over there, out of the way, I don't think will make it useful. I might not be great in the git help docs, but should be more findable for regular users.

The transition from Windows to the Linux world is not that easy for many users (even getting some to be happy with touching the cli..), hence the desire to find a way of providing 'on-ramps' that feel familiar.

For example I don't know how to get a man page from the regular install. man isn't installed, and help <cmd> only list the summary (I had to guess about using the help command).

Thought. Maybe we need a git help git-for-windows man page as a top level doc within the git hierarchy as an alternate if the git-bash has to be moved...

dscho · 2019-10-18T21:33:01Z

I would also strongly recommend to move this into MINGW-packages instead. It does not make sense in the git repository, as the source code for git-bash..exe does not live here.

My main issue here was that of discoverability sticking it over there, out of the way, I don't think will make it useful.

Well, opening a PR sends a pretty strong signal "I am doing this". And if you are already doing this, opening a PR in the correct spot is quite a bit more helpful than in the wrong spot 😄

I might not be great in the git help docs, but should be more findable for regular users.

You basically want git help git-bash to Just Work?

That's what I suggested: move the git-bash.txt file over to MINGW-packages' mingw-w64-git/ subdirectory, then integrate it into the build process:

add it to the sources in the PKGBUILD
as part of the build () function in PKGBUILD, copy the git-bash.txt file into Documentation/, just before doc-html and/or doc-man are made.
build the package with sdk build

That should be it already.

You should be able to verify that everything worked as expected if the resulting *-html*.tar.xz contains that git-bash.html you were looking for.

But once that works, it is time to actually figure out from git-wrapper.c's source code what options are available and to document at least some of them: https://github.com/git-for-windows/MINGW-packages/blob/e52f91ddc34cac7fcf7704b2c1948bf190373134/mingw-w64-git/git-wrapper.c#L510-L550

You should then also document that any unrecognized command-line option will make git-bash stop parsing, and the remainder of the command-line will be passed verbatim to the command (in this case, that mintty command: https://github.com/git-for-windows/MINGW-packages/blob/e52f91ddc34cac7fcf7704b2c1948bf190373134/mingw-w64-git/git-bash.rc#L3

PhilipOakley · 2019-10-19T19:55:04Z

Well, opening a PR sends a pretty strong signal "I am doing this".

I maybe should have added some label for "Needs help" 😉

We can get the right document to the right place once we've got some content (a big thank you for the pointers), and a common view of the finding/reading route.

dscho · 2019-10-19T21:08:24Z

Well, opening a PR sends a pretty strong signal "I am doing this".

I maybe should have added some label for "Needs help" 😉

Actually, I don't think that helps at all. Since you opened this PR, it is clear that nobody can work on this without stumbling over your feet.

We can get the right document to the right place once we've got some content (a big thank you for the pointers), and a common view of the finding/reading route.

We could also move it into the correct spot and then you could work on the content.

PhilipOakley · 2019-11-11T16:30:09Z

opening a PR sends a pretty strong signal

In this case, the PR was simply an initial notification that 'something needed to be done' by/with the community. It was not "I am doing this".

I'll close it.

dscho requested changes Oct 17, 2019

View reviewed changes

PhilipOakley mentioned this pull request Oct 19, 2019

There is almost no tutorial or documentation suggesting anyone how to create your own custom git-bash.exe arguments like "--cd-to-home" . Can you kindly provide the steps and guidance to do that ? #1674

Closed

PhilipOakley added the Help Wanted help is requested from collaborators, please! label Oct 19, 2019

weekly-digest bot mentioned this pull request Oct 20, 2019

Weekly Digest (13 October, 2019 - 20 October, 2019) #2363

Closed

PhilipOakley mentioned this pull request Oct 25, 2019

Can we use this version to use another shell in VS Code? git-for-windows/git-sdk-64#17

Closed

PhilipOakley closed this Nov 11, 2019

		C:\git-sdk-64\usr\src\MINGW-packages\mingw-w64-git\compat-bash.rc


		C:\git-sdk-64\usr\src\git\contrib\mw-to-git\bin-wrapper\

		various wrappers to describe.


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

git-bash: document the Windows initiator program #2357

git-bash: document the Windows initiator program #2357

Uh oh!

Conversation

PhilipOakley commented Oct 16, 2019

Uh oh!

dscho left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhilipOakley commented Oct 18, 2019

Uh oh!

dscho commented Oct 18, 2019

Uh oh!

PhilipOakley commented Oct 19, 2019

Uh oh!

dscho commented Oct 19, 2019

Uh oh!

PhilipOakley commented Nov 11, 2019

Uh oh!

Uh oh!