login
Search
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* -
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. -
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 -
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/ -
Hi, 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 -
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. -
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 -
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, 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 -
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
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. ...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
-
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
-
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 -- Ping Yin -
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). 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 -
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 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 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 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 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, 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 -
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/ -
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 -
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 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 -
prune is definitely scary, and users don't need to know about it until Indeed. I still don't grok it fully. I tend to use gitk/qgit and some 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 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 -
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/ -
