Deprecate git-fetch-pack?

Deprecate git-fetch-pack?

[Daniel Barkalow]

Now that git-fetch is in C, built in, and doing the fetch-pack in the same 
process, the normal usage patterns don't involve actually executing 
git-fetch-pack. Can we deprecate it at this point, or it is plausibly 
being used by scripts? As it is now, I'm not entirely confidant that the 
tests in t5500 won't be fooled by git-fetch working even with 
git-fetch-pack being broken in various ways, which should be fixed if we 
want to keep it.

We also might as well deprecate peek-remote now that it's a synonym for 
ls-remote.

	-Daniel
*This .sig left intentionally blank*

Re: Deprecate git-fetch-pack?

[Junio C Hamano]

Daniel Barkalow <barkalow@iabervon.org> writes:

> Now that git-fetch is in C, built in, and doing the fetch-pack in the same 
> process, the normal usage patterns don't involve actually executing 
> git-fetch-pack. Can we deprecate it at this point, or it is plausibly 
> being used by scripts? As it is now, I'm not entirely confidant that the 
> tests in t5500 won't be fooled by git-fetch working even with 
> git-fetch-pack being broken in various ways, which should be fixed if we 
> want to keep it.
>
> We also might as well deprecate peek-remote now that it's a synonym for 
> ls-remote.

Especially because git-fetch is no longer as hackable as it used
to be, and because people may still find special needs that can
be hacked up with direct access to low level transports from the
script more easily than going down to the C level, I'd rather
wait and see for a cycle or two to decide.  There is no strong
reason to drop it, is there?

As to peek-remote, ls-remote over the native transport is a
synonym so I do not think anybody doing the scripting would have
problem doing s/peek-/ls-/ to their script, but again I do not
see a heavy maintenance burden to keep the synonym, yet.

Re: Deprecate git-fetch-pack?

[Ask Bjørn Hansen]

On Nov 10, 2007, at 4:48 PM, Junio C Hamano wrote:

> As to peek-remote, ls-remote over the native transport is a
> synonym so I do not think anybody doing the scripting would have
> problem doing s/peek-/ls-/ to their script, but again I do not
> see a heavy maintenance burden to keep the synonym, yet.

For new users the superfluous programs are a burden making it harder  
to learn how everything works.

"What does this thing do?  How is it different from that other similar  
program?  How do they interact?  Oh, this one isn't really used.  Grrh."

At least a note in the documentation that it's superseded by  
$other_program would be helpful for us newcomers.  :-)


  - ask

-- 
http://develooper.com/ - http://askask.com/

Re: Deprecate git-fetch-pack?

[Johannes Schindelin]

Hi,

On Sat, 10 Nov 2007, Ask Bj?rn Hansen wrote:

> For new users the superfluous programs are a burden making it harder to 
> learn how everything works.

This should be a non-issue.  We really should start deprecating 
"git-<command>" in favour of "git <command>" for real.

New users should not even be told that this is correct usage.

My reason?  We have plumbing, and we will always have plumbing, as 
commands.  A regular git user does not _want_ to see that.  Without said 
deprecation she _will_, however.

Ciao,
Dscho

Re: Deprecate git-fetch-pack?

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Hi,
>
> On Sat, 10 Nov 2007, Ask Bj?rn Hansen wrote:
>
>> For new users the superfluous programs are a burden making it harder to 
>> learn how everything works.
>
> This should be a non-issue.  We really should start deprecating 
> "git-<command>" in favour of "git <command>" for real.
>
> New users should not even be told that this is correct usage.
>
> My reason?  We have plumbing, and we will always have plumbing, as 
> commands.  A regular git user does not _want_ to see that.  Without said 
> deprecation she _will_, however.

If you can write "git-commit" and "git commit" interchangeably
while you cannot say "git-cat-file" and are forced to say "git
cat-file", I suspect that would lead to a great confusion and
unhappy users.

I wonder if making the distinction between plumbing and
porcelain in the git(7) page even more cleaner would help.

Re: Deprecate git-fetch-pack?

[Theodore Tso]

On Sun, Nov 11, 2007 at 01:16:09PM -0800, Junio C Hamano wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> > This should be a non-issue.  We really should start deprecating 
> > "git-<command>" in favour of "git <command>" for real.
> >
> > New users should not even be told that this is correct usage.
> >
> 
> If you can write "git-commit" and "git commit" interchangeably
> while you cannot say "git-cat-file" and are forced to say "git
> cat-file", I suspect that would lead to a great confusion and
> unhappy users.

One of the reasons why I use git-diff and git-commit and in particular
"git-rebase --interactive master" very often is that it allows my
shell's bang completion to work.  (i.e., "!git-rebase").  If we tell
people they can not use "git-rebase", and must instead use "git
rebase" instead, I would consider that pretty annoying/obnoxious.

					- Ted

Re: Deprecate git-fetch-pack?

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> On Sun, Nov 11, 2007 at 01:16:09PM -0800, Junio C Hamano wrote:
>> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>> > This should be a non-issue.  We really should start deprecating 
>> > "git-<command>" in favour of "git <command>" for real.
>> >
>> > New users should not even be told that this is correct usage.
>> 
>> If you can write "git-commit" and "git commit" interchangeably
>> while you cannot say "git-cat-file" and are forced to say "git
>> cat-file", I suspect that would lead to a great confusion and
>> unhappy users.
>
> One of the reasons why I use git-diff and git-commit and in particular
> "git-rebase --interactive master" very often is that it allows my
> shell's bang completion to work.  (i.e., "!git-rebase").  If we tell
> people they can not use "git-rebase", and must instead use "git
> rebase" instead, I would consider that pretty annoying/obnoxious.

Oh, of course.

But my impression was that Johannes was talking about
deprecating git-<foo> form only for plumbing, so that the users
will only see git-<foo> for the Porcelain.  That would not break
your bang completion for the porcelain commands.

If Johannes was talking about deprecating all git-<foo> form,
then that would indeed break your bang completion, but it has
conceptually a much bigger problem.  The topic was about fixing
"a new user sees too many git commands and gets scared" problem.
Deprecaing all git-<foo> form just replaces the problem with "a
new user sees too many git subcommands and gets scared" problem,
without solving anything.

Re: Deprecate git-fetch-pack?

[Johannes Schindelin]

Hi,

On Sun, 11 Nov 2007, Junio C Hamano wrote:

> Theodore Tso <tytso@mit.edu> writes:
> 
> > On Sun, Nov 11, 2007 at 01:16:09PM -0800, Junio C Hamano wrote:
> >> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> >> > This should be a non-issue.  We really should start deprecating 
> >> > "git-<command>" in favour of "git <command>" for real.
> >> >
> >> > New users should not even be told that this is correct usage.
> >> 
> >> If you can write "git-commit" and "git commit" interchangeably
> >> while you cannot say "git-cat-file" and are forced to say "git
> >> cat-file", I suspect that would lead to a great confusion and
> >> unhappy users.
> >
> > One of the reasons why I use git-diff and git-commit and in particular
> > "git-rebase --interactive master" very often is that it allows my
> > shell's bang completion to work.  (i.e., "!git-rebase").  If we tell
> > people they can not use "git-rebase", and must instead use "git
> > rebase" instead, I would consider that pretty annoying/obnoxious.
> 
> Oh, of course.
> 
> But my impression was that Johannes was talking about
> deprecating git-<foo> form only for plumbing, so that the users
> will only see git-<foo> for the Porcelain.  That would not break
> your bang completion for the porcelain commands.
> 
> If Johannes was talking about deprecating all git-<foo> form,
> then that would indeed break your bang completion, but it has
> conceptually a much bigger problem.  The topic was about fixing
> "a new user sees too many git commands and gets scared" problem.
> Deprecaing all git-<foo> form just replaces the problem with "a
> new user sees too many git subcommands and gets scared" problem,
> without solving anything.

I beg to differ.  The biggest problem with a new user seeing all those 
completions is that this user is scared.

Just taking away that first shock would be helping very much.  I mean, we 
_still_ have the reputation of being more complex than other SCMs, but I 
do not think that this reputation is completely deserved.

However, reputations are formed by first time impressions.  It is _hard_ 
to get rid of a bad first time impression.

But yes, I was only proposing to deprecate all usage of git-<bla> in the 
documentation.

Maybe I'm wrong.  Wouldn't be the first time.

Ciao,
Dscho

Re: Deprecate git-fetch-pack?

[Theodore Tso]

On Sun, Nov 11, 2007 at 10:50:26PM +0000, Johannes Schindelin wrote:
> I beg to differ.  The biggest problem with a new user seeing all those 
> completions is that this user is scared.

Well, if we introduce the new user only to "git subcomand", and the
documentation is relatively gentle, I would suspect would solve most
of the problem.  Note BTW, that if your thesis is true, "git help -a"
(which is recommended in the last line of output by "git help") should
cause the typical new user to faint dead away.  :-)

Some other areas that would be worth fixing, in terms of user usability.

1) The references to the tutorial, everyday git, etc., don't actually
have working references in the git man page.  (i.e., what you see when
you run the command "man git").   It would be nice if that were fixed.

2) The command which are displayed by "git help" should use some
serious rethinking.  Ideally, it would be nice if the output fit in a
single 24-line terminal window.   Some candidates for removal:

       a) prune: "git prune" definitely doesn't deserve to be on the
       front and center as displayed by "git help".  Maybe replace it
       with "gc", but now that we have gc.auto, I'm not sure it's
       worth it at all.

       b) revert:  Is that really that common of a command?

       c) show-branch: The output is terrifying without explanation

There are other commands I'm not so sure about, but it is worth
flagging them.  One way that might be helpful is to group the commands
into subcommands, much like gdb does, so you could do something like
"git help other-repos" (where all commands that involve interacting
with other repositories are summarized), and so on.

> But yes, I was only proposing to deprecate all usage of git-<bla> in the 
> documentation.

I agree that de-emphasizing git-<blah> isn't a bad thing.  But I think
we need to look at the big picture here, since "git help" is often one
of the first things a new user might try (and obviously very few git
developers look at it, or "prune" probably would have been removed
from git help a long time ago :-), and the last thing that git help
suggests (and so therefore it will very visible to the newbie user),
is "git help -a" --- and that displays every single git command under
creation, porcelain or plumbing, in one gigantic sorted list.  

Oops, so much for first impressions.  :-)

	   	    	     	   		 - Ted

Re: Deprecate git-fetch-pack?

[Jakub Narebski]

Theodore Tso wrote:

> 2) The command which are displayed by "git help" should use some
> serious rethinking.  Ideally, it would be nice if the output fit in a
> single 24-line terminal window.   Some candidates for removal:
> 
>        a) prune: "git prune" definitely doesn't deserve to be on the
>        front and center as displayed by "git help".  Maybe replace it
>        with "gc", but now that we have gc.auto, I'm not sure it's
>        worth it at all.

I would replace it by "git gc" (you have to run 'git gc --prune' by hand
on quiescent repository), or remove it altogether.

>        b) revert:  Is that really that common of a command?

It is useful command, perhaps short description should be improved.
BTW. if we have cherry-pick, then we should have revert.

>        c) show-branch: The output is terrifying without explanation

I agree. I would replace it by gitk, or gui (git-gui / "git gui").

> There are other commands I'm not so sure about, but it is worth
> flagging them.  One way that might be helpful is to group the commands
> into subcommands, much like gdb does, so you could do something like
> "git help other-repos" (where all commands that involve interacting
> with other repositories are summarized), and so on.

I think that "git-rm" could be removed, because "rm <file>; git commit ..."
works just fine.

See also discussion about results of Git User's Survey 2007, somewhere
around
  http://thread.gmane.org/gmane.comp.version-control.git/59935/focus=62205

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Deprecate git-fetch-pack?

[Jon Loeliger]

On Sun, 2007-11-11 at 18:16, Jakub Narebski wrote:

> >        c) show-branch: The output is terrifying without explanation
> 
> I agree. I would replace it by gitk, or gui (git-gui / "git gui").

I disagree; we should keep it.  It is a very useful command,
and usable on systems where GUI isn't an option.

Thanks,
jdl

Re: Deprecate git-fetch-pack?

[Johannes Schindelin]

Hi,

On Mon, 12 Nov 2007, Jon Loeliger wrote:

> On Sun, 2007-11-11 at 18:16, Jakub Narebski wrote:
> 
> > >        c) show-branch: The output is terrifying without explanation
> > 
> > I agree. I would replace it by gitk, or gui (git-gui / "git gui").
> 
> I disagree; we should keep it.

We keep it.  We just don't advertise it.  The whole thread was not about 
removing commands, but removing them from the output of "git help".

> It is a very useful command, and usable on systems where GUI isn't an 
> option.

Yes, and those systems are the majority nowadays.  Oh, wait...

Ciao,
Dscho

Re: Deprecate git-fetch-pack?

[Jon Loeliger]

On Mon, 2007-11-12 at 11:33, Johannes Schindelin wrote:

> > I disagree; we should keep it.
> 
> We keep it.  We just don't advertise it.  The whole thread was not about 
> removing commands, but removing them from the output of "git help".

Yes, I can read an understand English; I know the context.

> > It is a very useful command, and usable on systems where GUI isn't an 
> > option.
> 
> Yes, and those systems are the majority nowadays.  Oh, wait...

I remotely log into my server machines frequently.

Again, though, that is just my opinion.

jdl

Re: Deprecate git-fetch-pack?

[Johannes Schindelin]

Hi,

On Mon, 12 Nov 2007, Jon Loeliger wrote:

> On Mon, 2007-11-12 at 11:33, Johannes Schindelin wrote:
> 
> > Jon wrote:
> >
> > > It [git show-branch] is a very useful command, and usable on systems 
> > > where GUI isn't an option.
> > 
> > Yes, and those systems are the majority nowadays.  Oh, wait...
> 
> I remotely log into my server machines frequently.

Okay, sorry.  I was in a bad mood (you know why, I guess), and I was a 
little tongue-in-cheek here.  I apologise.

The thing is, show-branch might be mighty useful for you, but I agree with 
another poster that its output is not for the faint of heart, if it goes 
without an explanation.

So I vote for keeping relatively quiet about it in the output of "git 
help" which is -- according to some people -- the first thing new git 
users see.

Power users, such as yourself, will read in the user manual or in the FAQ 
about the existence of this nice tool, and do not need to be reminded of 
it by git-help.

Fair enough?
Dscho

Re: Deprecate git-fetch-pack?

[Jon Loeliger]

On Mon, 2007-11-12 at 13:08, Johannes Schindelin wrote:

> Okay, sorry.  I was in a bad mood (you know why, I guess), and I was a 
> little tongue-in-cheek here.  I apologise.

And accepted.

> Fair enough?

Yes.

> Dscho

Thanks,
jdl

[PATCH,RFC 1/2] Make the list of common commands more exclusive

[Theodore Ts'o]

Remove apply, archive, cherry-pick, prune, revert, and show-branch, so
"git help" is less intimidating.

Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
---
 generate-cmdlist.sh |    6 ------
 1 files changed, 0 insertions(+), 6 deletions(-)

diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh
index 17df47b..1ba27ec 100755
--- a/generate-cmdlist.sh
+++ b/generate-cmdlist.sh
@@ -11,12 +11,9 @@ static struct cmdname_help common_cmds[] = {"
 
 sort <<\EOF |
 add
-apply
-archive
 bisect
 branch
 checkout
-cherry-pick
 clone
 commit
 diff
@@ -26,15 +23,12 @@ init
 log
 merge
 mv
-prune
 pull
 push
 rebase
 reset
-revert
 rm
 show
-show-branch
 status
 tag
 EOF
-- 
1.5.3.5.623.g91546-dirty

[PATCH,RFC 2/2] Remove hint to use "git help -a"

[Theodore Ts'o]

The newbie user will run away screaming when they see all possible
commands.  The expert user will already know about the -a option from
reading the git man page.

Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
---
 help.c |    1 -
 1 files changed, 0 insertions(+), 1 deletions(-)

diff --git a/help.c b/help.c
index 1cd33ec..f539b80 100644
--- a/help.c
+++ b/help.c
@@ -162,7 +162,6 @@ static void list_common_cmds_help(void)
 		mput_char(' ', longest - strlen(common_cmds[i].name));
 		puts(common_cmds[i].help);
 	}
-	puts("(use 'git help -a' to get a list of all installed git commands)");
 }
 
 static void show_man_page(const char *git_cmd)
-- 
1.5.3.5.623.g91546-dirty

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Junio C Hamano]

Theodore Ts'o <tytso@mit.edu> writes:

> Remove apply, archive, cherry-pick, prune, revert, and show-branch, so
> "git help" is less intimidating.
>
> Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
>
> -apply
> -archive
> -prune
> -revert
> -show-branch

I am fine with this list, perhaps except apply.

On the other hand, if you are shooting *really* for the absolute
minimum set for the beginners, I would kill rm and possibly mv)
in addition to your list:

 - git-rm is always easier to do with "rm -fr file-or-dir",
   followed by "git commit -a".  Of course "git rm --cached" and
   partial commits that contain removal cannot be emulated
   easily this way, but this is an alternative suggestion to aim
   for *real* beginners who do not use the index.

 - git-mv is on my list for the same reason as "rm", but it is a
   bit more cumbersome if you want to move a directory, because
   "mv old new && git add new" would not work for people without
   a correctly set-up .gitignore (and if we are talking about
   beginners, we should expect user's .gitignore is borked).

I have a bit of reservation about revert, but I'd imagine we
could kill it, and also fetch, pull and push, if you are
shooting for *real* beginners who work alone.  I think the only
valid justification to drop "revert" from the list is to assume
that the audience do not interact with the outside world, and
dropping fetch/pull/push from the list is in line with that.

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Ping Yin]

> I have a bit of reservation about revert, but I'd imagine we
> could kill it, and also fetch, pull and push, if you are
> shooting for *real* beginners who work alone.  I think the only
> valid justification to drop "revert" from the list is to assume
> that the audience do not interact with the outside world, and
> dropping fetch/pull/push from the list is in line with that.
many "real" beginners are users of CVS/svn, so the very first thing
they want to do is simulating the cvs/svn operation, so IMHO pull
(update) and push(commit) should be kept.
>
>
>
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>



-- 
Ping Yin

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Theodore Tso]

On Sun, Nov 11, 2007 at 06:21:44PM -0800, Junio C Hamano wrote:
> Theodore Ts'o <tytso@mit.edu> writes:
> 
> > Remove apply, archive, cherry-pick, prune, revert, and show-branch, so
> > "git help" is less intimidating.
> >
> > Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
> >
> > -apply
> > -archive
> > -prune
> > -revert
> > -show-branch
> 
> I am fine with this list, perhaps except apply.

I was borderline on apply, but given that people are familiar with
patch -p1, the only real advantage git-apply has is that automatically
deals with new files (which "git commit -a" or "git add -u" won't
automatically get).

What did you think about cherry-pick?  Was that omitted by accident?

> On the other hand, if you are shooting *really* for the absolute
> minimum set for the beginners, I would kill rm and possibly mv)
> in addition to your list:

Those did cross my mind as well.  :-)

> I have a bit of reservation about revert, but I'd imagine we
> could kill it, and also fetch, pull and push, if you are
> shooting for *real* beginners who work alone.  I think the only
> valid justification to drop "revert" from the list is to assume
> that the audience do not interact with the outside world, and
> dropping fetch/pull/push from the list is in line with that.

My mental model for git newbies is that they would probably be pulling
from upstream repositories (so I was tempted to remove git-init from
the common commands list), but they would rarely be cherry-picking or
reverting other people's changes.

They probably would be submitting changes back upstream using e-mail
before they learn how to publish their own repository, so commands I'd
be tempted to add would include git-format-patch, git-send-email, and
git-cherry.  But these commands are pretty complicated for beginners....

	     	       		    	   - Ted

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> On Sun, Nov 11, 2007 at 06:21:44PM -0800, Junio C Hamano wrote:
> ...
>> I am fine with this list, perhaps except apply.
>
> I was borderline on apply, but given that people are familiar with
> patch -p1, the only real advantage git-apply has is that automatically
> deals with new files (which "git commit -a" or "git add -u" won't
> automatically get).

Although more importantly git-apply is much more strict and
safer than patch by default, that distinction will probably not
register with total newbies; not much would be lost if we do not
list git-apply, I'd guess.

> What did you think about cherry-pick?  Was that omitted by accident?

As "git show | git apply --index" would be good enough for
simple projects, omission of git-cherry-pick is not as serious
compared to ommission of git-revert, whose alternatives would be
"commit --amend" and "rebase" which are not suitable for
published history.

> My mental model for git newbies is that they would probably be pulling
> from upstream repositories (so I was tempted to remove git-init from
> the common commands list), but they would rarely be cherry-picking or
> reverting other people's changes.

I'd agree with that, but reverting and cherry-picking would also
be done on the commits the user builds on top of other people's
changes.

> They probably would be submitting changes back upstream using e-mail
> before they learn how to publish their own repository, so commands I'd
> be tempted to add would include git-format-patch, git-send-email, and
> git-cherry.  But these commands are pretty complicated for beginners....

I'd half agree with that.  People coming from CVS workflow will
be pushing and pulling from their central repositories, without
format-patch and send-email.  For them revert would matter more
together with fetch, rebase and push.

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Mike Hommey]

On Sun, Nov 11, 2007 at 11:26:10PM -0800, Junio C Hamano <gitster@pobox.com> wrote:
> > My mental model for git newbies is that they would probably be pulling
> > from upstream repositories (so I was tempted to remove git-init from
> > the common commands list), but they would rarely be cherry-picking or
> > reverting other people's changes.
> 
> I'd agree with that, but reverting and cherry-picking would also
> be done on the commits the user builds on top of other people's
> changes.

On the other hand, cherry-picking and reverting are just the same thing,
except one applies a reversed patch. Wouldn't it make sense to merge these
two in one command ?

Mike

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Johannes Schindelin]

Hi,

On Mon, 12 Nov 2007, Mike Hommey wrote:

> On Sun, Nov 11, 2007 at 11:26:10PM -0800, Junio C Hamano <gitster@pobox.com> wrote:
> > > My mental model for git newbies is that they would probably be pulling
> > > from upstream repositories (so I was tempted to remove git-init from
> > > the common commands list), but they would rarely be cherry-picking or
> > > reverting other people's changes.
> > 
> > I'd agree with that, but reverting and cherry-picking would also
> > be done on the commits the user builds on top of other people's
> > changes.
> 
> On the other hand, cherry-picking and reverting are just the same thing, 
> except one applies a reversed patch. Wouldn't it make sense to merge 
> these two in one command ?

Technically, they are.  That's why both of them live in builtin-revert.c.  
But conceptually, they are not.  At least _I_ found it hard at first, to 
accept that reverting a patch really was a reverse cherry-picking.

Ciao,
Dscho

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Ask Bjørn Hansen]

On Nov 11, 2007, at 10:22 PM, Theodore Tso wrote:

> They probably would be submitting changes back upstream using e-mail
> before they learn how to publish their own repository, so commands I'd
> be tempted to add would include git-format-patch, git-send-email, and
> git-cherry.  But these commands are pretty complicated for  
> beginners....

Maybe split it into sections?   I'm all for making it appear simpler,  
but not for hiding the power features of git too much.  :-)

"These are basic local commands"

"This is what you need to interact with a remote repository"

"This is what you need for branching and merging"

"This is what you need to make, manage and apply patches"


  - ask

-- 
http://develooper.com/ - http://askask.com/

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Andreas Ericsson]

Theodore Tso wrote:
> 
> They probably would be submitting changes back upstream using e-mail
> before they learn how to publish their own repository, so commands I'd
> be tempted to add would include git-format-patch, git-send-email, and
> git-cherry.  But these commands are pretty complicated for beginners....
> 

git format-patch could probably go in, but skip the others. I've never
used git cherry in my entire life and it's not, strictly speaking,
necessary for users to have it. There are other and easier ways to
find the same information.

I'd keep cherry-pick though. It's incredibly useful, and especially
when a commit ends up on the wrong branch which is something newbies
are likely to do when they start trying out the topic-branch workflow.
I still do it sometimes, but hardly ever stop thinking about it since
it's so easy to fix thanks to cherry-pick.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH,RFC 1/2] Make the list of common commands more exclusive

[Theodore Tso]

On Mon, Nov 12, 2007 at 11:21:34AM +0100, Andreas Ericsson wrote:
>
> git format-patch could probably go in, but skip the others. I've never
> used git cherry in my entire life and it's not, strictly speaking,
> necessary for users to have it. There are other and easier ways to
> find the same information.

How useful it is depends on the project, definitely.  The Linux kernel
doesn't have the "what's cooking" emails, and is very fast-moving, so
a day after you submit your patch set via e-mail, and then you do a
pull, and several hundred commits come spilling down from upstream,
git-cherry is incredibly useful to see what was accepted and what
wasn't.  :-)

> I'd keep cherry-pick though. It's incredibly useful, and especially
> when a commit ends up on the wrong branch which is something newbies
> are likely to do when they start trying out the topic-branch workflow.
> I still do it sometimes, but hardly ever stop thinking about it since
> it's so easy to fix thanks to cherry-pick.

How often cherry-pick is useful is probably also very project
specific, and depends on how branchy a project happens to be, and how
aggressively patches get merged into the master development line.  For
a project that is extremely linear, with few branches, cherry-pick is
less useful; I didn't have any occasion to use it for quite a while,
and certainly not while I was a git beginner.

							- Ted

Re: Deprecate git-fetch-pack?

[Andreas Ericsson]

Theodore Tso wrote:
> On Sun, Nov 11, 2007 at 10:50:26PM +0000, Johannes Schindelin wrote:
>> I beg to differ.  The biggest problem with a new user seeing all those 
>> completions is that this user is scared.
> 
> Well, if we introduce the new user only to "git subcomand", and the
> documentation is relatively gentle, I would suspect would solve most
> of the problem.  Note BTW, that if your thesis is true, "git help -a"
> (which is recommended in the last line of output by "git help") should
> cause the typical new user to faint dead away.  :-)
> 
> Some other areas that would be worth fixing, in terms of user usability.
> 
> 1) The references to the tutorial, everyday git, etc., don't actually
> have working references in the git man page.  (i.e., what you see when
> you run the command "man git").   It would be nice if that were fixed.
> 
> 2) The command which are displayed by "git help" should use some
> serious rethinking.  Ideally, it would be nice if the output fit in a
> single 24-line terminal window.   Some candidates for removal:
> 
>        a) prune: "git prune" definitely doesn't deserve to be on the
>        front and center as displayed by "git help".  Maybe replace it
>        with "gc", but now that we have gc.auto, I'm not sure it's
>        worth it at all.
> 

prune is definitely scary, and users don't need to know about it until
they've worked with git for quite some time.

>        b) revert:  Is that really that common of a command?
> 

I think I've used it once ;-)

>        c) show-branch: The output is terrifying without explanation
> 

Indeed. I still don't grok it fully. I tend to use gitk/qgit and some
brainpower to obtain the same result.


> There are other commands I'm not so sure about, but it is worth
> flagging them.  One way that might be helpful is to group the commands
> into subcommands, much like gdb does, so you could do something like
> "git help other-repos" (where all commands that involve interacting
> with other repositories are summarized), and so on.
> 

Ack on that. I suggested it a while back and it appears many liked the
idea. I'm really bad at writing docs though, so it's one of those things
I've been putting off for "some other day".


>> But yes, I was only proposing to deprecate all usage of git-<bla> in the 
>> documentation.
> 
> I agree that de-emphasizing git-<blah> isn't a bad thing.  But I think
> we need to look at the big picture here, since "git help" is often one
> of the first things a new user might try (and obviously very few git
> developers look at it, or "prune" probably would have been removed
> from git help a long time ago :-), and the last thing that git help
> suggests (and so therefore it will very visible to the newbie user),
> is "git help -a" --- and that displays every single git command under
> creation, porcelain or plumbing, in one gigantic sorted list.  
> 
> Oops, so much for first impressions.  :-)
> 

I agree. Culling the list output by "git help -a" to only show the
porcelain commands would definitely be worthwhile. I'm not sure if it's
worth having a way of showing every installed git command at all (I
know I've never used it anyway).

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: Deprecate git-fetch-pack?

[Ask Bjørn Hansen]

On Nov 11, 2007, at 2:50 PM, Johannes Schindelin wrote:

> I beg to differ.  The biggest problem with a new user seeing all those
> completions is that this user is scared.


How about moving the plumbing commands to libexec/ or some such?   (Or  
libexec/git/ - then you can put it back in your PATH if you really  
want easy access to run them directly).

Maybe I'm being pedantic, but it's not about "scaring the user" --  
it's simply that the "visible commands" is part of the UI and having  
it unnecessarily complex (many more commands than the user needs to  
learn) makes it much harder to get started using git.  It's a very  
practical thing.

I strongly second Theodore's suggestions for cleaning up some of the  
help texts, too.


  - ask

-- 
http://develooper.com/ - http://askask.com/

Re: Deprecate git-fetch-pack?

[Mike Hommey]

On Sat, Nov 10, 2007 at 04:48:29PM -0800, Junio C Hamano wrote:
> Daniel Barkalow <barkalow@iabervon.org> writes:
> 
> > Now that git-fetch is in C, built in, and doing the fetch-pack in the same 
> > process, the normal usage patterns don't involve actually executing 
> > git-fetch-pack. Can we deprecate it at this point, or it is plausibly 
> > being used by scripts? As it is now, I'm not entirely confidant that the 
> > tests in t5500 won't be fooled by git-fetch working even with 
> > git-fetch-pack being broken in various ways, which should be fixed if we 
> > want to keep it.
> >
> > We also might as well deprecate peek-remote now that it's a synonym for 
> > ls-remote.
> 
> Especially because git-fetch is no longer as hackable as it used
> to be, and because people may still find special needs that can
> be hacked up with direct access to low level transports from the
> script more easily than going down to the C level, I'd rather
> wait and see for a cycle or two to decide.  There is no strong
> reason to drop it, is there?

Still, if the functionality is needed, i think it would be better if it
were provided by git-fetch --pack. The list of programs is already long
enough, it should be time to shrink it.

Mike