is http://git-scm.com an *official* git-affiliated site?

is http://git-scm.com an *official* git-affiliated site?

[Robert P. J. Day]

  i ask WRT whether it should be up to date. i'm currently writing a
number of git-related wiki pages, and i want to link to whatever are
the canonical man pages for various git commands, but that site seems
a bit off.

  if one follows a link to get here:

https://git-scm.com/doc

there is another link to the "Reference Manual" that promises "The
official and comprehensive man pages that are included in the Git
package itself."

  but upon getting there:

https://git-scm.com/docs

it seems clear that that page doesn't come close to covering all of
the available git commands.

  as an example, there is a link "submodule" on that page, which does
indeed take one to the page https://git-scm.com/docs/git-submodule. so
far, so good.

  however, while there is no link for the "worktree" command, there
does in fact exist a similarly-named web page
https://git-scm.com/docs/git-worktree.

  finally, there is no reference to the git "subtree" command, either
as a link *or* as an existing web page
https://git-scm.com/docs/git-subtree. it all seems kind of arbitrary.

  is there an actual, canonical set of online web pages for all
current git commands one should use?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: is http://git-scm.com an *official* git-affiliated site?

[Duy Nguyen]

On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
>   i ask WRT whether it should be up to date. i'm currently writing a
> number of git-related wiki pages, and i want to link to whatever are
> the canonical man pages for various git commands,

I think this one is updated often by Junio (Git maintainer)

https://www.kernel.org/pub/software/scm/git/docs/

> but that site seems a bit off.
-- 
Duy

Re: is http://git-scm.com an *official* git-affiliated site?

[Robert P. J. Day]

On Wed, 7 Feb 2018, Duy Nguyen wrote:

> On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> >
> >   i ask WRT whether it should be up to date. i'm currently writing a
> > number of git-related wiki pages, and i want to link to whatever are
> > the canonical man pages for various git commands,
>
> I think this one is updated often by Junio (Git maintainer)
>
> https://www.kernel.org/pub/software/scm/git/docs/

  ah, better, thanks.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: is http://git-scm.com an *official* git-affiliated site?

[Ævar Arnfjörð Bjarmason]

On Wed, Feb 07 2018, Robert P. J. Day jotted:

>   i ask WRT whether it should be up to date. i'm currently writing a
> number of git-related wiki pages, and i want to link to whatever are
> the canonical man pages for various git commands, but that site seems
> a bit off.
>
>   if one follows a link to get here:
>
> https://git-scm.com/doc
>
> there is another link to the "Reference Manual" that promises "The
> official and comprehensive man pages that are included in the Git
> package itself."
>
>   but upon getting there:
>
> https://git-scm.com/docs
>
> it seems clear that that page doesn't come close to covering all of
> the available git commands.
>
>   as an example, there is a link "submodule" on that page, which does
> indeed take one to the page https://git-scm.com/docs/git-submodule. so
> far, so good.
>
>   however, while there is no link for the "worktree" command, there
> does in fact exist a similarly-named web page
> https://git-scm.com/docs/git-worktree.

It is an official site, of the git project. The project is legally
managed by the SFC which owns the domain, Github happens to host it (for
free) for us.

It's not fully auto-generated so stuff like git-worktree doesn't get
added automatically, I just added a PR for that:
https://github.com/git/git-scm.com/pull/1133

>   finally, there is no reference to the git "subtree" command, either
> as a link *or* as an existing web page
> https://git-scm.com/docs/git-subtree. it all seems kind of arbitrary.

Unlike git-worktree, git-subtree is not shipped as a "proper" git
command, it lives in contrib/. What the status of that is I'm not sure,
but that's why it's not on git-scm or kernel.org in any form.

>   is there an actual, canonical set of online web pages for all
> current git commands one should use?

You can use git-scm.com or the kernel.org link Duy noted.

The thing that's the most official is the man pages we ship with any
given release, and as seen above the online presence may lag behind in
some ways, but that can always be fixed.

Even though we may have some official online sources, it's better to
direct users to the documentation that ships with git on their system,
since it'll reflect the version they're using.

Re: is http://git-scm.com an *official* git-affiliated site?

[Robert P. J. Day]

On Wed, 7 Feb 2018, Duy Nguyen wrote:

> On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> >
> >   i ask WRT whether it should be up to date. i'm currently writing a
> > number of git-related wiki pages, and i want to link to whatever are
> > the canonical man pages for various git commands,
>
> I think this one is updated often by Junio (Git maintainer)
>
> https://www.kernel.org/pub/software/scm/git/docs/

  whoops, just noticed that there is still no entry for "git subtree"
there; is there something about that git command that makes it so hard
to track down? :-)

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: is http://git-scm.com an *official* git-affiliated site?

[Duy Nguyen]

On Wed, Feb 7, 2018 at 6:41 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> On Wed, 7 Feb 2018, Duy Nguyen wrote:
>
>> On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>> >
>> >   i ask WRT whether it should be up to date. i'm currently writing a
>> > number of git-related wiki pages, and i want to link to whatever are
>> > the canonical man pages for various git commands,
>>
>> I think this one is updated often by Junio (Git maintainer)
>>
>> https://www.kernel.org/pub/software/scm/git/docs/
>
>   whoops, just noticed that there is still no entry for "git subtree"
> there; is there something about that git command that makes it so hard
> to track down? :-)

git-subtree is not an official command, so it's not there.
-- 
Duy

Re: is http://git-scm.com an *official* git-affiliated site?

[Robert P. J. Day]

On Wed, 7 Feb 2018, Duy Nguyen wrote:

> On Wed, Feb 7, 2018 at 6:41 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> > On Wed, 7 Feb 2018, Duy Nguyen wrote:
> >
> >> On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> >> >
> >> >   i ask WRT whether it should be up to date. i'm currently writing a
> >> > number of git-related wiki pages, and i want to link to whatever are
> >> > the canonical man pages for various git commands,
> >>
> >> I think this one is updated often by Junio (Git maintainer)
> >>
> >> https://www.kernel.org/pub/software/scm/git/docs/
> >
> >   whoops, just noticed that there is still no entry for "git subtree"
> > there; is there something about that git command that makes it so hard
> > to track down? :-)
>
> git-subtree is not an official command, so it's not there.

  i'm going to push back a bit on that since, at the bottom of the man
page for git-subtree, it states:

  GIT
       Part of the git(1) suite

so either it's part of the git suite, or it isn't.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: is http://git-scm.com an *official* git-affiliated site?

[Duy Nguyen]

On Wed, Feb 7, 2018 at 6:58 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> On Wed, 7 Feb 2018, Duy Nguyen wrote:
>
>> On Wed, Feb 7, 2018 at 6:41 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>> > On Wed, 7 Feb 2018, Duy Nguyen wrote:
>> >
>> >> On Wed, Feb 7, 2018 at 5:54 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>> >> >
>> >> >   i ask WRT whether it should be up to date. i'm currently writing a
>> >> > number of git-related wiki pages, and i want to link to whatever are
>> >> > the canonical man pages for various git commands,
>> >>
>> >> I think this one is updated often by Junio (Git maintainer)
>> >>
>> >> https://www.kernel.org/pub/software/scm/git/docs/
>> >
>> >   whoops, just noticed that there is still no entry for "git subtree"
>> > there; is there something about that git command that makes it so hard
>> > to track down? :-)
>>
>> git-subtree is not an official command, so it's not there.
>
>   i'm going to push back a bit on that since, at the bottom of the man
> page for git-subtree, it states:
>
>   GIT
>        Part of the git(1) suite
>
> so either it's part of the git suite, or it isn't.

It's a template that people use when write document for new commands.
That part should be deleted, I guess, if it's that confusing.
-- 
Duy

Re: is http://git-scm.com an *official* git-affiliated site?

[Jeff King]

On Wed, Feb 07, 2018 at 12:37:32PM +0100, Ævar Arnfjörð Bjarmason wrote:

> >   however, while there is no link for the "worktree" command, there
> > does in fact exist a similarly-named web page
> > https://git-scm.com/docs/git-worktree.
> 
> It is an official site, of the git project. The project is legally
> managed by the SFC which owns the domain, Github happens to host it (for
> free) for us.

Actually, this isn't accurate anymore. The costs are covered by
donated services from a few companies. I've been meaning to write this
up (and thank them!), and will probably send something out around the
contributor summit.

> It's not fully auto-generated so stuff like git-worktree doesn't get
> added automatically, I just added a PR for that:
> https://github.com/git/git-scm.com/pull/1133

Thanks for doing that. I'm also open to auto-generating the index if we
can come up with well-organized output.

-Peff

Re: is http://git-scm.com an *official* git-affiliated site?

[Jeff King]

On Wed, Feb 07, 2018 at 11:34:51AM +0000, pedro rijo wrote:

> The command list under https://git-scm.com/docs doesn't show all the
> commands. It's a manually curated list as we can see at
> 
> - https://github.com/git/git-scm.com/blob/master/app/views/doc/ref.html.erb
> - https://github.com/git/git-scm.com/tree/master/app/views/shared/ref
> 
> I'm not sure if the goal ever was to list all available commands or to just
> list some important existing commands (cc @Peff).
>
> If we want to list all available commands, there's some work that must be
> done in order to automate that, since it's not feasible to manually add
> each new command.

I think we _could_ just add all commands, but there's some value in
organizing them. I'm not sure if there's enough information in git.git
to do that organization. But we could also have a curated list of some
subset of the commands, and then dump the rest in an alphabetized index.

-Peff

Re: is http://git-scm.com an *official* git-affiliated site?

[Jean-Noël Avila]

On 07/02/2018, Jeff King wrote:

> On Wed, Feb 07, 2018 at 12:37:32PM +0100, Ævar Arnfjörð Bjarmason wrote:
>
>
>> It's not fully auto-generated so stuff like git-worktree doesn't get
>> added automatically, I just added a PR for that:
>> https://github.com/git/git-scm.com/pull/1133
> Thanks for doing that. I'm also open to auto-generating the index if we
> can come up with well-organized output.
>
> -Peff


I did not know that git-worktree is not considered ready for general
consumption. It has been present in the release notes for quite some
time now.


If there's something available from the git repo to drive the build of
the index, that would be a good way to advert the publicly available
commands of git.


JN