threads / discuss / 47777

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

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

## tl;dr

11 messages between Feb 7, 2018 and Feb 7, 2018.

replies: 10people: 5as markdown or json

Robert P. J. Day· Feb 7, 2018, 10:54 UTC · lore

  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
========================================================================

Duy Nguyen· Feb 7, 2018, 11:21 UTC · re: Robert P. J. Day · lore

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

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

Robert P. J. Day· Feb 7, 2018, 11:37 UTC · re: Duy Nguyen · lore

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

On Wed, 7 Feb 2018, Duy Nguyen wrote:

Show 9 quoted lines

> 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
========================================================================

Robert P. J. Day· Feb 7, 2018, 11:41 UTC · re: Duy Nguyen · lore

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

On Wed, 7 Feb 2018, Duy Nguyen wrote:

Show 9 quoted lines

> 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
========================================================================

Duy Nguyen· Feb 7, 2018, 11:50 UTC · re: Robert P. J. Day · lore

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

On Wed, Feb 7, 2018 at 6:41 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:

Show 15 quoted lines

> 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

Robert P. J. Day· Feb 7, 2018, 11:58 UTC · re: Duy Nguyen · lore

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

On Wed, 7 Feb 2018, Duy Nguyen wrote:

Show 18 quoted lines

> 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
========================================================================

Duy Nguyen· Feb 7, 2018, 12:07 UTC · re: Robert P. J. Day · lore

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

On Wed, Feb 7, 2018 at 6:58 PM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:

Show 28 quoted lines

> 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

Ævar Arnfjörð Bjarmason· Feb 7, 2018, 11:37 UTC · re: Robert P. J. Day · lore

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

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

Show 27 quoted lines

>   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.

Jeff King· Feb 7, 2018, 12:54 UTC · re: Ævar Arnfjörð Bjarmason · lore

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

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

Show 7 quoted lines

> >   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

Jean-Noël Avila· Feb 7, 2018, 13:10 UTC · re: Jeff King · lore

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

On 07/02/2018, Jeff King wrote:

Show 10 quoted lines

> 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

Jeff King· Feb 7, 2018, 12:56 UTC · lore

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

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

Show 12 quoted lines

> 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