# A tour of git: the basics (and notes on some unfriendly messages) 26 messages from 2007-09-28 to 2007-09-30. Participants: Carl Worth, Shawn O. Pearce, Junio C Hamano, Johannes Schindelin, Nguyen Thai Ngoc Duy, Steffen Prohaska, Pierre Habouzit, Wincent Colaiuta. Thread: https://gitlist.dev/t/10064 ## Carl Worth, 2007-09-28 23:07 Subject: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <87ir5us82a.wl%cworth@cworth.org> URL: https://gitlist.dev/e/87ir5us82a.wl%25cworth%40cworth.org ``` I recently "ported" the introductory chapter of Bryan O’Sullivan's Distributed revision control with Mercurial[1] from mercurial to git. The result is here: A tour of git: the basics http://cworth.org/hgbook-git/tour/ I did this as an attempt to demonstrate that git and mercurial are fundamentally equally "easy to learn", and definitely not as an effort to try to leech Bryan's hard work, (nor would I even want to encourage that kind of thing). More of my rationale is available here: Git is easy to learn http://cworth.org/hgbook-git/ I have two reasons for sharing this with the list. First, I'd appreciate any feedback that the knowledgable readers on this list might have. If anything could be made more clear, or if I have factual mistakes in the text, I'd definitely like to fix those. Please let me know. Second, the process of porting the document highlighted a few issues in git that I think would be nice to fix. I only noticed fairly cosmetic issues, but I included them as XXX comments in the text. I'll share them here as well: (all of these are with git 1.5.3.2). * Is "git help" actually a builtin thing or just a way to call out to "man"? Does it work at all in Windows ports of git, for example? (OK, so that one's just a question, not an issue it git) * Would it make sense to put much smaller amounts of text into "git help" than the entire man page? For example, maybe just the description and the most common options or maybe an example? Maybe do something like "git -v help" for more details? See my text for more on this, or compare "git help init" to "hg help init" and "hg -v help init". * The output from a git-clone operating locally is really confusing: $ git clone hello hello-clone Initialized empty Git repository in /tmp/hello-clone/.git/ 0 blocks Empty? Didn't I just clone it? What does "0 blocks" mean? * git-log by default displays "Date" that is the author date, but also only uses committer date for options such as --since. This is confusing. * It would be nice if all short-format options, (like "git log -p"), were also available in a long-format option, (like "git log --patch"). * There's a ton of extraneous output from git-fetch. I would love to see it reduced to a single-line progress bar, (even if a multiple-staged progress bar). I'm imagining a final line something like: Computing (100%) Transferring (100%) But you can imagine more accurate words than those, (I'm not even sure what all of the things mean that git-fetch is currently reporting progress on). Obviously some of these would be pretty easy, and I should jump into the git implementation to try them out, but I've just been typing this stuff as fast as I could, and I'm about to go campout in the rain and hail now, (fun, fun!), so I wanted to get this out before I forgot anything. Thanks in advance for any of your time, attention, or feedback, (and especially any patches!). -Carl [1] http://hgbook.red-bean.com/ ``` ## Shawn O. Pearce, 2007-09-29 00:00 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <20070929000056.GZ3099@spearce.org> URL: https://gitlist.dev/e/20070929000056.GZ3099%40spearce.org In-Reply-To: <87ir5us82a.wl%cworth@cworth.org> ``` Carl Worth wrote: > I recently "ported" the introductory chapter of Bryan O’Sullivan's > Distributed revision control with Mercurial[1] from mercurial to > git. The result is here: > > A tour of git: the basics > http://cworth.org/hgbook-git/tour/ Interesting. > * Is "git help" actually a builtin thing or just a way to call out to > "man"? Does it work at all in Windows ports of git, for example? > (OK, so that one's just a question, not an issue it git) `git help` with no arguments displays a message compiled into git. `git help init` runs `man git-init`. If you don't have any manual pages installed, or if they aren't available to your man installation then it fails with "No manual entry for git-init" or whatever your local man implementation dumps. Brett Schwartz started an asciidoc viewer for Tcl/Tk that I am still playing around with and trying to get working right in git-gui. In theory one could use that to display the manual right from the asciidoc files, thus bypassing the need for asciidoc and xmlto. On Cygwin we have man, so `git help init` (or `git init --help`) work just fine to display the manual entry. No idea about the MSYS port. > * The output from a git-clone operating locally is really confusing: > > $ git clone hello hello-clone > Initialized empty Git repository in /tmp/hello-clone/.git/ > 0 blocks > > Empty? Didn't I just clone it? What does "0 blocks" mean? Yea. That's because we realized its on the local disk and used `cpio` with hardlinks to copy the files. So cpio says it copied 0 blocks as it actually just hardlinked everything for you. No data was actually copied. git-gui's new clone UI uses fancy progress meters here and tries to shield the user from "plumbing and UNIX tools" spitting out seemingly nonsense messages. We probably should try harder in git-clone to do the same here. > * git-log by default displays "Date" that is the author date, but > also only uses committer date for options such as --since. This is > confusing. I've never thought about that. But when you say it I think its very obvious that it could be confusing to a new user. Maybe we should show the committer line and its date if it doesn't match the author name/date. Usually I don't care who committed a change in git.git (its a very small handful of people that Junio pulls from directly) but at day-job committer name is usually just as interesting as the author name *when they aren't the same*. > * There's a ton of extraneous output from git-fetch. I would love to > see it reduced to a single-line progress bar, (even if a > multiple-staged progress bar). I'm imagining a final line > something like: > > Computing (100%) Transferring (100%) > > But you can imagine more accurate words than those, (I'm not even > sure what all of the things mean that git-fetch is currently > reporting progress on). Yea. About half of that output is from pack-objects and either unpack-objects or index-pack. The other part is from git-fetch itself as it updates the local tracking branches (if any are to be updated). Now that git-fetch is in C and reasonably stable maybe I can look into making this prettier. Few people really grok the pack-objects/index-pack output, nor do they care. They just want to know two things: - Is git working or frozen in limbo? - Is git frozen because my network sucks, or git sucks? - When will this be done? Please $DIETY, I want to go home! Make the fetch finish! The C based git-fetch made the http protocol almost totally silent. (No more got/walk messages.) But that's actually also bad as it now doesn't even let you know its transferring anything at all. There are serious issues here about getting the user the progress they really want. The last item ("When will this be done?") is actually not possible to determine under either the native git protocol or HTTP/FTP. We have no idea up front how much data must be transferred. In the native git case we do know how many objects, but we don't know how many bytes that will be. It could be under a kilobyte in one project. That same object count for a different set of objects fetch could be 500M. Radically different transfer times would be required. -- Shawn. ``` ## Junio C Hamano, 2007-09-29 00:45 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <7v1wcinvth.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v1wcinvth.fsf%40gitster.siamese.dyndns.org In-Reply-To: <87ir5us82a.wl%cworth@cworth.org> ``` Thanks for starting this. It was an interesting read. ---------------------------------------------------------------- #2.2.1 "git help init" would give man page. The time when the short help is given is when you mistype options, as in: $ git init --huh? #2.4 By default this command prints a brief paragraph of output... Not really. The default is to give you the entire log message, unless you somehow made --pretty=short the default with your copy of git. The "git log" tool doesn't display the Committer... You can ask it to, so "by default" is missing. #2.7.1 But some poepl, (notably Linus... typo. #2.7.6 for which "git commit --amend" was was what? "invented" perhaps? #2.8.3 Using "git remote" to pull changes other repositories "changes from other repositories". ---------------------------------------------------------------- ``` ## Johannes Schindelin, 2007-09-29 00:49 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0709290144310.28395%40racer.site In-Reply-To: <20070929000056.GZ3099@spearce.org> ``` Hi, On Fri, 28 Sep 2007, Shawn O. Pearce wrote: > On Cygwin we have man, so `git help init` (or `git init --help`) work > just fine to display the manual entry. No idea about the MSYS port. We open the html pages. That is, we don't yet, since we do not generate the html pages just yet; asciidoc is a Python program, and Python is not available as an MSys program as far as I know (and asciidoc insists on finding files in a Unix-like file structure, so we _do_ need an MSys Python). ... but all this would be easier if we succeeded in having a minimal asciidoc lookalike in git.git... > > * The output from a git-clone operating locally is really confusing: > > > > $ git clone hello hello-clone > > Initialized empty Git repository in /tmp/hello-clone/.git/ > > 0 blocks > > > > Empty? Didn't I just clone it? What does "0 blocks" mean? > > Yea. That's because we realized its on the local disk and used > `cpio` with hardlinks to copy the files. So cpio says it copied > 0 blocks as it actually just hardlinked everything for you. No > data was actually copied. > > git-gui's new clone UI uses fancy progress meters here and tries > to shield the user from "plumbing and UNIX tools" spitting out > seemingly nonsense messages. We probably should try harder in > git-clone to do the same here. AFAICT git-clone is a prime candidate for builtinification, after which issues like this should be easy to address. > > * git-log by default displays "Date" that is the author date, but > > also only uses committer date for options such as --since. This is > > confusing. > > I've never thought about that. But when you say it I think its very > obvious that it could be confusing to a new user. Maybe we should show > the committer line and its date if it doesn't match the author > name/date. Usually I don't care who committed a change in git.git (its > a very small handful of people that Junio pulls from directly) but at > day-job committer name is usually just as interesting as the author name > *when they aren't the same*. --pretty=fuller Ciao, Dscho ``` ## Nguyen Thai Ngoc Duy, 2007-09-29 05:32 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/fcaeb9bf0709282232v376d2bccoc7ffcc5ae184b59e%40mail.gmail.com In-Reply-To: <87ir5us82a.wl%cworth@cworth.org> ``` On 9/29/07, Carl Worth wrote: > I recently "ported" the introductory chapter of Bryan O'Sullivan's > Distributed revision control with Mercurial[1] from mercurial to > git. The result is here: > > A tour of git: the basics > http://cworth.org/hgbook-git/tour/ Minor thing. On Gentoo you should do "emerge dev-util/git" instead of "emerge git" because there is another program with the same name. -- Duy ``` ## Steffen Prohaska, 2007-09-29 07:44 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <4D958F04-D531-416A-9FB4-E4119BEC6905@zib.de> URL: https://gitlist.dev/e/4D958F04-D531-416A-9FB4-E4119BEC6905%40zib.de In-Reply-To: ``` On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote: > > On Fri, 28 Sep 2007, Shawn O. Pearce wrote: > >> On Cygwin we have man, so `git help init` (or `git init --help`) work >> just fine to display the manual entry. No idea about the MSYS port. > > We open the html pages. That is, we don't yet, since we do not > generate > the html pages just yet; asciidoc is a Python program, and Python > is not > available as an MSys program as far as I know (and asciidoc insists on > finding files in a Unix-like file structure, so we _do_ need an MSys > Python). > I propose to clone the html pages from git.git's html branch and include them in the installer. I continue to believe that this is the simplest and fastest solution for providing html pages. I'll provide a patch (hopefully next week). Steffen ``` ## Pierre Habouzit, 2007-09-29 09:01 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <20070929090121.GA4216@artemis.corp> URL: https://gitlist.dev/e/20070929090121.GA4216%40artemis.corp In-Reply-To: <20070929000056.GZ3099@spearce.org> ``` On Sat, Sep 29, 2007 at 12:00:56AM +0000, Shawn O. Pearce wrote: > The C based git-fetch made the http protocol almost totally silent. > (No more got/walk messages.) But that's actually also bad as it > now doesn't even let you know its transferring anything at all. > > There are serious issues here about getting the user the progress > they really want. The last item ("When will this be done?") is > actually not possible to determine under either the native git > protocol or HTTP/FTP. We have no idea up front how much data must > be transferred. In the native git case we do know how many objects, > but we don't know how many bytes that will be. It could be under > a kilobyte in one project. That same object count for a different > set of objects fetch could be 500M. Radically different transfer > times would be required. I'm not sure you need the ETA thing. I've used bzr only a couple of time, I don't think it shows any kind of ETA, but I think I remember sth like: Stage 3/4 [==========================> ] [43%] And that's all is needed. It's sober, and informative enough I think. Many git commands output are still messy and indeed, having them in C should help in that regard. The usual culprit are I think: * git fetch/clone/pull/.. ; * git push ; * git repack/gc/... ; * git merge (even with the merge.verbosity set to the minimum it's still not very readable and confusing). I do believe that the quite verbose output git commands sometimes have is quite confusing, and let the user think it's messy. I believe that porcelains should be more silent, it's OK for the plumbing to spit progress messages and so on, because people using the plumbing are able to understand those, but porcelains should not. -- ·O· Pierre Habouzit ··O madcoder@debian.org OOO http://www.madism.org ``` ## Johannes Schindelin, 2007-09-29 15:06 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0709291606010.28395%40racer.site In-Reply-To: <4D958F04-D531-416A-9FB4-E4119BEC6905@zib.de> ``` Hi, On Sat, 29 Sep 2007, Steffen Prohaska wrote: > On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote: > > > > > On Fri, 28 Sep 2007, Shawn O. Pearce wrote: > > > > > On Cygwin we have man, so `git help init` (or `git init --help`) > > > work just fine to display the manual entry. No idea about the MSYS > > > port. > > > > We open the html pages. That is, we don't yet, since we do not > > generate the html pages just yet; asciidoc is a Python program, and > > Python is not available as an MSys program as far as I know (and > > asciidoc insists on finding files in a Unix-like file structure, so we > > _do_ need an MSys Python). > > I propose to clone the html pages from git.git's html branch and include > them in the installer. I continue to believe that this is the simplest > and fastest solution for providing html pages. I'm hesitant... The html branch is synced with the master branch. And we deviate from the master branch quite a lot ATM. > I'll provide a patch (hopefully next week). This will be a good temporary workaround. Ciao, Dscho ``` ## Steffen Prohaska, 2007-09-29 16:05 Subject: [PATCH] WinGit: included /bin/start in the installer Message-ID: <11910819531200-git-send-email-prohaska@zib.de> URL: https://gitlist.dev/e/11910819531200-git-send-email-prohaska%40zib.de In-Reply-To: ``` /bin/start is needed to tell Windows to open html pages. Signed-off-by: Steffen Prohaska --- share/WinGit/release.sh | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/share/WinGit/release.sh b/share/WinGit/release.sh index 67d0725..5ab876a 100644 --- a/share/WinGit/release.sh +++ b/share/WinGit/release.sh @@ -29,7 +29,7 @@ ls.exe,md5sum.exe,mkdir.exe,msys-1.0.dll,msysltdl-3.dll,mv.exe,patch.exe,\ patch.exe.manifest,perl.exe,printf,ps.exe,pwd,rm.exe,rmdir.exe,rxvt.exe,\ scp.exe,sed.exe,sh.exe,sleep.exe,sort.exe,split.exe,ssh-agent.exe,ssh.exe,\ tail.exe,tar.exe,tee.exe,touch.exe,tr.exe,true.exe,uname.exe,uniq.exe,vi,\ -vim.exe,wc.exe,which,xargs.exe,ssh-add.exe} lib/perl5/ share/git* share/vim) | +vim.exe,wc.exe,which,xargs.exe,ssh-add.exe,start} lib/perl5/ share/git* share/vim) | tar xvf - && mkdir lib/perl5/site_perl && cp /lib/{Error.pm,Git.pm} lib/perl5/site_perl/ && -- 1.5.3.mingw.1.3.g195850 ``` ## Steffen Prohaska, 2007-09-29 16:05 Subject: [PATCH] WinGit: include html pages from official git.git's html branch Message-ID: <11910819542185-git-send-email-prohaska@zib.de> URL: https://gitlist.dev/e/11910819542185-git-send-email-prohaska%40zib.de In-Reply-To: <11910819531200-git-send-email-prohaska@zib.de> ``` It is assumed that a matching version of the html documentation is available as the HEAD of /doc/git/html/.git. If not an error will be reported. This patch doesn't include a mechanism to fetch the html pages to /doc/git/html/.git. You should manually clone them. Maybe this could handled as a submodule of msysgit? Signed-off-by: Steffen Prohaska --- share/WinGit/release.sh | 5 +++++ 1 files changed, 5 insertions(+), 0 deletions(-) diff --git a/share/WinGit/release.sh b/share/WinGit/release.sh index 5ab876a..8a3c197 100644 --- a/share/WinGit/release.sh +++ b/share/WinGit/release.sh @@ -5,6 +5,8 @@ test -z "$1" && { exit 1 } +test -d /doc/git/html/.git || { echo "Error: html pages in /doc/git/html/.git missing"; exit 1; } + TARGET="$HOME"/WinGit-$1.exe OPTS7="-m0=lzma -mx=9 -md=64M" TARGET7=tmp.7z @@ -21,6 +23,9 @@ mkdir "$TMPDIR" && cp uninstaller.exe "$TMPDIR"/bin) && cd "$TMPDIR" && echo "Copying files" && +(git --git-dir=/doc/git/html/.git log --pretty=format:%s -1 HEAD && + mkdir -p doc/git/html && cd doc/git/html && + git --git-dir=/doc/git/html/.git archive HEAD | tar xf -) && (cd / && tar cf - bin/{git*,awk,basename.exe,bash.exe,bunzip2,bzip2.exe,\ cat.exe,chmod.exe,clear,cmp.exe,cp.exe,cpio,cut.exe,cvs.exe,date.exe,diff.exe,\ du.exe,echo,egrep,env.exe,expr.exe,false.exe,find.exe,gawk.exe,grep.exe,\ -- 1.5.3.mingw.1.3.g195850 ``` ## Steffen Prohaska, 2007-09-29 16:06 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/A835C8E8-8EC5-43B7-9252-8709214DE7AD%40zib.de In-Reply-To: ``` On Sep 29, 2007, at 5:06 PM, Johannes Schindelin wrote: > Hi, > > On Sat, 29 Sep 2007, Steffen Prohaska wrote: > >> On Sep 29, 2007, at 2:49 AM, Johannes Schindelin wrote: >> >>> >>> On Fri, 28 Sep 2007, Shawn O. Pearce wrote: >>> >>>> On Cygwin we have man, so `git help init` (or `git init --help`) >>>> work just fine to display the manual entry. No idea about the MSYS >>>> port. >>> >>> We open the html pages. That is, we don't yet, since we do not >>> generate the html pages just yet; asciidoc is a Python program, and >>> Python is not available as an MSys program as far as I know (and >>> asciidoc insists on finding files in a Unix-like file structure, >>> so we >>> _do_ need an MSys Python). >> >> I propose to clone the html pages from git.git's html branch and >> include >> them in the installer. I continue to believe that this is the >> simplest >> and fastest solution for providing html pages. > > I'm hesitant... The html branch is synced with the master branch. > And we > deviate from the master branch quite a lot ATM. We could choose a specific commit from the html branch for the WinGit release. I don't think we'll need modifications to the documentation in msysgit. Selecting an older version that matches the state of msysgit should be sufficient. Fixes to the documentation could be committed directly to git.git. >> I'll provide a patch (hopefully next week). > > This will be a good temporary workaround. The patch following soon will assume that html is available. Maybe we could add it as a submodule of msysgit? I haven't looked into the submodule mechanisms and therefore will not include it in the patch. I just manually cloned the html branch. For now, this may be sufficient to create a WinGit installer. Steffen ``` ## Johannes Schindelin, 2007-09-29 20:50 Subject: Re: [PATCH] WinGit: include html pages from official git.git's html branch Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0709292149280.28395%40racer.site In-Reply-To: <11910819542185-git-send-email-prohaska@zib.de> ``` Hi, On Sat, 29 Sep 2007, Steffen Prohaska wrote: > It is assumed that a matching version of the html documentation > is available as the HEAD of /doc/git/html/.git. If not an error > will be reported. > > This patch doesn't include a mechanism to fetch the html pages > to /doc/git/html/.git. You should manually clone them. Maybe > this could handled as a submodule of msysgit? I'd rather handle it as in git.git, as another branch, and not check it out in /git/html/, but rather use "git read-tree --prefix=/tmp/WinGit/share/git/html origin/html", or some such. Ciao, Dscho ``` ## Steffen Prohaska, 2007-09-29 21:48 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/E5C688F2-4A8D-402A-9757-5007BE4A8B25%40zib.de In-Reply-To: <20070929000056.GZ3099@spearce.org> ``` On Sep 29, 2007, at 2:00 AM, Shawn O. Pearce wrote: >> * There's a ton of extraneous output from git-fetch. I would >> love to >> see it reduced to a single-line progress bar, (even if a >> multiple-staged progress bar). I'm imagining a final line >> something like: >> >> Computing (100%) Transferring (100%) >> >> But you can imagine more accurate words than those, (I'm not even >> sure what all of the things mean that git-fetch is currently >> reporting progress on). > > Yea. About half of that output is from pack-objects and either > unpack-objects or index-pack. The other part is from git-fetch > itself as it updates the local tracking branches (if any are to be > updated). Now that git-fetch is in C and reasonably stable maybe > I can look into making this prettier. Few people really grok the > pack-objects/index-pack output, nor do they care. They just want > to know two things: > > - Is git working or frozen in limbo? > - Is git frozen because my network sucks, or git sucks? > - When will this be done? Please $DIETY, I want to go home! > Make the fetch finish! > > The C based git-fetch made the http protocol almost totally silent. > (No more got/walk messages.) But that's actually also bad as it > now doesn't even let you know its transferring anything at all. > > There are serious issues here about getting the user the progress > they really want. The last item ("When will this be done?") is > actually not possible to determine under either the native git > protocol or HTTP/FTP. We have no idea up front how much data must > be transferred. In the native git case we do know how many objects, > but we don't know how many bytes that will be. It could be under > a kilobyte in one project. That same object count for a different > set of objects fetch could be 500M. Radically different transfer > times would be required. Often you know that you have a good connection and you are not interested in any progress reporting at all. _No_ output would be perfect. A return code of 0 would already tell you all you need to know. If you'd like to know more you could pass something like '--verbose' or '--progress'. Quite often git prints a lot of very technical information that is not very interesting as long as things succeed without error. Some examples are - git fetch (see above) - git rebase: prints a lot of details that I'm not interested in unless the rebase fails. - git push: prints updates of remote heads. A message about failing to update a remote head may get lost. - git merge: the fact that a merge is a fast forward merge gets printed at the very top, followed by (often a lot of) diffstat. I know diffstat can help to judge if the merge did what you expected. But even more important is the fact that the merge was just a fast forward, which may get buried under lots of output. Maybe git should become more quiet, as other unix tools are, and per default only report problems. Technical details and progress could be requested explicitly by '--verbose' or similar. We could pipe all the technical output to a per-repository logfile, which can be consulted in case of errors. The log could be cropped during 'git gc'. Steffen ``` ## Junio C Hamano, 2007-09-29 22:13 Subject: Re: [PATCH] WinGit: include html pages from official git.git's html branch Message-ID: <7vr6khjf22.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vr6khjf22.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Johannes Schindelin writes: > Hi, > > On Sat, 29 Sep 2007, Steffen Prohaska wrote: > >> It is assumed that a matching version of the html documentation >> is available as the HEAD of /doc/git/html/.git. If not an error >> will be reported. >> >> This patch doesn't include a mechanism to fetch the html pages >> to /doc/git/html/.git. You should manually clone them. Maybe >> this could handled as a submodule of msysgit? > > I'd rather handle it as in git.git, as another branch, and not check it > out in /git/html/, but rather use "git read-tree > --prefix=/tmp/WinGit/share/git/html origin/html", or some such. This is starting to smell like an opportunity to use the gitlink stuff, isn't it? ``` ## Junio C Hamano, 2007-09-29 22:25 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <7vlkapjeir.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vlkapjeir.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Steffen Prohaska writes: > Quite often git prints a lot of very technical information that > is not very interesting as long as things succeed without error. > Some examples are > - git fetch (see above) Probably. > - git rebase: prints a lot of details that I'm not interested in > unless the rebase fails. Yes. Most of the clutter is coming from "am" which also should be squelched. Saying Switched to branch is good when the branch to rebase is specified. "HEAD is now at ..." is not useful -- it is a side effect of rewinding the head to the --onto commit. Applying Wrote tree Committed: are coming from "am" for each patch. We could squelch these into just one "Applying " and nothing else, which would also help making "am" quieter. > - git push: prints updates of remote heads. A message about > failing to update a remote head may get lost. Please do not remove the report of successful update, as people often say "git push" or "git push $there" without explicitly saying which refs to push. When pushing out to publish, I say "git push ko" (to mean k.org) and I _want_ my positive feedback. > - git merge: the fact that a merge is a fast forward merge gets > printed at the very top, followed by (often a lot of) diffstat. > I know diffstat can help to judge if the merge did what you > expected. But even more important is the fact that the merge > was just a fast forward, which may get buried under lots of output. I do not think fast-forwardness is particularly interesting. If you find fast-forwardness interesting, I suspect you would even want to know what _your_ change that were not in the other side of the merge, which is something that we do not even report right now. > Maybe git should become more quiet, as other unix tools are, and > per default only report problems. Technical details and progress > could be requested explicitly by '--verbose' or similar. I'd agree with this sentiment in principle, and many of the things you propose to remove above fall into the "unnecessary clutter" category. But some of the existing output fall into the "necessary info" category --- diffstart after merge and report of successful remote ref updates are such things, so we should be careful not to go overboard. ``` ## Johannes Schindelin, 2007-09-29 23:23 Subject: Re: [PATCH] WinGit: include html pages from official git.git's html branch Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0709300022080.28395%40racer.site In-Reply-To: <7vr6khjf22.fsf@gitster.siamese.dyndns.org> ``` Hi, On Sat, 29 Sep 2007, Junio C Hamano wrote: > Johannes Schindelin writes: > > > On Sat, 29 Sep 2007, Steffen Prohaska wrote: > > > >> It is assumed that a matching version of the html documentation is > >> available as the HEAD of /doc/git/html/.git. If not an error will be > >> reported. > >> > >> This patch doesn't include a mechanism to fetch the html pages to > >> /doc/git/html/.git. You should manually clone them. Maybe this could > >> handled as a submodule of msysgit? > > > > I'd rather handle it as in git.git, as another branch, and not check > > it out in /git/html/, but rather use "git read-tree > > --prefix=/tmp/WinGit/share/git/html origin/html", or some such. > > This is starting to smell like an opportunity to use the gitlink stuff, > isn't it? I'd agree that we could have a submodule in /doc/git/html/. This way, even users of msysGit and GitMe would benefit. Ciao, Dscho ``` ## Carl Worth, 2007-09-30 03:38 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <87d4w0styy.wl%cworth@cworth.org> URL: https://gitlist.dev/e/87d4w0styy.wl%25cworth%40cworth.org In-Reply-To: <7v1wcinvth.fsf@gitster.siamese.dyndns.org> ``` On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote: > Thanks for starting this. It was an interesting read. You're welcome. I hope it's useful for people. The original goal was to demonstrate that git is no harder to learn than mercurial. So that attempt is done, now, (whether successful or not, I can't really judge). Now, after getting some initial feedback, it's clear that the document could further be improved by focusing on the "git way" of doing things that aren't as natural in hg, (like multiple branches in a single repository). Rather than extending the current document, though, I think I'll just draw up on outline based on what I think would be a good order to introduce the topics. And then I'll see what text in the current user's guide could plug into that outline, and what pieces might be missing or could be improved. At least, that's my thoughts for now. I don't know if I'll get around to it though, (we'll have to see if I get annoyed into doing that work like I got annoyed into this first project). > "git help init" would give man page. The time when the short > help is given is when you mistype options, as in: > > $ git init --huh? Oh, and that's *really* short output. Just a summary of the command-line options and no description. If you look at "hg help" it has a middle-ground option which is little more than a brief description and a very small number of options. I think that's a useful thing to consider for "git help". Or, perhaps just carefully construct the man page so that this most important information is first. See "git help clone" for example which does have a better order than "git help init" in my opinion. Meanwhile, "git init --huh?" is totally appropriate in just printing usage information. That's really all you want to see if you forget the exact name of a particular command-line option. Trying a couple of random examples though, git could be better in some cases: $ git log --pretty=complete fatal: invalid --pretty format: complete That's a fairly specific error message, but no information on what I might have meant to say. A fix should be be quite simple, (presumably there's a list of --pretty options it just looped through and it might as well print them out). $ git log --format=fuller fatal: unrecognized argument: --format=fuller There's no usage given in this case at all. It should print some usage statement, hopefully containing --pretty. Admittedly, this one is *really* hard to fix entirely since there is a ridiculously large number of possible options to a command like "git log". But a aummary of the most common stuff should still help. Thanks for the various typo fixes. I've implemented those, (and the things submitted by others). There were some particularly bad markup problems where "git commit " was being misinterpreted and presented as "git commit" which was fairly disastrous for my intended meaning. Hopefully it's much better now. -Carl ``` ## Carl Worth, 2007-09-30 03:38 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <87bqbkstyq.wl%cworth@cworth.org> URL: https://gitlist.dev/e/87bqbkstyq.wl%25cworth%40cworth.org In-Reply-To: <7v1wcinvth.fsf@gitster.siamese.dyndns.org> ``` On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote: > Thanks for starting this. It was an interesting read. You're welcome. I hope it's useful for people. The original goal was to demonstrate that git is no harder to learn than mercurial. So that attempt is done, now, (whether successful or not, I can't really judge). Now, after getting some initial feedback, it's clear that the document could further be improved by focusing on the "git way" of doing things that aren't as natural in hg, (like multiple branches in a single repository). Rather than extending the current document, though, I think I'll just draw up on outline based on what I think would be a good order to introduce the topics. And then I'll see what text in the current user's guide could plug into that outline, and what pieces might be missing or could be improved. At least, that's my thoughts for now. I don't know if I'll get around to it though, (we'll have to see if I get annoyed into doing that work like I got annoyed into this first project). > "git help init" would give man page. The time when the short > help is given is when you mistype options, as in: > > $ git init --huh? Oh, and that's *really* short output. Just a summary of the command-line options and no description. If you look at "hg help" it has a middle-ground option which is little more than a brief description and a very small number of options. I think that's a useful thing to consider for "git help". Or, perhaps just carefully construct the man page so that this most important information is first. See "git help clone" for example which does have a better order than "git help init" in my opinion. Meanwhile, "git init --huh?" is totally appropriate in just printing usage information. That's really all you want to see if you forget the exact name of a particular command-line option. Trying a couple of random examples though, git could be better in some cases: $ git log --pretty=complete fatal: invalid --pretty format: complete That's a fairly specific error message, but no information on what I might have meant to say. A fix should be be quite simple, (presumably there's a list of --pretty options it just looped through and it might as well print them out). $ git log --format=fuller fatal: unrecognized argument: --format=fuller There's no usage given in this case at all. It should print some usage statement, hopefully containing --pretty. Admittedly, this one is *really* hard to fix entirely since there is a ridiculously large number of possible options to a command like "git log". But a summary of the most common stuff should still help. Thanks for the various typo fixes. I've implemented those, (and the things submitted by others). There were some particularly bad markup problems where "git commit " was being misinterpreted and presented as "git commit" which was fairly disastrous for my intended meaning. Hopefully it's much better now. -Carl ``` ## Steffen Prohaska, 2007-09-30 08:15 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/E8851B12-AAA5-4B4D-9F28-C5AB5AEF0E57%40zib.de In-Reply-To: <7vlkapjeir.fsf@gitster.siamese.dyndns.org> ``` On Sep 30, 2007, at 12:25 AM, Junio C Hamano wrote: > Steffen Prohaska writes: > >> - git push: prints updates of remote heads. A message about >> failing to update a remote head may get lost. > > Please do not remove the report of successful update, as people > often say "git push" or "git push $there" without explicitly > saying which refs to push. When pushing out to publish, I say > "git push ko" (to mean k.org) and I _want_ my positive feedback. Yes but it's pretty technical. A much simpler output could be easier to scan by a human updating 'refs/heads/master' .. fast forward .. ok. updating 'refs/heads/pu' .. forced non-fast forward .. ok. updating 'refs/heads/next' .. ERROR: 'refs/heads/next' not updating to non-fast forward exit(1) here. If we exit after the very first problem it can't get lost. After fixing the issue you can just 'git push' again. >> - git merge: the fact that a merge is a fast forward merge gets >> printed at the very top, followed by (often a lot of) diffstat. >> I know diffstat can help to judge if the merge did what you >> expected. But even more important is the fact that the merge >> was just a fast forward, which may get buried under lots of output. > > I do not think fast-forwardness is particularly interesting. If > you find fast-forwardness interesting, I suspect you would even > want to know what _your_ change that were not in the other side > of the merge, which is something that we do not even report > right now. I use it to advance a branch to a temporary integration branch. At that point I expect that the merge is a fast forward. Here's what I do. git checkout -b for/master master git merge branch-with-good-topics git branch -f scratch git push compileservers # pushes scratch for automatic builds Now I wait for compiles to finish. Typically I continue not before the next morning. If everything's ok I do. git checkout master git merge for/master git push The last merge must be a fast forward. This is the only fact I'm interested in. I could do 'git reset' or 'git branch -f' but then I'd loose the check if it's a fast forward. I don't merge directly to master to avoid any accidentally push. I can also easily revert by just deleting 'for/master'. Maybe there's a better workflow? >> Maybe git should become more quiet, as other unix tools are, and >> per default only report problems. Technical details and progress >> could be requested explicitly by '--verbose' or similar. > > I'd agree with this sentiment in principle, and many of the > things you propose to remove above fall into the "unnecessary > clutter" category. But some of the existing output fall into > the "necessary info" category --- diffstart after merge I agree. Could we print the note about fast forward _after_ the diffstat? Maybe there are more useful oneline information that could be output there. > and report of successful remote ref updates are such things, so we > should be careful not to go overboard. But the output could be less technical and more human readable. Also diffstat's output and "git push" are different. diffstats change with the content of your repo. "git push" just succeeds or fails. If is succeeds it updates remote refs according to your configuration. There is no new information in the output beyond success or failure [which is not quite true if you depend on git push finding matching refs automatically -- I don't]. I don't think the sha1's printed are needed by anyone. And if someone needs them, he could call push with '--verbose'. I asked about a '--dry-run' switch to "git push" some time ago, which would only report what "git push" would do without actually changing anything on the remote side. I'd use this to check what I expect to do. Just in case I messed up my configuration. At the time "git push" is actually pushing it's too late to fix a broken configuration. I know '--dry-run' it's not trivial to implement and I'll likely have no time to look into it. Steffen ``` ## Steffen Prohaska, 2007-09-30 08:19 Subject: Re: [PATCH] WinGit: include html pages from official git.git's html branch Message-ID: URL: https://gitlist.dev/e/D4E42E0D-99CB-4F4E-AC89-CD94DA061FDC%40zib.de In-Reply-To: ``` On Sep 30, 2007, at 1:23 AM, Johannes Schindelin wrote: > Hi, > > On Sat, 29 Sep 2007, Junio C Hamano wrote: > >> Johannes Schindelin writes: >> >>> On Sat, 29 Sep 2007, Steffen Prohaska wrote: >>> >>>> It is assumed that a matching version of the html documentation is >>>> available as the HEAD of /doc/git/html/.git. If not an error >>>> will be >>>> reported. >>>> >>>> This patch doesn't include a mechanism to fetch the html pages to >>>> /doc/git/html/.git. You should manually clone them. Maybe this >>>> could >>>> handled as a submodule of msysgit? >>> >>> I'd rather handle it as in git.git, as another branch, and not check >>> it out in /git/html/, but rather use "git read-tree >>> --prefix=/tmp/WinGit/share/git/html origin/html", or some such. >> >> This is starting to smell like an opportunity to use the gitlink >> stuff, >> isn't it? > > I'd agree that we could have a submodule in /doc/git/html/. This way, > even users of msysGit and GitMe would benefit. And we could completely tag a WinGit release. The version of the html docs included would be defined by the submodule's head in /doc/git/html. This is what I had in mind when submitting the patch. Maybe I didn't express this clearly. I do not yet understand submodules sufficiently. Therefore I didn't add a patch that actually sets up the submodule in /doc/git/html. Maybe I'll do so later today. Steffen ``` ## Junio C Hamano, 2007-09-30 10:17 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <7vr6kgh2yy.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vr6kgh2yy.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Steffen Prohaska writes: > ... If everything's ok I do. > > git checkout master > git merge for/master > git push > > The last merge must be a fast forward. Last week I saw somebody (I think it was Shawn) mentioned a trick: git push . thisbranch:thatbranch will moves thatbranch to thisbranch iff thisbranch is a descendant of thatbranch. So doing git push . for-master:master instead of that checkout + merge command sequence would obviously be a good solution for your particular use case. Having said that it may make sense to swap the order so that the diffstat is shown first and then a single line "Merge made by recursive" or "Updatting A..B, Fast Forward" concludes the report. At least, I do not think such a swapping would hurt the usability, although people used to the UI may first feel uneasy. I would not object to such a patch in principle. ``` ## Johannes Schindelin, 2007-09-30 12:44 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0709301343000.28395%40racer.site In-Reply-To: ``` Hi, On Sun, 30 Sep 2007, Steffen Prohaska wrote: > > On Sep 30, 2007, at 12:25 AM, Junio C Hamano wrote: > > > Steffen Prohaska writes: > > > > > - git push: prints updates of remote heads. A message about > > > failing to update a remote head may get lost. > > > > Please do not remove the report of successful update, as people often > > say "git push" or "git push $there" without explicitly saying which > > refs to push. When pushing out to publish, I say "git push ko" (to > > mean k.org) and I _want_ my positive feedback. > > Yes but it's pretty technical. > > A much simpler output could be easier to scan by a human > > updating 'refs/heads/master' .. fast forward .. ok. > updating 'refs/heads/pu' .. forced non-fast forward .. ok. > updating 'refs/heads/next' .. > ERROR: 'refs/heads/next' not updating to non-fast forward > exit(1) here. No, please no. This is way too short. If at all, please let 8c3275abcacb83ea3f4c4f4ceb2376799fc282bd be an example, and make git respect several different output levels, but not changing the default (at first). Ciao, Dscho ``` ## Wincent Colaiuta, 2007-09-30 12:45 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <912CB4AE-83B9-42D7-A591-E721D1E22439@wincent.com> URL: https://gitlist.dev/e/912CB4AE-83B9-42D7-A591-E721D1E22439%40wincent.com In-Reply-To: <20070929090121.GA4216@artemis.corp> ``` El 29/9/2007, a las 11:01, Pierre Habouzit escribió: > Many git commands output are still messy and indeed, having them > in C > should help in that regard. The usual culprit are I think: > > * git fetch/clone/pull/.. ; > * git push ; > * git repack/gc/... ; > * git merge (even with the merge.verbosity set to the minimum it's > still not very readable and confusing). > > > I do believe that the quite verbose output git commands sometimes > have > is quite confusing, and let the user think it's messy. I believe that > porcelains should be more silent, it's OK for the plumbing to spit > progress messages and so on, because people using the plumbing are > able > to understand those, but porcelains should not. I think that most people just want to know, "Did it work or not?" and so when the commands chatter too much they go into filter mode, don't really read the output, let alone try to understand it, and just skim it. Ideally Git would be much less "chattery" in general when things work, and only be more verbose when things go wrong; of course, finding that balance point is where the art lies. Wincent ``` ## Steffen Prohaska, 2007-09-30 13:41 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: URL: https://gitlist.dev/e/D6FD584E-9B14-4566-8955-ACA1BAFB0456%40zib.de In-Reply-To: ``` On Sep 30, 2007, at 2:44 PM, Johannes Schindelin wrote: >> >> A much simpler output could be easier to scan by a human >> >> updating 'refs/heads/master' .. fast forward .. ok. >> updating 'refs/heads/pu' .. forced non-fast forward .. ok. >> updating 'refs/heads/next' .. >> ERROR: 'refs/heads/next' not updating to non-fast forward >> exit(1) here. > > No, please no. This is way too short. > > If at all, please let 8c3275abcacb83ea3f4c4f4ceb2376799fc282bd be an > example, and make git respect several different output levels, but not > changing the default (at first). good idea. Steffen ``` ## Pierre Habouzit, 2007-09-30 13:49 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <20070930134937.GG22560@artemis.corp> URL: https://gitlist.dev/e/20070930134937.GG22560%40artemis.corp In-Reply-To: <912CB4AE-83B9-42D7-A591-E721D1E22439@wincent.com> ``` On Sun, Sep 30, 2007 at 12:45:34PM +0000, Wincent Colaiuta wrote: > El 29/9/2007, a las 11:01, Pierre Habouzit escribió: > > > Many git commands output are still messy and indeed, having them in C > >should help in that regard. The usual culprit are I think: > > > > * git fetch/clone/pull/.. ; > > * git push ; > > * git repack/gc/... ; > > * git merge (even with the merge.verbosity set to the minimum it's > > still not very readable and confusing). > > > > > > I do believe that the quite verbose output git commands sometimes have > >is quite confusing, and let the user think it's messy. I believe that > >porcelains should be more silent, it's OK for the plumbing to spit > >progress messages and so on, because people using the plumbing are able > >to understand those, but porcelains should not. > > I think that most people just want to know, "Did it work or not?" and so > when the commands chatter too much they go into filter mode, don't really > read the output, let alone try to understand it, and just skim it. > Ideally Git would be much less "chattery" in general when things work, > and only be more verbose when things go wrong; of course, finding that > balance point is where the art lies. That's true for git merge that is fast. But people also want to know the command is not stuck in an infinite loop, and for that progress bars or little \|/- animation. -- ·O· Pierre Habouzit ··O madcoder@debian.org OOO http://www.madism.org ``` ## Wincent Colaiuta, 2007-09-30 14:31 Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Message-ID: <9FDE609B-ABC1-45D7-AFF9-211381CAF830@wincent.com> URL: https://gitlist.dev/e/9FDE609B-ABC1-45D7-AFF9-211381CAF830%40wincent.com In-Reply-To: <20070930134937.GG22560@artemis.corp> ``` El 30/9/2007, a las 15:49, Pierre Habouzit escribió: > On Sun, Sep 30, 2007 at 12:45:34PM +0000, Wincent Colaiuta wrote: >> >> I think that most people just want to know, "Did it work or not?" >> and so >> when the commands chatter too much they go into filter mode, don't >> really >> read the output, let alone try to understand it, and just skim it. >> Ideally Git would be much less "chattery" in general when things >> work, >> and only be more verbose when things go wrong; of course, finding >> that >> balance point is where the art lies. > > That's true for git merge that is fast. But people also want to know > the command is not stuck in an infinite loop, and for that progress > bars > or little \|/- animation. Yes, I agree. I probably should have said that they either want to know "*Did* it work?" for near-instant operations (most Git operations, hopefully), and "*Is* it working?" for long-running ones (network ops, for example) and in those cases you're right that a progress bar would be a nice enhancement. Cheers, Wincent ```