Deprecate git-fetch-pack?

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*

Daniel Barkalow <barkalow@iabervon.org> writes:

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.

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

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

Hi,

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

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

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

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.

On Sun, Nov 11, 2007 at 01:16:09PM -0800, Junio C Hamano wrote:

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

Theodore Tso <tytso@mit.edu> writes:

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.

Hi,

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

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

On Sun, Nov 11, 2007 at 10:50:26PM +0000, Johannes Schindelin wrote:

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.

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

Theodore Tso wrote:

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

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

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

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

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

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

Thanks, jdl

Hi,

On Mon, 12 Nov 2007, Jon Loeliger wrote:

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, and those systems are the majority nowadays.  Oh, wait...

Ciao, Dscho

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

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

I remotely log into my server machines frequently.

Again, though, that is just my opinion.

jdl

Hi,

On Mon, 12 Nov 2007, Jon Loeliger 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.

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

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

And accepted.

Yes.

Thanks, jdl

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

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

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

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.

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.

On Sun, Nov 11, 2007 at 06:21:44PM -0800, Junio C Hamano wrote:

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?

Those did cross my mind as well.  :-)

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

Theodore Tso <tytso@mit.edu> writes:

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.

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.

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.

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.

On Sun, Nov 11, 2007 at 11:26:10PM -0800, Junio C Hamano <gitster@pobox.com> wrote:

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

Hi,

On Mon, 12 Nov 2007, Mike Hommey wrote:

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

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

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

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

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.

On Mon, Nov 12, 2007 at 11:21:34AM +0100, Andreas Ericsson wrote:

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

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

Theodore Tso wrote:

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

I think I've used it once ;-)

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

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

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

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

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

On Sat, Nov 10, 2007 at 04:48:29PM -0800, Junio C Hamano wrote:

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