Re: Problems using perl's Git.pm module

Ævar Arnfjörð Bjarmason [off-list ref] writes:

On Thu, Dec 2, 2010 at 12:40, Josef Wolf [off-list ref] wrote:

quoted

I am trying to use perl's Git.pm module, but for some reason, it keeps
bailing out:

Why are you using it? It's for internal use only.

That is not a valid question nor answer, I am afraid.

It probably is showing that perl/Git.pm is underdocumented.  We should
make it possible if not trivial for people who want to write the next
great git-svn.perl or whatever that uses the module to interact with the
repository.

I don't understand why the Josef's scriptlet passes Directory to the
initialization code.  Is it working with a bare repository?

On 2 December 2010 18:46, Junio C Hamano [off-list ref] wrote:

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

On Thu, Dec 2, 2010 at 12:40, Josef Wolf [off-list ref] wrote:

quoted

I am trying to use perl's Git.pm module, but for some reason, it keeps
bailing out:

Why are you using it? It's for internal use only.

That is not a valid question nor answer, I am afraid.

So you are saying that it is for more than internal use?

Yves


-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

demerphq wrote:

On 2 December 2010 18:46, Junio C Hamano [off-list ref] wrote:

quoted

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

quoted

Why are you using it? It's for internal use only.

That is not a valid question nor answer, I am afraid.

So you are saying that it is for more than internal use?

I assume so.  I had guessed the same thing (that it is meant to be
generally useful), based on the following:

 - it is installed to be usable with a simple "use Git"
   automatically

 - "perldoc Git" tells me that this module gives Perl scripts an easy
   way to interface the Git version control system, not that it is an
   implementation artifact

 - tools like "git svn" were not historically part of core git, and
   usage by them was not exactly internal use.

Hope that helps.
Jonathan

On 2 December 2010 19:14, Jonathan Nieder [off-list ref] wrote:

demerphq wrote:

quoted

On 2 December 2010 18:46, Junio C Hamano [off-list ref] wrote:

quoted

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

quoted

quoted

Why are you using it? It's for internal use only.

That is not a valid question nor answer, I am afraid.

So you are saying that it is for more than internal use?

I assume so.  I had guessed the same thing (that it is meant to be
generally useful), based on the following:

 - it is installed to be usable with a simple "use Git"
  automatically

Well that is true. But im not sure that is a good reason.

 - "perldoc Git" tells me that this module gives Perl scripts an easy
  way to interface the Git version control system, not that it is an
  implementation artifact

Any perl module, or script, or podfile installed in a place that
perldoc knows about is available to perldoc.

 - tools like "git svn" were not historically part of core git, and
  usage by them was not exactly internal use.

Well, the counter  arguments are:

No back-compat layer for older gits. Tight binding to a particular git
- no availability of upgrades independent of upgrading git. No
availability or review of the module on the standard venues for doing
so for Perl modules. CPAN, CPANTESTERS, smoke reports, etc.

And well the line:

# Totally unstable API.
$VERSION = '0.01';

STRONGLY suggests that the module should not be used by code outside
the Git package itself.

Cheers,
yves


-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

Git's internal perl interface still does not have a stable API, and
meanwhile CPAN has a number of modules to fulfill the need for a perl
git interface.  The line

	# Totally unstable API.
	$VERSION = '0.01';

in the source makes this clear enough, but users who just looked at
git-svn.perl and then tried "perldoc Git" would not notice.  Add a
note to the manual to warn the reader.

Inspired-by: Yves Orton [off-list ref]
Signed-off-by: Jonathan Nieder <redacted>
---
demerphq wrote:

And well the line:

# Totally unstable API.
$VERSION = '0.01';

STRONGLY suggests that the module should not be used by code outside
the Git package itself.

So how about something like this patch, to start?

diff --git a/perl/Git.pm b/perl/Git.pm
index 6cb0dd1..7f6c500 100644
--- a/perl/Git.pm
+++ b/perl/Git.pm

@@ -63,12 +63,16 @@ require Exporter;
 
 =head1 DESCRIPTION
 
-This module provides Perl scripts easy way to interface the Git version control
-system. The modules have an easy and well-tested way to call arbitrary Git
+This module provides an easy way to interact with the Git version control
+system for Git's internal perl scripts.
+The modules have an easy and well-tested way to call arbitrary Git
 commands; in the future, the interface will also provide specialized methods
 for doing easily operations which are not totally trivial to do over
 the generic command interface.
 
+Note: this module should not be used by code outside the Git package itself,
+since the API is not stable yet.
+
 While some commands can be executed outside of any context (e.g. 'version'
 or 'init'), most operations require a repository context, which in practice
 means getting an instance of the Git object using the repository() constructor.

On Thu, Dec 02, 2010 at 07:41:00PM +0100, demerphq wrote:

Well, the counter  arguments are:

No back-compat layer for older gits. Tight binding to a particular git
- no availability of upgrades independent of upgrading git.

I don't understand this one. Why do you need independent upgrades here?
Since Git.pm comes with git core, the installed version of Git.pm should
always match the installed version of git.

No
availability or review of the module on the standard venues for doing
so for Perl modules. CPAN, CPANTESTERS, smoke reports, etc.

A module on CPAN has better tests for perl integration.
A module in git-core has better tests for git integration.

You trade one for the other. The question is which is more critical. IMHO,
git-integration is more critical.

On 3 December 2010 09:38, Josef Wolf [off-list ref] wrote:

On Thu, Dec 02, 2010 at 07:41:00PM +0100, demerphq wrote:

quoted

Well, the counter  arguments are:

No back-compat layer for older gits. Tight binding to a particular git
- no availability of upgrades independent of upgrading git.

I don't understand this one. Why do you need independent upgrades here?
Since Git.pm comes with git core, the installed version of Git.pm should
always match the installed version of git.

Because in my experience coding a tool against a particular version of
Git.pm basically means that tool has to be on the same git version or
higher than the version you coded against.

There is no easy/safe way to update Git,pm to provide a consistent
interface to older gits.

quoted

No
availability or review of the module on the standard venues for doing
so for Perl modules. CPAN, CPANTESTERS, smoke reports, etc.

A module on CPAN has better tests for perl integration.
A module in git-core has better tests for git integration.

You trade one for the other. The question is which is more critical. IMHO,
git-integration is more critical.

A CPAN module would be automatically tested by the CPANTESTERS
community against whatever git people happened to have lying around,
and those tests would necessarily occur on a myriad of systems, and
when failures occurred they would be automatically registered in CPAN
rt bug tracking system, and available in various summarized and
detailed forms from multiple locations.

Those test results and integration efforts would be automatically fed
back to the module author, be publicly available on several websites,
including via CPAN itself, and if it should happen that the p5p group
were to somehow break Git.pm somehow we would know about it, and be
able to fix perl itself without Git.pm having to change. Admittedly
this is unlikely given the nature of the code.

So really, by tightly binding the package to git all that you
guarantee is that the version of Git.pm installed by git will work
with the git you have installed. It does not say that any program
written against that version of Git.pm will continue to work on a
later version, or that people stuck on a older version of git will be
able to use it.

cheers,
Yves







-- 
perl -Mre=debug -e "/just|another|perl|hacker/"