categorization, documentation and packaging of "git core" commands

categorization, documentation and packaging of "git core" commands

[Robert P. J. Day]

  (related to earlier thread but different enough that i'll start
fresh.)

  based on the collection of man page links here:

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

i took a look at how git 2.14.3 is laid out on my fedora 27 system,
particularly all of the executables under /usr/libexec/git-core/.
after manually cross-checking all of those executables against the
links on the docs page, here's what i learned.

  first, here are the executables under /usr/libexec/git-core/ that
are unreferenced by that web page, but that should be fine as almost
all of them would be considered underlying helpers or utilities
(except for things like git-subtree, but we're still unclear on its
status, right?):

  git-add--interactive
  git-bisect--helper
  git-credential-cache--daemon
  git-credential-libsecret
  git-credential-netrc
  git-difftool--helper
  git-fsck-objects
  git-gui--askpass
  git-init-db
  git-merge-octopus
  git-merge-ours
  git-merge-recursive
  git-merge-resolve
  git-merge-subtree
  git-mergetool--lib
  git-rebase--am
  git-rebase--helper
  git-rebase--interactive
  git-rebase--merge
  git-remote-ext
  git-remote-fd
  git-remote-ftp
  git-remote-ftps
  git-remote-http
  git-remote-https
  git-sh-i18n--envsubst
  git-stage
  git-submodule--helper
  git-subtree
  git-web--browse

on the other hand (and this is not so much a git issue as a fedora
packaging issue), there are a number of command links at that web page
that are supplied by distinct RPM packages rather than by the basic
fedora git package, so one would need to install the following
packages to get some of those commands on fedora:

  * gitk
  * git-cvs
  * git-svn
  * git-p4
  * git-email (provides git-send-email)

finally, from fedora, i am utterly unable to find a package that
provides git-archimport. pretty sure fedora used to have a "git-arch"
package but it's not there now.

rday

-- 

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

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

Re: categorization, documentation and packaging of "git core" commands

[Todd Zullinger]

Robert P. J. Day wrote:
> first, here are the executables under /usr/libexec/git-core/ that
> are unreferenced by that web page, but that should be fine as almost
> all of them would be considered underlying helpers or utilities
> (except for things like git-subtree, but we're still unclear on its
> status, right?):

I don't think there's anything unclear about git subtree's
status.  It's in contrib/ within the source, so it's not
part of the core git suite.  Some distributions (Fedora
being one of them) ship a git-subtree package to provide it
for users who want it.

> on the other hand (and this is not so much a git issue as a fedora
> packaging issue), there are a number of command links at that web page
> that are supplied by distinct RPM packages rather than by the basic
> fedora git package, so one would need to install the following
> packages to get some of those commands on fedora:
> 
>   * gitk
>   * git-cvs
>   * git-svn
>   * git-p4
>   * git-email (provides git-send-email)

These packages are in separate sub-packages in Fedora (and
some other distributions) because they are no required by
all users and they pull in dependencies which are not wanted
on minimal installs.  In Fedora, you can install git-all to
get all the available git sub-packages.

> finally, from fedora, i am utterly unable to find a package that
> provides git-archimport. pretty sure fedora used to have a "git-arch"
> package but it's not there now.

It hasn't been in Fedora since 2011.  The tla command which
is required for git-archimport  was retired, thus we removed
the git-arch package.  The rpm changelog shows this:

* Tue Jul 26 2011 Todd Zullinger <tmz@pobox.com> - 1.7.6-4
- Drop git-arch on fedora >= 16, the tla package has been retired

As does the git history for the package:

    https://src.fedoraproject.org/rpms/git/c/3f0dc974fa

The tla package was retired because it failed to build for
several releases:

    https://src.fedoraproject.org/rpms/tla/blob/master/f/dead.package

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Going to trial with a lawyer who considers your whole life-style a
Crime in Progress is not a happy prospect.
    -- Hunter S. Thompson

Re: categorization, documentation and packaging of "git core" commands

[Robert P. J. Day]

On Wed, 7 Feb 2018, Todd Zullinger wrote:

> Robert P. J. Day wrote:
> > first, here are the executables under /usr/libexec/git-core/ that
> > are unreferenced by that web page, but that should be fine as
> > almost all of them would be considered underlying helpers or
> > utilities (except for things like git-subtree, but we're still
> > unclear on its status, right?):
>
> I don't think there's anything unclear about git subtree's status.
> It's in contrib/ within the source, so it's not part of the core git
> suite.  Some distributions (Fedora being one of them) ship a
> git-subtree package to provide it for users who want it.

  not true, "git-subtree" is part of fedora's lowest-level
"git-core" package.

rday

-- 

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

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

Re: categorization, documentation and packaging of "git core" commands

[Todd Zullinger]

Robert P. J. Day wrote:
> On Wed, 7 Feb 2018, Todd Zullinger wrote:
> 
>> Robert P. J. Day wrote:
>>> first, here are the executables under /usr/libexec/git-core/ that
>>> are unreferenced by that web page, but that should be fine as
>>> almost all of them would be considered underlying helpers or
>>> utilities (except for things like git-subtree, but we're still
>>> unclear on its status, right?):
>>
>> I don't think there's anything unclear about git subtree's status.
>> It's in contrib/ within the source, so it's not part of the core git
>> suite.  Some distributions (Fedora being one of them) ship a
>> git-subtree package to provide it for users who want it.
> 
>   not true, "git-subtree" is part of fedora's lowest-level
> "git-core" package.

Eek, my apologies for providing bad information.  I really
should know the Fedora git packaging better than that. :/

Amusingly, I did suggest packaging it as a subpackage
specifically to avoid any confusion that it was a core
command in the Fedora bug which requested it be included in
the git packaging:

    https://bugzilla.redhat.com/show_bug.cgi?id=864651

I'll see about changing that going forward in the Fedora
packaging.  I think it deserves to be in a subpackage.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Doing a job RIGHT the first time gets the job done.
Doing the job WRONG fourteen times gives you job security.

Re: categorization, documentation and packaging of "git core" commands

[Robert P. J. Day]

On Wed, 7 Feb 2018, Todd Zullinger wrote:

> Robert P. J. Day wrote:

... snip ...

> > finally, from fedora, i am utterly unable to find a package that
> > provides git-archimport. pretty sure fedora used to have a
> > "git-arch" package but it's not there now.
>
> It hasn't been in Fedora since 2011.  The tla command which is
> required for git-archimport was retired, thus we removed the
> git-arch package.  The rpm changelog shows this:
>
> * Tue Jul 26 2011 Todd Zullinger <tmz@pobox.com> - 1.7.6-4
> - Drop git-arch on fedora >= 16, the tla package has been retired
>
> As does the git history for the package:
>
>     https://src.fedoraproject.org/rpms/git/c/3f0dc974fa
>
> The tla package was retired because it failed to build for
> several releases:
>
>     https://src.fedoraproject.org/rpms/tla/blob/master/f/dead.package

  huh ... well, that raises the question, if tla has been unbuildable
for that long (possibly for other distros), what is the value in
continuing to support git-archimport?

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

i don't really care one way or the other, but perhaps git-archimport
should be broken out as a "non-core" component of git. related post
coming shortly ...

rday

-- 

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

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

Re: categorization, documentation and packaging of "git core" commands

[Jeff King]

On Wed, Feb 07, 2018 at 03:03:31PM -0500, Robert P. J. Day wrote:

>   huh ... well, that raises the question, if tla has been unbuildable
> for that long (possibly for other distros), what is the value in
> continuing to support git-archimport?
> 
>   https://www.kernel.org/pub/software/scm/git/docs/git-archimport.html

I don't think that we do really support archimport. It's just that we
tend to leave things sitting around if they're not actively causing us
work, in the off chance that somebody might find them useful.

I'd be OK with declaring archimport dead and unmaintained, and dropping
it totally (I almost did so a few months ago when it _did_ cause me
extra work, because it contained a bunch of shell injections that I
turned up while auditing the whole code base).

-Peff

Re: categorization, documentation and packaging of "git core" commands

[Robert P. J. Day]

On Wed, 7 Feb 2018, Todd Zullinger wrote:

> Robert P. J. Day wrote:
> > first, here are the executables under /usr/libexec/git-core/ that
> > are unreferenced by that web page, but that should be fine as
> > almost all of them would be considered underlying helpers or
> > utilities (except for things like git-subtree, but we're still
> > unclear on its status, right?):
>
> I don't think there's anything unclear about git subtree's status.
> It's in contrib/ within the source, so it's not part of the core git
> suite.  Some distributions (Fedora being one of them) ship a
> git-subtree package to provide it for users who want it.
>
> > on the other hand (and this is not so much a git issue as a fedora
> > packaging issue), there are a number of command links at that web
> > page that are supplied by distinct RPM packages rather than by the
> > basic fedora git package, so one would need to install the
> > following packages to get some of those commands on fedora:
> >
> >   * gitk
> >   * git-cvs
> >   * git-svn
> >   * git-p4
> >   * git-email (provides git-send-email)
>
> These packages are in separate sub-packages in Fedora (and some
> other distributions) because they are no required by all users and
> they pull in dependencies which are not wanted on minimal installs.
> In Fedora, you can install git-all to get all the available git
> sub-packages.

  not to belabour this (and i'm sure it's *way* too late for that),
but fedora has the following packaging scheme.  first, there's a bunch
of stuff in "git-core", which has no dependencies on any other
git-related packages.

  then there's "git", which has the following property:

  $ rpm -qR git
  /bin/sh
  /usr/bin/perl
  emacs-filesystem >= 25.3
  git-core = 2.14.3-2.fc27
  git-core-doc = 2.14.3-2.fc27
  ... snip ...

  $ rpm -ql git
  ... snip ...
  /usr/libexec/git-core/git-add--interactive
  /usr/libexec/git-core/git-am
  /usr/libexec/git-core/git-credential-libsecret
  /usr/libexec/git-core/git-credential-netrc
  /usr/libexec/git-core/git-difftool
  /usr/libexec/git-core/git-difftool--helper
  /usr/libexec/git-core/git-instaweb
  /usr/libexec/git-core/git-request-pull
  /usr/libexec/git-core/git-submodule
  /usr/libexec/git-core/git-submodule--helper
  ... snip ...
  /usr/share/man/man1/git-am.1.gz
  /usr/share/man/man1/git-difftool.1.gz
  /usr/share/man/man1/git-instaweb.1.gz
  /usr/share/man/man1/git-request-pull.1.gz
  /usr/share/man/man1/git-submodule.1.gz
  /usr/share/man/man1/gitweb.1.gz
  /usr/share/man/man5/gitweb.conf.5.gz
  $

so with fedora, "git" drags in "git-core" and a small number of
additional git utilities. all of this leads one to wonder -- is there
any comprehensible relationship between:

  1) commands that claim to be in the "git suite"
  2) commands that come from contrib/
  3) commands listed at
     https://www.kernel.org/pub/software/scm/git/docs/
  4) how different distros package all of the above

as i think we've noticed, it's not at all clear how git decides what
is and isn't part of the "official" git suite.

rday

-- 

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

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

Re: categorization, documentation and packaging of "git core" commands

[Todd Zullinger]

Robert P. J. Day wrote:
> not to belabour this (and i'm sure it's *way* too late for that),
> but fedora has the following packaging scheme.  first, there's a bunch
> of stuff in "git-core", which has no dependencies on any other
> git-related packages.

The split in Fedora between git and git-core is done to
minimize the dependencies required for a minimal git
install.  The initial reason was to to allow installing the
git-core package on systems, in containers, etc. without
requiring perl and its various dependencies to be installed.

The name git-core was not chosen to imply any official
status as core versus contrib from upstream.

(Farther back in the past, the main git package (and the
upstream tarball, IIRC) was named git-core due to conflicts
with another tool named git (GNU interactive tools).)

> so with fedora, "git" drags in "git-core" and a small number of
> additional git utilities. all of this leads one to wonder -- is there
> any comprehensible relationship between:
> 
>   1) commands that claim to be in the "git suite"
>   2) commands that come from contrib/
>   3) commands listed at
>      https://www.kernel.org/pub/software/scm/git/docs/
>   4) how different distros package all of the above
> 
> as i think we've noticed, it's not at all clear how git decides what
> is and isn't part of the "official" git suite.

I don't think there's any good reason to use the packaging
of any distribution as the source for what the git project
considers officially part of the suite.  For that, you
should look at the git source and particularly
contrib/README.  The first paragraph says:

    Although these pieces are available as part of the official git
    source tree, they are in somewhat different status.  The
    intention is to keep interesting tools around git here, maybe
    even experimental ones, to give users an easier access to them,
    and to give tools wider exposure, so that they can be improved
    faster.

If anything the Fedora packging does in the splitting or
naming of the git packages is something the git project
feels is incorrect or needlessly confusing, I (with my
Fedora maintainer hat on) would be happy to make any changes
I can to improve things.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some god must protect drunkards and fools, there are so many of them
still around.

Re: categorization, documentation and packaging of "git core" commands

[Robert P. J. Day]

On Wed, 7 Feb 2018, Todd Zullinger wrote:

> Robert P. J. Day wrote:
> > not to belabour this (and i'm sure it's *way* too late for that),
> > but fedora has the following packaging scheme.  first, there's a
> > bunch of stuff in "git-core", which has no dependencies on any
> > other git-related packages.
>
> The split in Fedora between git and git-core is done to minimize the
> dependencies required for a minimal git install.  The initial reason
> was to to allow installing the git-core package on systems, in
> containers, etc. without requiring perl and its various dependencies
> to be installed.
>
> The name git-core was not chosen to imply any official status as
> core versus contrib from upstream.

  ... snip ...

  oh, i understand completely (i particularly like that fedora
supports a "git-extras" package with loads of cool stuff). remember
that this all started when i pointed out that, over at
https://git-scm.com/doc, there is a link entitled "Reference Manual"
(https://git-scm.com/docs) that assures the reader, "The official and
comprehensive man pages that are included in the Git package itself",
so it's just a matter of someone deciding what *exactly* corresponds
to "the Git package itself" to make sure all relevant man pages can be
found there.

  just being pedantic, as is my wont.

rday