git-scm.com refresh

git-scm.com refresh

[Scott Chacon]

Hey everyone,

I just shipped a big update to the git-scm.com website, incorporating
tons of feedback I've gotten on the site, especially from new users,
over the years.  I think it will help new users to Git find the right
installer and get up and running easier.  I have other ideas of things
to add to it in the future, but I think this is much better than the
site that has served us well for a few years now.

Some other interesting things to note:

* There is now permanent man page hosting here, for example:
http://git-scm.com/docs/git-fsck.  You can also reference any older
version of any command: http://git-scm.com/docs/git-fsck/1.5.5

* We designed a new logo[1] - there are multiple variations available
for download on the site under the most permissive CC license for any
use.

* The Pro Git book (and all of it's translations) has been directly
incorporated into the site and has better permalinks and section
anchors.  progit.org will soon be redirecting to git-scm.com.

* Matthew McCullough has started a video series[2] for newbies and
will continue to do more developer and intermediate type videos as
well.

* There are still a few asciidoc parsing issues that we're working on
- if you find anything that's weird please report it at our issue
tracker: https://github.com/github/gitscm-next/issues

Let me know if you run into anything or there are any features you
would like to see.  Also, be sure to thank Jason Long for doing all
the design for the site, including the new logo
(https://github.com/blackant).

Scott

[1] http://git-scm.com/downloads/logos
[2] http://git-scm.com/videos

Re: git-scm.com refresh

[Jakub Narebski]

Scott Chacon <schacon@gmail.com> writes:

> Hey everyone,
> 
> I just shipped a big update to the git-scm.com website, incorporating
> tons of feedback I've gotten on the site, especially from new users,
> over the years.  I think it will help new users to Git find the right
> installer and get up and running easier.  I have other ideas of things
> to add to it in the future, but I think this is much better than the
> site that has served us well for a few years now.
> 
> Some other interesting things to note:
> 
> * There is now permanent man page hosting here, for example:
> http://git-scm.com/docs/git-fsck.  You can also reference any older
> version of any command: http://git-scm.com/docs/git-fsck/1.5.5

That's very good.  Thank you very much for giving home to git manpages
online.

It would be nice for those manpages to have the title of page to be
set appropriately, e.g. for http://git-scm.com/docs/git-bisect to have
"git-bisect(1)" or "git-bisect(1) Manual Page", or even perhaps
"git-bisect(1) Manual Page - Find by binary search the change that
introduced a bug" instead of just "Git".

> 
> * We designed a new logo[1] - there are multiple variations available
> for download on the site under the most permissive CC license for any
> use.

IMVHO it is too similar to Bazaar logo:

  http://bazaar.canonical.com/bzricons/bazaar-logo.png

I like the [---] git logo, but I guess it is a bit cryptic.
           [+++]


[...]
> Let me know if you run into anything or there are any features you
> would like to see.

In my ancient 10-years old web browser (Mozilla 1.17.2, Linux) the new
layout is seriously broken (misaligned), and much less readable than
the old one (BTW. could you keep the old one, perhaps only the front
page, for comparison?).  Also the font size is too small.

-- 
Jakub Narebski

Re: git-scm.com refresh

[Junio C Hamano]

Scott Chacon <schacon@gmail.com> writes:

> Hey everyone,
>
> I just shipped a big update to the git-scm.com website,...

Thanks.  The Reference Manual area lists "apply" in a very funny place.
It should go together with "diff", whichever section you decide to put
"diff" in.  As "diff" is listed in "Basic Snapshotting", and it will not
be able to achieve that without being able to apply its output back to the
working tree or to the index, I would suggest moving "apply" to the
section as well.

I am fairly happy about the look of the new site except for a few things
;-).

It seems that you are trying to advocate "staging area" as some sort of
official term.  I think "it is like a staging area" is a good phrase to
use when answering "what is the index?", but I think repeating it million
times without telling the casual readers what its official name is is
counterproductive.  Don't do that.  It will confuse these same people when
they start reading manuals.

Re: git-scm.com refresh

[Andrew Sayers]

I had a poke round the site looking for trouble - here's what I found:

I'm using Linux, but for some reason the front page offers me downloads
for Mac.  When I click on "Mac GUIs", I am taken to a sensible URL for
Macs[1] but the button at the top says "Only show GUIs for my own OS
(Windows)".  I'm not sure how the detection works, but I have Javascript
disabled and the following user agent string:
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.11 (KHTML, like Gecko)
Chrome/17.0.963.56 Safari/535.11
Automatically guessing the user's OS is a good way of reducing interface
complexity, but for example the Firefox homepage[2] shows Windows, Linux
and Mac OS buttons if it can't guess.  This probably also helps Google
index their site, as GoogleBot can follow links to all the OS-specific
download pages.

The "about" section doesn't work in JS-disabled browsers - I always see
the "branching and merging" page no matter what I click on.  Again, this
means GoogleBot most likely won't index the other pages.

Not a bug, but a little tip - while investigating the issue on the
"about" page, I noticed that all the links had href="#".  You might want
to consider using href="#some-unique-identifier" so when you click round
the site with a JS-enabled browser and notice a "#" in the URL, you can
identify which click handler(s) failed.

Probably another non-JS browser issue, although not one that will bother
Google: the "book" section in the documentation page[3] has the first
"book cover" block protruding way into the left column, with all its
text mirrored.

Not a bug but a feature request: in the actual book pages, could you put
the prev/next links at the top as well as the bottom?  If I read through
the book, then come back a few weeks later looking for one of the pages,
it's much quicker to click through links at the top without needing to
scroll or move the mouse.

These bugs are relatively minor - the new site looks great overall.

	- Andrew

[1] http://git-scm.com/download/gui/mac
[2] http://www.mozilla.org/en-US/firefox/new/
[3] http://git-scm.com/documentation

Re: git-scm.com refresh

[Felipe Contreras]

Hi,

On Sat, May 5, 2012 at 1:29 AM, Scott Chacon <schacon@gmail.com> wrote:
> * We designed a new logo[1] - there are multiple variations available
> for download on the site under the most permissive CC license for any
> use.

I don't like it. I don't see how it can possibly be related to git in
any way. There are no plus and minus anywhere, nor green :)

But anyway, if you are going to use such a logo, perhaps you should
choose a less saturated red, or even green would be better, and use
the black version as the page favicon (like in github).

See how bad it looks in my browser:
http://felipec.org/git-scm-screenshot.png

Also, the hugely saturated red on the rest of the page seems
offsetting. A less saturated red often looks bad, but a less saturated
green not so much.

And probably rotate the logo it 180 degrees; it looks like development
is going down?

Other than that I think it's great :)

Thanks!

-- 
Felipe Contreras

Re: git-scm.com refresh

[Philip Oakley]

From: "Scott Chacon" <schacon@gmail.com>Sent: Saturday, May 05, 2012 12:29 
AM
> Hey everyone,
>
> I just shipped a big update to the git-scm.com website, incorporating
> tons of feedback I've gotten on the site, especially from new users,
> over the years.  I think it will help new users to Git find the right
> installer and get up and running easier.  I have other ideas of things
> to add to it in the future, but I think this is much better than the
> site that has served us well for a few years now.
>

I liked the groupings of the commands on the doc/reference page 
http://git-scm.com/docs (plural).
I felt they were reasonably grouped and relatively inviting to explore.

The visual cheatsheet looks interesting and informative, though wasn't what 
I was expecting from its title - perhaps "interactive cheatsheet"?
[If they did a composite with all the cheats in cascade it'd make a good 
printout]

Philip Oakley

Re: git-scm.com refresh

[Felipe Contreras]

On Sat, May 5, 2012 at 3:31 AM, Junio C Hamano <gitster@pobox.com> wrote:

> It seems that you are trying to advocate "staging area" as some sort of
> official term.  I think "it is like a staging area" is a good phrase to
> use when answering "what is the index?", but I think repeating it million
> times without telling the casual readers what its official name is is
> counterproductive.  Don't do that.  It will confuse these same people when
> they start reading manuals.

I think keeping the name 'index' is what is counter-productive. I
think most users don't even need to hear the term 'index' in order to
interact with the staging area in common operations, so they won't ask
"what is the index?".

-- 
Felipe Contreras

Re: git-scm.com refresh

[Scott Chacon]

Hey,

On Fri, May 4, 2012 at 5:26 PM, Jakub Narebski <jnareb@gmail.com> wrote:
>> version of any command: http://git-scm.com/docs/git-fsck/1.5.5
>
> That's very good.  Thank you very much for giving home to git manpages
> online.
>
> It would be nice for those manpages to have the title of page to be
> set appropriately, e.g. for http://git-scm.com/docs/git-bisect to have
> "git-bisect(1)" or "git-bisect(1) Manual Page", or even perhaps
> "git-bisect(1) Manual Page - Find by binary search the change that
> introduced a bug" instead of just "Git".

Good catch - I'm pushing that out in a minute.

>> * We designed a new logo[1] - there are multiple variations available
>> for download on the site under the most permissive CC license for any
>> use.
>
> IMVHO it is too similar to Bazaar logo:
>
>  http://bazaar.canonical.com/bzricons/bazaar-logo.png
>
> I like the [---] git logo, but I guess it is a bit cryptic.
>           [+++]
>

I was actually concerned with the same thing, but a) not that many
people are familiar with the Bzr logo and b) when I actually look at
the Bzr logo I don't really see that much in common.  It was done by
someone totally unfamiliar with that logo and although I can still see
similarities, I think it's a good, clean logo that would be easily
recognizable and much more versatile than what we have been using so I
decided to stick with it.


>> Let me know if you run into anything or there are any features you
>> would like to see.
>
> In my ancient 10-years old web browser (Mozilla 1.17.2, Linux) the new
> layout is seriously broken (misaligned), and much less readable than
> the old one (BTW. could you keep the old one, perhaps only the front
> page, for comparison?).  Also the font size is too small.

I have to assume that just about any modern site looks pretty awful to
you.  I honestly don't know what to do about this - I can't even test
it really.  I am aware since the launch that a number of people have
issues with JS being turned off, which I'm working on, but there's not
a lot I can do for browsers like that and I'm not sure what the point
would be anyhow.  People with browsers like that don't need anything
on this site as far as I can think of.  It targets people that don't
know Git and possibly don't know version control and are trying to
figure it out.

I'll try to make it better, but it would be simpler if you could fix
it and send me a pull request since I have no other way to see what
you're seeing with tech that out of date.

Scott

Re: git-scm.com refresh

[Scott Chacon]

Hey,

On Fri, May 4, 2012 at 6:31 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
> Thanks.  The Reference Manual area lists "apply" in a very funny place.
> It should go together with "diff", whichever section you decide to put
> "diff" in.  As "diff" is listed in "Basic Snapshotting", and it will not
> be able to achieve that without being able to apply its output back to the
> working tree or to the index, I would suggest moving "apply" to the
> section as well.

I have to disagree.  You are thinking of 'apply' from an internals
perspective I have to assume, because I use 'diff' every single day
for all sorts of stuff ("what is modified and unstaged?", "what is
modified and staged?", "what is different between these two branches?"
etc) where I can't think of a single time I've ever used 'apply'.  In
fact, even the times when I have needed to apply a patch generated
from 'diff' I used 'patch -p1' because I know it better.  I, and most
people I would guess, almost never use 'diff' to generate patch files,
we use it to see what has changed before committing or things like
that - in general usage, it's more like an advanced 'status' honestly.

> I am fairly happy about the look of the new site except for a few things
> ;-).
>
> It seems that you are trying to advocate "staging area" as some sort of
> official term.  I think "it is like a staging area" is a good phrase to
> use when answering "what is the index?", but I think repeating it million
> times without telling the casual readers what its official name is is
> counterproductive.  Don't do that.  It will confuse these same people when
> they start reading manuals.

I'm not really trying to advocate it as much as using terminology that
is already quite popular.  It's true that it's not what is used in the
man pages, but neither is 'index' used consistently - there is 'cache'
too, in addition to 'index' having two meanings - packfile and cache.
I'm open to making things clearer, but I just don't think that
changing the terminology to something more technical and vague would
be overall less confusing to people.

That said, in most places I use phrases like 'Git has something called
the "staging area" or "index"' letting people know that there are
multiple phrases for it and what it's technical term tends to be.  So
your "without telling the casual readers what its official name is" is
generally not true - I do try to do that too.

Scott

Re: git-scm.com refresh

[Josh Juran]

On May 4, 2012, at 5:26 PM, Jakub Narebski wrote:

> Scott Chacon <schacon@gmail.com> writes:
>
>> * We designed a new logo[1] - there are multiple variations available
>> for download on the site under the most permissive CC license for any
>> use.
>
> IMVHO it is too similar to Bazaar logo:
>
>   http://bazaar.canonical.com/bzricons/bazaar-logo.png

That's nothing compared to the similarity between the Bazaar logo and  
the MacCVS Pro logo:

http://www.maccvs.org/images/roadsign_small.gif

Josh

Re: git-scm.com refresh

[Neal Kreitzinger]

On 5/4/2012 6:29 PM, Scott Chacon wrote:
>
> I just shipped a big update to the git-scm.com website
>
I'll miss Torvald the Troll (http://torvald.gjovaag.com/)showing the 
trees of thor's woods (tor's wald) who's boss.  :(

> * There is now permanent man page hosting here

Thanks for rescuing the man!  I suppose you also had help from the ents. 
  Thanks to them too.  :)

> Let me know if you run into anything or there are any features you
> would like to see.

The new homepage looks too slick.  The hacky look of the old one was 
more in keeping with cli git.  This is git.git, not github.  ;)

v/r,
neal

Re: git-scm.com refresh

[Junio C Hamano]

Scott Chacon <schacon@gmail.com> writes:

>> As "diff" is listed in "Basic Snapshotting", and it will not
>> be able to achieve that without being able to apply its output back to the
>> working tree or to the index, I would suggest moving "apply" to the
>> section as well.
>
> I have to disagree.  You are thinking of 'apply' from an internals
> perspective I have to assume, because I use 'diff' every single day
> for all sorts of stuff ("what is modified and unstaged?", "what is
> modified and staged?", "what is different between these two branches?"
> etc) ...

The other day when I was surfing the 'net, I found a blog that was
complaining about Git UI.  Some of the things were worth listening to, but
there was one item I really had to scratch my head where the misconception
behind the complaint came from.  I am typing from memory without bothering
to go back to the site to quote, but the complaint essentially was:

        Getting a patch is easy with "git diff", but to apply it you need
        to make it an email and feed it to "git am"???  That's crazy.

Of course it *is* crazy, if that were the case. I was wondering why the
obvious "patch" (or "git apply") did not get into the mind of the author,
and I think I now know why.

If the owner of the site that people call "git's home page" does not care
about those who take diffs and apply them as patches, and thinks "git
apply" as a mere implementation detail of "git am", it is understandable
that such a misconception is spread widely to harm users without getting
corrected. Who knows other Git fanboys are spreading misinformation in a
similar way. Sigh...

> ... where I can't think of a single time I've ever used 'apply'.  In
> fact, even the times when I have needed to apply a patch generated
> from 'diff' I used 'patch -p1' because I know it better.

As you are supposed to be one of the top-level Git Teachers, I wish you
knew better.  Here is a free Git lesson.  Consider "git apply" as

    a better version of "patch" that knows how to work better with Git by
    understanding rename and binary patches, and allows them to be applied
    to the working tree and the index (the latter is most useful when the
    patch contains new files)

and teach it as such.

"diff" pairs with "apply", and "format-patch" pairs with "am".

I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
apply", if you think that would make the above pairing more obvious.  Many
computer users know what "patch" does already even they have never used
any SCM.

[Footnote]

Re: git-scm.com refresh

[Felipe Contreras]

On Sun, May 6, 2012 at 3:39 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Scott Chacon <schacon@gmail.com> writes:
>
>>> As "diff" is listed in "Basic Snapshotting", and it will not
>>> be able to achieve that without being able to apply its output back to the
>>> working tree or to the index, I would suggest moving "apply" to the
>>> section as well.
>>
>> I have to disagree.  You are thinking of 'apply' from an internals
>> perspective I have to assume, because I use 'diff' every single day
>> for all sorts of stuff ("what is modified and unstaged?", "what is
>> modified and staged?", "what is different between these two branches?"
>> etc) ...
>
> The other day when I was surfing the 'net, I found a blog that was
> complaining about Git UI.  Some of the things were worth listening to, but
> there was one item I really had to scratch my head where the misconception
> behind the complaint came from.  I am typing from memory without bothering
> to go back to the site to quote, but the complaint essentially was:
>
>        Getting a patch is easy with "git diff", but to apply it you need
>        to make it an email and feed it to "git am"???  That's crazy.
>
> Of course it *is* crazy, if that were the case. I was wondering why the
> obvious "patch" (or "git apply") did not get into the mind of the author,
> and I think I now know why.
>
> If the owner of the site that people call "git's home page" does not care
> about those who take diffs and apply them as patches, and thinks "git
> apply" as a mere implementation detail of "git am", it is understandable
> that such a misconception is spread widely to harm users without getting
> corrected. Who knows other Git fanboys are spreading misinformation in a
> similar way. Sigh...

So you think moving "git apply" to another section there is going to
fix the problem? And what is the problem? That some random guy in a
blog post thinks it's crazy to use 'git format-patch' and 'git am'? I
don't think that's a problem worth worrying about, and I don't think
it's crazy.

Who cares if people don't know about "git apply"? I too have used it
very rarely, and almost every time I gave up. It's not really useful
because if there are conflicts (and there usually are), the thing just
fails, and 'git apply --reject' (horrible name BTW; apply and reject a
patch?) is too cumbersome. It's much easier to just avoid it.

>> ... where I can't think of a single time I've ever used 'apply'.  In
>> fact, even the times when I have needed to apply a patch generated
>> from 'diff' I used 'patch -p1' because I know it better.
>
> As you are supposed to be one of the top-level Git Teachers, I wish you
> knew better.  Here is a free Git lesson.  Consider "git apply" as
>
>    a better version of "patch" that knows how to work better with Git by
>    understanding rename and binary patches, and allows them to be applied
>    to the working tree and the index (the latter is most useful when the
>    patch contains new files)
>
> and teach it as such.

It's still basically useless.

> "diff" pairs with "apply", and "format-patch" pairs with "am".

A contributor uses 'format-patch' often, a maintainer uses 'am' often,
but who uses 'apply'? Nobody. Who uses 'diff'? Everybody.

'git diff' is *essential* to see what's going on with the staging
area, and the working directory.

When do you actually *need* 'git apply'? Never; you can always achieve
the same in different ways probably much easier.

> I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
> apply", if you think that would make the above pairing more obvious.  Many
> computer users know what "patch" does already even they have never used
> any SCM.

'git patch' would certainly make more sense, but even more would be to
make it actually usable so mergetool could be used in case of
conflicts, or even just having the typical conflict markers.

But even with all that, it still wouldn't be as essential as 'git diff'.

Cheers.

-- 
Felipe Contreras

Re: git-scm.com refresh

[Scott Chacon]

On Sat, May 5, 2012 at 6:39 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Scott Chacon <schacon@gmail.com> writes:
>
>>> As "diff" is listed in "Basic Snapshotting", and it will not
>>> be able to achieve that without being able to apply its output back to the
>>> working tree or to the index, I would suggest moving "apply" to the
>>> section as well.
>>
>> I have to disagree.  You are thinking of 'apply' from an internals
>> perspective I have to assume, because I use 'diff' every single day
>> for all sorts of stuff ("what is modified and unstaged?", "what is
>> modified and staged?", "what is different between these two branches?"
>> etc) ...
>
> The other day when I was surfing the 'net, I found a blog that was
> complaining about Git UI.  Some of the things were worth listening to, but
> there was one item I really had to scratch my head where the misconception
> behind the complaint came from.  I am typing from memory without bothering
> to go back to the site to quote, but the complaint essentially was:
>
>        Getting a patch is easy with "git diff", but to apply it you need
>        to make it an email and feed it to "git am"???  That's crazy.
>
> Of course it *is* crazy, if that were the case. I was wondering why the
> obvious "patch" (or "git apply") did not get into the mind of the author,
> and I think I now know why.

You think he doesn't know about 'git apply' because I'm not listing it
under Basic Snapshotting in the site I put live yesterday?  Or because
I'm not teaching that?  That makes no sense, I don't understand why
you think I'm to blame for this guy not knowing that.  If anything,
this new grouping will help that, since it clearly puts 'apply' under
a section explicitly labeled 'Patching'.  It doesn't belong in "Basic
Snapshotting" because that's not at all what it's used for and it
doesn't make sense to put 'diff' under 'Patching' because that's not
it's primary use case - it is mainly used to see what differences are
in various cases, not to create patch files.

> If the owner of the site that people call "git's home page" does not care
> about those who take diffs and apply them as patches, and thinks "git
> apply" as a mere implementation detail of "git am", it is understandable
> that such a misconception is spread widely to harm users without getting
> corrected. Who knows other Git fanboys are spreading misinformation in a
> similar way. Sigh...

For one, it's not that I don't care, it's that I don't think that how
you're considering the problem set here is common.  I'm trying to make
Git a little bit easier to approach by grouping many of the commands
into groups by the problems they are primarily used to address.  If
you can argue that 'diff' is *primarily* used to create patch files
for 'apply' to consume, then I would be happy to argue that, but
that's not what you're saying.  You're ignoring my argument that I
believe that 'diff' is used primarily for another use case and that
that use case is closer to 'status' then to 'apply'.

>> ... where I can't think of a single time I've ever used 'apply'.  In
>> fact, even the times when I have needed to apply a patch generated
>> from 'diff' I used 'patch -p1' because I know it better.
>
> As you are supposed to be one of the top-level Git Teachers, I wish you
> knew better.  Here is a free Git lesson.  Consider "git apply" as
>
>    a better version of "patch" that knows how to work better with Git by
>    understanding rename and binary patches, and allows them to be applied
>    to the working tree and the index (the latter is most useful when the
>    patch contains new files)
>
> and teach it as such.

There is absolutely no reason to be this condescending.  You can read
a similar description of 'apply' in the context of applying patches
produced by 'diff' in my book which is CC licensed and now makes up a
large part of the git-scm.com site here:

http://git-scm.com/book/en/Distributed-Git-Maintaining-a-Project#Applying-Patches-from-E-mail

It is also one of the top results when searching for 'apply' on the
site and it is cross-linked from the git-apply manpage in the sidebar.
 It's difficult for me to see how this can be made more clear by me on
this site.

>
> "diff" pairs with "apply", and "format-patch" pairs with "am".
>

If you read on through the next paragraph in that book you will see
this covered as well, as a slightly different use case where the
contributor used 'format-patch' instead.

Or, if you wish, you can read it in German, Japanese, French, Dutch,
Russian, Chinese or Spanish - the languages that have fully translated
my book and are also available on the site.  It's difficult to see why
you think I'm making this perceived issue worse.

> I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
> apply", if you think that would make the above pairing more obvious.  Many
> computer users know what "patch" does already even they have never used
> any SCM.

I don't think this is a good idea at all and I've never advocated
this.  If people know what GNU 'patch' is they can use that, if people
glance at the new git-scm.com site they should be able to easily see
'git apply'  listed under other patch-y workflow tools.  What would be
far easier would be for me to simply list 'diff' under both sections,
since what we're really struggling with is the multiple use cases of
the 'diff' command.  I think I'll just do that, OK?

Scott

Re: git-scm.com refresh

[Neal Kreitzinger]

On 5/4/2012 6:29 PM, Scott Chacon wrote:
>
> I just shipped a big update to the git-scm.com website...
>
Thanks for the cool website, old and new!  :)

> * There is now permanent man page hosting here, for example:
> http://git-scm.com/docs/git-fsck.  You can also reference any older
> version of any command: http://git-scm.com/docs/git-fsck/1.5.5
>
IMO, I think the reference manual before the kernel.org crash was the 
best.  Back then, you first got a list of all the versions and you 
picked your version.  If I'm on version x I want to click on version x 
one time for the entire refman, not for every manpage.

I prefer the git.git make doc version of the html.  If you could have a 
'classic' view of the reference manual that would be great.  I'm not an 
expert on the make doc technologies, but if your version is harder to 
get working then a classic view would enable you to quickly and reliably 
publish updates while ironing out the enhanced version.

Also, the new format has *way* too much whitespace on the sides for the 
manpages.  (Progit also has too much whitespace -- was it like that 
before?)  The manpages are long enough without double column width in a 
single column.  ;)  The related topics is interesting.  I think this 
hybrid reference manual format should be called 'enhanced' or something. 
  I think its important to keep the official git reference manual 
clearly distinguished from supplemental material because some of the 
supplements are not correct (ie, [a]progit merge=ours).  I think the new 
hybrid format disguised as the reference manual will cause the newsgroup 
to get alot of questions about supplemental material confused with the 
reference manual pages.  They probably already spend too much time 
correcting my bum scoop posts as it is.  ;)

I'm not a website expert, but an option to pick a stylesheet that has a 
main theme color of blue, green, etc., as opposed to red-orange that 
would a big plus in keeping with the open source concept.  I'm not a 
visual brain scientist, but I think my aversion to staring at a 
red-orange website all the time has something to do with why walls are 
not normally painted red-orange either.  ;)

> * There are still a few asciidoc parsing issues that we're working on
> - if you find anything that's weird please report it at our issue
> tracker: https://github.com/github/gitscm-next/issues
>
git-rebase manpage is pretty hosed.  (when i tried to report on github 
it wanted me to signup.)

Footnotes:
a.  http://git-scm.com/book/en/Customizing-Git-Git-Attributes,
http://comments.gmane.org/gmane.comp.version-control.git/192798

v/r,
neal

Re: git-scm.com refresh

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com> Sent: Sunday, May 06, 2012 2:39
AM
 > Scott Chacon <schacon@gmail.com> writes:
>
>>> As "diff" is listed in "Basic Snapshotting", and it will not
>>> be able to achieve that without being able to apply its output back to
>>> the
>>> working tree or to the index, I would suggest moving "apply" to the
>>> section as well.
>>
>> I have to disagree.  You are thinking of 'apply' from an internals
>> perspective I have to assume, because I use 'diff' every single day
>> for all sorts of stuff ("what is modified and unstaged?", "what is
>> modified and staged?", "what is different between these two branches?"
>> etc) ...
>
> The other day when I was surfing the 'net, I found a blog that was
> complaining about Git UI.  Some of the things were worth listening to, but
> there was one item I really had to scratch my head where the misconception
> behind the complaint came from.  I am typing from memory without bothering
> to go back to the site to quote, but the complaint essentially was:
>
>        Getting a patch is easy with "git diff", but to apply it you need
>        to make it an email and feed it to "git am"???  That's crazy.
>
<snip>

> "diff" pairs with "apply", and "format-patch" pairs with "am".
>
> I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
> apply", if you think that would make the above pairing more obvious.  Many
> computer users know what "patch" does already even they have never used
> any SCM.
>

Part of the problem is that the `git diff` man page [1] doesn't actively
tell the user that its result will be in a patch format, and that such a
patch can be `apply`ed. There are only 5 uses of 'apply' buried in the body
text, never as a command, as if they are special cases. There is a section
on the -p option, again it feels like it is a special case.

The "--patch" option in [1] is corrupted(?) relative to my desktop in that 
it
misses the "(This is the default.)" ending (which most readers skip over 
when
speed reading).

The normal case of `git diff` for most users is simply as an extended 'what
changed' git status.

The `git apply` page [2] does say its about a diff:
    "DESCRIPTION - Reads the supplied diff output (i.e. "a patch") and
    applies it to files."
so it reads ok in reverse.

Perhaps for `git diff` man page
    NAME - git-diff - Show changes/, usually as a patch,/ between commits,
    commit and working tree, etc.

Then
    DESCRIPTION - Show changes ...two files on disk.
     /You can implement a diff patch by using git-apply(1)./

The main point is that the new user is probably unaware of many of the
conventions others take for granted. This gives them 'a clue' about `apply`.

Philip

[1] http://git-scm.com/docs/git-diff
[2] http://git-scm.com/docs/git-apply.html

Re: git-scm.com refresh

[Matthieu Moy]

Scott Chacon <schacon@gmail.com> writes:

> * There is now permanent man page hosting here, for example:
> http://git-scm.com/docs/git-fsck.  You can also reference any older
> version of any command: http://git-scm.com/docs/git-fsck/1.5.5

Great.

Could somebody with kernel.org access set up redirects from
http://www.kernel.org/pub/software/scm/git/docs/* to these pages? There
are still tons of links pointing to kernel.org's 404 errors ...

Some time ago, you mentionned some plans to host a wiki on git-scm.com,
is it still the case? I noticed that the kernel.org wiki was back since
a few days, so the question is different now.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: git-scm.com refresh

[Scott Chacon]

Hey,

On Sun, May 6, 2012 at 4:04 AM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Great.
>
> Could somebody with kernel.org access set up redirects from
> http://www.kernel.org/pub/software/scm/git/docs/* to these pages? There
> are still tons of links pointing to kernel.org's 404 errors ...
>
> Some time ago, you mentionned some plans to host a wiki on git-scm.com,
> is it still the case? I noticed that the kernel.org wiki was back since
> a few days, so the question is different now.

I am still planning on doing this.  Since it took them several months
to get back and as you point out, while they're down links go bad all
over the place, I am planning on owning the wiki so we can have more
control over it.  I also want to make it easier to contribute to it
and have it be Git backed.  This is a project on my to-do list.

Scott

Re: git-scm.com refresh

[Christian Couder]

Hi Scott,

On Sat, May 5, 2012 at 1:29 AM, Scott Chacon <schacon@gmail.com> wrote:
> Hey everyone,
>
> I just shipped a big update to the git-scm.com website, incorporating
> tons of feedback I've gotten on the site, especially from new users,
> over the years.  I think it will help new users to Git find the right
> installer and get up and running easier.  I have other ideas of things
> to add to it in the future, but I think this is much better than the
> site that has served us well for a few years now.
>
> Some other interesting things to note:
>
> * There is now permanent man page hosting here, for example:
> http://git-scm.com/docs/git-fsck.  You can also reference any older
> version of any command: http://git-scm.com/docs/git-fsck/1.5.5

Great!

> * We designed a new logo[1] - there are multiple variations available
> for download on the site under the most permissive CC license for any
> use.

I prefer the old one.

> * The Pro Git book (and all of it's translations) has been directly
> incorporated into the site and has better permalinks and section
> anchors.  progit.org will soon be redirecting to git-scm.com.

It's good to have it integrated but on the other hand I don't like the
boxes on the left side of each page about the book.
It just looks to me like an (annoying) ad.

> * Matthew McCullough has started a video series[2] for newbies and
> will continue to do more developer and intermediate type videos as
> well.

Nice.

> * There are still a few asciidoc parsing issues that we're working on
> - if you find anything that's weird please report it at our issue
> tracker: https://github.com/github/gitscm-next/issues
>
> Let me know if you run into anything or there are any features you
> would like to see.

I would like the page about the git authors to be back.

Thanks,
Christian.

Re: git-scm.com refresh

[A Large Angry SCM]

On 05/04/2012 07:29 PM, Scott Chacon wrote:
> Hey everyone,
>
> I just shipped a big update to the git-scm.com website, incorporating
> tons of feedback I've gotten on the site, especially from new users,
> over the years.  I think it will help new users to Git find the right
> installer and get up and running easier.  I have other ideas of things
> to add to it in the future, but I think this is much better than the
> site that has served us well for a few years now.

[...]

I was looking over the updated website and what follows are my initial 
impressions:

1) I like the old logo much better.

2) I notice that GitHub is NOT listed as a company or project using git 
on the main page. What SCM does GitHub use? :-O

3) On the About -> Small and Fast Page: you show a comparison to Git and 
Git* for the clone operation but there is no explanation of how Git and 
Git* differ.

4) It's 2 clicks to get to a category view of the man pages: I think 
that's 1 too many.

5) I would like to see a page that lists all of the documentation in the 
core distribution in one place. A good place for this would be somewhere 
near the top of the category view page.

6) The documentation pages should let the user decide with one click 
which version of the documentation set they wish to view instead of 
having to do it for every page.

7) A help topic on the category view page about determining which 
version of the documentation matches the user's installed version of Git 
would be useful.

Re: git-scm.com refresh

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com> Sent: Sunday, May 06, 2012 2:39
>
>> "diff" pairs with "apply", and "format-patch" pairs with "am".
>>
>> I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
>> apply", if you think that would make the above pairing more obvious.  Many
>> computer users know what "patch" does already even they have never used
>> any SCM.
>
> Part of the problem is that the `git diff` man page [1] doesn't actively
> tell the user that its result will be in a patch format, and that such a
> patch can be `apply`ed. There are only 5 uses of 'apply' buried in the body
> text, never as a command, as if they are special cases. There is a section
> on the -p option, again it feels like it is a special case.

Sounds like you spotted a good set of places in the documentation that
need to be updated.

> The normal case of `git diff` for most users is simply as an extended 'what
> changed' git status.

I think that use of "diff" is listed in "Inspection and Comparison"
section, and I fully agree and is happy to see "diff" there as well.  Of
course, I wouldn't suggest "apply" to go next to that use of "diff".

But what I have been discussing was the use of "diff" in the "Basic
Snapshotting" section.  I actually very often use "diff" paired with
"apply" for my own work, not when working to integrate others' work.  

Also I do not think anybody would use "apply" to accept patches (that is
what "am" is for), so listing it in "Email" section is doubly wrong.  If
for some reason the command Reference does not want to have "apply" next
to "diff" listed in "Basic Snapshotting", I do not think there is any
category on that page for the command to belong to.

The above two were the primary things that triggered my reaction.

When reshaping a multi-commit series, "git diff $rev1 $rev2 >P.diff"
followed by "git apply <P.diff" (either with or without editing P.diff in
between) is sometimes a more versatile and even more natural solution than
repeated use of "rebase -i" is, depending on what kind of reshaping
I want to do.

For example, after an exploratory development session, I often end up
with something like this (time flows from top to bottom):

	update A
        update D
        refactor and modify B
	update E
        refactor and modify C

and then I realize that the refactoring I needed to give to B and C are
the similar kind, and is better done as a single step early in the
series.  This will involve splitting two "refactor and modify" commits
into four, reorder and squash in different combinations.  It often is the
most convenient to

	git checkout ":/update A"
        git diff ":/update D" ":/refactor and modify B" | git apply
        git add -p ;# only keep the 'refactor' bit
        git checkout . ;# and lose the 'modify' part
        git diff ":/update E" ":/refactor and modify C" | git apply
        git add -p ;# only keep the 'refactor' bit
        git checkout . ;# and lose the 'modify' part
	git commit -c ':/refactor and modify C'

when rebuilding 'refactor B and C' on top of 'update A'.  Of course this
does not have to be "rebase" but picking only part of good infrastructure
change from totally unrelated branch.  A concrete example is the recent
index-v4 series started by a commit that borrowed a small part of older
jc/split-blob series to refactor a varint API, and the diff to apply pipe
with editing (because the API needed to be cleaned up for the index-v4
work) was how a part of change was extracted from older branch (later the
jc/split-blob was rewritten to base it on the updated varint API that
was cleaned up for the index-v4 series).

In such a workflow, the use of "diff" is very much "Basic snapshotting"
(which is the category head I was referring to).  It is used as a mechaism
to take a snapshot, and not as a measure for "Inspection and Comparison".

And the way to replay that basic snapshot to the working tree is "git
apply".  Without the matching pair, "git diff" does not serve well as a
"Basic snapshotting" feature.

I do not think Scott is ignorant of or unsympathetic to such a use case
(after all, he mentioned use of GNU patch on "git diff" output, so he must
use "take a diff to stash away some change, then replay it to the working
tree" workflow, even if much less often than I do.  Perhaps he personally
uses it not so often and its usefulness escaped him).

It is a different topic if it makes sense to enhance "rebase -i" to
support "split two, shuffle and squash in a different way".  I do not
think of a good UI for such an operation offhand.

Re: git-scm.com refresh

[Ævar Arnfjörð Bjarmason]

On Mon, May 7, 2012 at 6:18 AM, Christian Couder
<christian.couder@gmail.com> wrote:
> I would like the page about the git authors to be back.

I'd also like that back, it was the best done author page in any
project I've seen because it was automatically generated and regularly
updated.

Re: git-scm.com refresh

[Matthieu Moy]

Scott Chacon <schacon@gmail.com> writes:

> Let me know if you run into anything or there are any features you
> would like to see.

On http://git-scm.com/community one can see how to post and how to read
the archives of the mailing-list, but not how to subscribe. I guess you
need to add a link to http://vger.kernel.org/vger-lists.html#git

Typing "git@vger.kernel.org" in the search box gives no result. Probably
the search box should suggest searching an external search engine (e.g.
google, restricted to git-scm.org)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: git-scm.com refresh

[Antonio Ospite]

Scott Chacon <schacon <at> gmail.com> writes:

> 
> Hey everyone,
> 
> I just shipped a big update to the git-scm.com website, incorporating
> tons of feedback I've gotten on the site, especially from new users,
> over the years.  I think it will help new users to Git find the right
> installer and get up and running easier.  I have other ideas of things
> to add to it in the future, but I think this is much better than the
> site that has served us well for a few years now.
> 
> Some other interesting things to note:
> 
> * There is now permanent man page hosting here, for example:
> http://git-scm.com/docs/git-fsck.  You can also reference any older
> version of any command: http://git-scm.com/docs/git-fsck/1.5.5
>

Some pages are not displayed correctly:
http://git-scm.com/docs/git-rebase for instance gets corrupted at some point.

> * We designed a new logo[1] - there are multiple variations available
> for download on the site under the most permissive CC license for any
> use.
> 

FWIW I also miss the + and - in the logo but I think I will survive :)

Thanks,
   Antonio Ospite
   http://ao2.it

Re: git-scm.com refresh

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> But what I have been discussing was the use of "diff" in the "Basic
> Snapshotting" section.  I actually very often use "diff" paired with
> "apply" for my own work, not when working to integrate others' work.  
>
> Also I do not think anybody would use "apply" to accept patches (that is
> what "am" is for), so listing it in "Email" section is doubly wrong.  If
> for some reason the command Reference does not want to have "apply" next
> to "diff" listed in "Basic Snapshotting", I do not think there is any
> category on that page for the command to belong to.
>
> The above two were the primary things that triggered my reaction.
>
> When reshaping a multi-commit series, "git diff $rev1 $rev2 >P.diff"
> followed by "git apply <P.diff" (either with or without editing P.diff in
> between) is sometimes a more versatile and even more natural solution than
> repeated use of "rebase -i" is, depending on what kind of reshaping
> I want to do.
>
> For example,...  Of course this
> does not have to be "rebase" but picking only part of good infrastructure
> change from totally unrelated branch.  A concrete example is ...

I encountered another example yesterday after sending the above message
[*1*].  I was fixing one small bug, and had a commit that updates code and
adds a test vector.  It is a single commit on top of the current branch
tip, which allegedly as a buggy code.

Then I wanted to double check that the bug really existed before the fix.

	git checkout HEAD^
        git show @{-1} t/ | git apply
        make test

The above gave me the pristine state plus only new tests to let me see the
old code was indeed buggy.

I also hit another example use case yesterday.

A series was posted that was a fix that should go to "maint" but the
pathces were based on "master".  The usual "git am -s3c" on "maint" didn't
exactly grok the series, as there were semantic conflicts (a new field was
added between "maint" and "master" to the structure the patch touches to
add yet another field).  So here is what I had to do:

	git checkout -b jk/status-porcelain-z-b master
        git am -s ./+mbox
        git checkout -b jk/maint-status-porcelain-z-b
        git rebase --onto maint master
        ... fix conflicts, resolving semantic conflicts along the way

	git checkout -B jk/status-porcelain-z-b master
        ... at this point, jk/status-porcelain-z-b@{1} is what the series
        ... applied to 'master' as the poster intended.
        git merge jk/maint-status-porcelain-z-b
        ... conflicts, which is more or less a squashed version of the
        ... mess I dealt with when I rebased the original to maint
        ... rerere will replay the mechanical part.
	... look at the conflict in "git diff" (no other
	... arguments) and making sure that it mostly makes sense.
	git add -u
        git diff
        git diff HEAD
        ... but the semantic conflict part is still missing, which
        ... can be eyeballed like this.
        git diff -R jk/status-porcelain-z-b@{1}
        ... then transport the remaining changes.
        git diff -R jk/status-porcelain-z-b@{1} | git apply --index
	... and then double check the result
        git diff HEAD

And I had exactly the same use case today for another series.

It turns out that "nobody uses apply while accepting patches" is not quite
true.  I do use "apply" while accepting patches.  But I do not use it on
"format-patch" output.  That is what "am" is for.

In any case, the latter part of the write-up above was done primarily
because I thought it would be illustrative for others who need to flip
commits (whether it comes in patch form, or you develop your own) between
multiple code bases.  As people say, just my two cents ;-)


[Footnote]
 
*1* I admit that I use "apply" so often that I do not have to think when
using it, and I realize use cases of it only during the course of the
usual work day, not during a theoretical "I do not think anybody uses 'git
apply' on 'git diff' output" discussion.

Re: git-scm.com refresh

[Andreas Schwab]

Junio C Hamano <gitster@pobox.com> writes:

> I encountered another example yesterday after sending the above message
> [*1*].  I was fixing one small bug, and had a commit that updates code and
> adds a test vector.  It is a single commit on top of the current branch
> tip, which allegedly as a buggy code.
>
> Then I wanted to double check that the bug really existed before the fix.
>
> 	git checkout HEAD^
>         git show @{-1} t/ | git apply

Alternative:
          git checkout @{-1} t/

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: git-scm.com refresh

[Junio C Hamano]

Andreas Schwab <schwab@linux-m68k.org> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> I encountered another example yesterday after sending the above message
>> [*1*].  I was fixing one small bug, and had a commit that updates code and
>> adds a test vector.  It is a single commit on top of the current branch
>> tip, which allegedly as a buggy code.
>>
>> Then I wanted to double check that the bug really existed before the fix.
>>
>> 	git checkout HEAD^
>>         git show @{-1} t/ | git apply
>
> Alternative:
>           git checkout @{-1} t/

True in this case, but that is usable when "diff @{-1}^ @{-1}" happens to
be the _only_ change to your current state, so it won't be a general
substitute for the "diff | apply" pipeline.

Re: git-scm.com refresh

[Heiko Voigt]

Hi,

On Mon, May 07, 2012 at 11:04:52PM +0200, Matthieu Moy wrote:
> Scott Chacon <schacon@gmail.com> writes:
> 
> > Let me know if you run into anything or there are any features you
> > would like to see.
> 
> On http://git-scm.com/community one can see how to post and how to read
> the archives of the mailing-list, but not how to subscribe. I guess you
> need to add a link to http://vger.kernel.org/vger-lists.html#git

One thing I noticed is that there is no link to the msysgit project for
the windows development under community. The only way you can find it is
under download when you look closely at the text when the download is
starting.

Could we add some information about msysgit for windows development on
the community page?

Maybe the same applies for other OS like the osx installer?

Cheers Heiko