[PATCH] Documentation: add a planning document for the next CLI revamp

[PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

From: Sam Vilain <samv@vilain.net>

For cross-command CLI changes to be effective, they need to be
cohesively planned.  Add a planning document for this next set of
changes.

Signed-off-by: Sam Vilain <sam@vilain.net>
---
 Some suggestions, which have been briefly scanned over by some of the
 (remaining @4pm) GitTogether attendees.

 Please keep it constructive! :)

 Documentation/cli-revamp.txt |  135 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 135 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/cli-revamp.txt

diff --git a/Documentation/cli-revamp.txt b/Documentation/cli-revamp.txt
new file mode 100644
index 0000000..980ea07
--- /dev/null
+++ b/Documentation/cli-revamp.txt
@@ -0,0 +1,135 @@
+GIT command line revamp
+=======================
+
+This design document is designed for review and critique over planned
+direction for changing the command set used by git, rather than
+reviewing and critiquing individual changes.
+
+In general, old commands will be grandfathered for a year or longer,
+and all plumbing commands will still work as originally designed.
+
+Please bear in mind when critiquing that each of these changes might
+themselves have a progressive implementation, for instance the new
+behaviour being optional initially.
+
+Please try to be positive with your comments; let's try to come up
+with solutions and not argue about the details of the solutions
+presented until those details are submitted.  In particular, critical
+comments that do not acknowledge the presence of a problem are
+worthless at this stage.
+
+Add/rm/reset/checkout/revert
+----------------------------
+
+Many find these confusing.
+
+  * 'git stage' would do what 'git add' does now.
+
+  * 'git unstage' would do what 'git reset --' does now
+
+  * 'git status' would encourage the user to use
+    'git diff --staged' to see staged changes as a patch
+
+  * 'git commit' with no changes should give useful information about
+    using 'git stage', 'git commit -a' or 'git commit filename ...'
+
+  * 'git add' and 'git rm': no change
+
+  * 'git update-index' considered plumbing, not changed
+
+  * 'git revert' deprecated in favour of 'git cherry-pick --revert'
+
+  * 'git undo' would do what 'git checkout HEAD --' does now
+
+  * 'git checkout branch' would, if there is a remote branch called
+    'branch' on exactly one remote, do what
+    'git checkout -b branch thatremote/branch' does now.  If it is
+    ambiguous, it would be an error, forcing the explicit notation.
+
+  * 'git branch --switch' : alternative to checkout
+
+
+Push/pull
+---------
+
+These commands are asymmetric, and this seems mostly historical.
+
+  * 'git push --matching' does what 'git push' does today (without
+    explicit configuration)
+
+  * 'git push' with no ref args and no 'push =' configuration does
+    what:
+    'git push origin $(git symbolic-ref HEAD | sed "s!refs/heads/!!")'
+    does today.  ie, it only pushes the current branch.
+    If a branch was defined in branch.<name>.push, push to that ref
+    instead of the matching one.  If there is no matching ref, and
+    there is a branch.<name>.merge, push back there.
+
+  * 'git pull' behaviour unchanged
+
+  * 'git push' to checked out branch of non-bare repository not
+    allowed without special configuration.  Configuration available
+    that allows working directory to be updated, known caveats
+    notwithstanding.  Ideally, it would refuse only in situations
+    where a broken working copy would be left (because you couldn't
+    fix it), and work when it can be known to be safe.
+
+
+Informational
+-------------
+
+  * 'git branch' should default to '--color=auto -v'
+
+  * 'git tag -l' should show more information
+
+
+Working with patches
+--------------------
+
+  * 'git send-email' should prompt for all SMTP-related information
+    about sending e-mail when it is running with no configuration.
+    Because these days /usr/lib/sendmail is rarely configured
+    correctly.
+
+  * other git send-email functionality which has bitten people -
+    particularly building the recipient list - should prompt for
+    confirmation until configured to be automatic.
+
+  * 'git am -3' the default; with global option to make it not the
+    default for those that prefer the speed of -2
+
+
+Submodules
+----------
+
+  * submodules should be able to refer to symbolic ref names, svn
+    style - in the .gitmodules file.  The actual commit used is still
+    recorded in the index.
+
+  * when switching branches, if the checked out revision of a submodule
+    changes, then it should be switched as well
+
+  * 'git submodule update' should be able to be triggered when
+    switching branches (but not be the default behaviour)
+
+
+Others
+------
+
+  * 'git export' command that does what
+    'git archive --format=tar --prefix=dir | tar x' does now
+
+  * conflicted merges should point the user immediately to
+    'git mergetool' and mention you need to use 'git stage' to mark
+    resolved files and 'git commit' when done.
+
+  * 'git init --server' (or similar) should do everything required for
+    exporting::
+----
+chmod -R a+rX
+touch git-daemon-export-ok
+git gc
+git update-server-info
+chmod u+x .git/hooks/post-update
+git config core.sharedrepository=1
+----
-- 
debian.1.5.6.1

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Stefan Karpinski]

These proposed changes look great.

On Wed, Oct 29, 2008 at 8:48 PM, Sam Vilain <sam@vilain.net> wrote:

> +  * 'git unstage' would do what 'git reset --' does now

Would it make sense to deprecate using "git reset --" for this then?
It's always seemed confusing to me to have such disparate
functionality in the reset command.

> +  * 'git export' command that does what
> +    'git archive --format=tar --prefix=dir | tar x' does now

It would be nice if the "git export" command could "checkout" a
non-repo copy of a remote repo at a specific version. This would be as
simple as calling archive on the remote size and then unarchiving it
locally. But would of course take care of all the plumbing.

(Sorry for the resend, Sam.)

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Kyle Moffett]

On Thu, Oct 30, 2008 at 6:55 AM, Stefan Karpinski
<stefan.karpinski@gmail.com> wrote:
> On Wed, Oct 29, 2008 at 8:48 PM, Sam Vilain <sam@vilain.net> wrote:
>> +  * 'git export' command that does what
>> +    'git archive --format=tar --prefix=dir | tar x' does now
>
> It would be nice if the "git export" command could "checkout" a
> non-repo copy of a remote repo at a specific version. This would be as
> simple as calling archive on the remote size and then unarchiving it
> locally. But would of course take care of all the plumbing.

I'm not sure whether the "git archive | tar" or the following is more efficient:

export GIT_INDEX_FILE="$(mktemp .git/export-index.XXXXXX)"
git read-tree -i "$1"
git checkout-index -f -a --prefix="$2/"

Cheers,
Kyle Moffett

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 3292 bytes --]

On Thu, Oct 30, 2008 at 03:48:05AM +0000, Sam Vilain wrote:
> +Add/rm/reset/checkout/revert
> +----------------------------
> +
> +Many find these confusing.
> +
> +  * 'git stage' would do what 'git add' does now.

  -> git stage -i/-p shall do what git add -i/-p does.

> +
> +  * 'git unstage' would do what 'git reset --' does now

  -> likely we need a git unstage -i/-p to interactively unstage some
     bits.

* 'git track' would do what git add -N does now.

* 'git untrack' would do what 'git rm --cached' does now.

> +  * 'git undo' would do what 'git checkout HEAD --' does now

I'm not really a fan of this one. Undo is too unspecific (I know at
least 2 people using that for git reset --hard HEAD~1 and 1 other for an
alias to git reset --hard HEAD@{1}).

I have no constructive proposal to replace it though, but I believe git
undo would cause lots of harm. Would it be for another command, it
wouldn't be a problem, but git undo *LOSES* information by design (the
local changes on a file), and it would override aliases that people
could have done on it. Choosing it has consequences.


> +Working with patches
> +--------------------
> +
> +  * 'git send-email' should prompt for all SMTP-related information
> +    about sending e-mail when it is running with no configuration.
> +    Because these days /usr/lib/sendmail is rarely configured
> +    correctly.

And when the user answer them, it should set them (a bit like zsh does
when it's run from the first time e.g.)

> +
> +  * other git send-email functionality which has bitten people -
> +    particularly building the recipient list - should prompt for
> +    confirmation until configured to be automatic.
> +

  * git-send-email should be either more interactive, or less: either
    just use the damn configuration, or propose a mode where it spawns
    an editor for each patch so that you can add further comments.

  * git-send-email should be able to format-patches by himself (IOW
    accept most of format-patch arguments and deal with the patch list
    by himself, which is usable if the previous point is implemented).

> +  * 'git am -3' the default; with global option to make it not the
> +    default for those that prefer the speed of -2
> +
> +
> +Submodules
> +----------
> +
> +  * submodules should be able to refer to symbolic ref names, svn
> +    style - in the .gitmodules file.  The actual commit used is still
> +    recorded in the index.
> +
> +  * when switching branches, if the checked out revision of a submodule
> +    changes, then it should be switched as well
> +
> +  * 'git submodule update' should be able to be triggered when
> +    switching branches (but not be the default behaviour)

Actually on this one, I'd say that a submodule is either non initialized
(in which case we don't care) or it is. If it is, switching branches
should probably trigger a submodule update if the switch isn't possible
(because the dereferenced sha1 doesn't exists). Or alternatively it
should make the whole branch switch fail.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Julian Phillips]

On Thu, 30 Oct 2008, Pierre Habouzit wrote:

> On Thu, Oct 30, 2008 at 03:48:05AM +0000, Sam Vilain wrote:
>> +Working with patches
>> +--------------------
>> +
>> +  * 'git send-email' should prompt for all SMTP-related information
>> +    about sending e-mail when it is running with no configuration.
>> +    Because these days /usr/lib/sendmail is rarely configured
>> +    correctly.
>
> And when the user answer them, it should set them (a bit like zsh does
> when it's run from the first time e.g.)
>
>> +
>> +  * other git send-email functionality which has bitten people -
>> +    particularly building the recipient list - should prompt for
>> +    confirmation until configured to be automatic.
>> +
>
>  * git-send-email should be either more interactive, or less: either
>    just use the damn configuration, or propose a mode where it spawns
>    an editor for each patch so that you can add further comments.
>
>  * git-send-email should be able to format-patches by himself (IOW
>    accept most of format-patch arguments and deal with the patch list
>    by himself, which is usable if the previous point is implemented).

This gets my vote ...

These are two of the reasons that I ended up ignoring git-send-email and 
writing my own replacement.  I found the whole format-patch/send-email 
dance too cumbersome and confusing - particularly for sending a single 
patch.  To send a single patch I ended up with the command:

git mail-commmits --edit HEAD~1

It would be nice if I could replace this with:

git send-email --edit HEAD~1

;)

>
>> +  * 'git am -3' the default; with global option to make it not the
>> +    default for those that prefer the speed of -2
>> +
>> +

-- 
Julian

  ---
Blessed be those who initiate lively discussions with the hopelessly mute,
for they shall be know as Dentists.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Thu, Oct 30, 2008 at 02:24:53PM +0100, Pierre Habouzit wrote:

> > +  * 'git stage' would do what 'git add' does now.
>   -> git stage -i/-p shall do what git add -i/-p does.

Yes, and that is obviously easy.

> > +  * 'git unstage' would do what 'git reset --' does now
>   -> likely we need a git unstage -i/-p to interactively unstage some
>      bits.

Agreed, though this is a bit harder. But I think this should go hand in
hand with "git stash -i" and "git stash apply -i" (as I mentioned in my
other mail in this thread).

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> * 'git track' would do what git add -N does now.
> * 'git untrack' would do what 'git rm --cached' does now.

Ok with me up to here.

>> +  * 'git undo' would do what 'git checkout HEAD --' does now
> ...
> I have no constructive proposal to replace it though, but I believe git
> undo would cause lots of harm.

I'm in agreement.

>   * git-send-email should be either more interactive, or less: either
>     just use the damn configuration, or propose a mode where it spawns
>     an editor for each patch so that you can add further comments.

In principle I'd agree, but I use send-email non-interactively myself (I
type Meta/SE where Meta is an independent checkout of my 'todo' branch),
so I am not sure if the "just use the configuration" is an added
requirement.  I also have this in .git/config in the repo:

        [sendemail]
                smtpserver = /usr/bin/msmtp
                to = git@vger.kernel.org
                suppressfrom
                signedoffcc = false

>   * git-send-email should be able to format-patches by himself (IOW
>     accept most of format-patch arguments and deal with the patch list
>     by himself, which is usable if the previous point is implemented).

I earlier was against this, mostly out of the "each tool to do the job it
was designed to do well" principle, but with your workflow description and
Peff's comment, I am open to add this kind of "run format-patch internally"
wrapper behaviour to send-email which is already a Porcelain anyway.

>> +  * 'git am -3' the default; with global option to make it not the
>> +    default for those that prefer the speed of -2

I am moderately negative on this, but not because of performance concern.

The --3way fall back is done only when it is necessary, and there is no
"prefer the speed" involved.  It is between "stop when the patch does not
apply because there may be something iffy going on" and "assume it is Ok
in such an iffy case to pretend that you apply the patch to the original
copy and cherry-pick the result to your updated tree".  IOW, it is a
safety concern.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1513 bytes --]

On Sun, Nov 02, 2008 at 09:53:44PM +0000, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> >   * git-send-email should be either more interactive, or less: either
> >     just use the damn configuration, or propose a mode where it spawns
> >     an editor for each patch so that you can add further comments.
> 
> In principle I'd agree, but I use send-email non-interactively myself (I
> type Meta/SE where Meta is an independent checkout of my 'todo' branch),
> so I am not sure if the "just use the configuration" is an added
> requirement.  I also have this in .git/config in the repo:
> 
>         [sendemail]
>                 smtpserver = /usr/bin/msmtp
>                 to = git@vger.kernel.org
>                 suppressfrom
>                 signedoffcc = false

Well with my patches it goes _more_ interactive on request only, so that
wouldn't break your setup (you have to explicitely pass --annotated
and/or --compose). Okay arguably not the feature that auto enables
--compose on series of more than 1 patch, but you can redirect
send-email to | cat or pass --no-compose for that. Or we can drop that
bit of the patch if people find it too cumbersome, I can put that in an
alias I don't really care.

I really _care_ about not breaking send-email for its previous uses.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Wed, 29 Oct 2008, Sam Vilain wrote:

> From: Sam Vilain <samv@vilain.net>
> 
> For cross-command CLI changes to be effective, they need to be
> cohesively planned.  Add a planning document for this next set of
> changes.
> 
> Signed-off-by: Sam Vilain <sam@vilain.net>
[...]

> +  * 'git checkout branch' would, if there is a remote branch called
> +    'branch' on exactly one remote, do what
> +    'git checkout -b branch thatremote/branch' does now.  If it is
> +    ambiguous, it would be an error, forcing the explicit notation.

I can't do otherwise but disagree with this.  Currently, when a remote 
branch is checked out, the commit corresponding to that remote branch is 
put on a detached head which is IMHO completely sane and coherent. It 
even tells you how to create a local branch from there if that's what 
you wanted to do.  So if it is still too confusing at that point then 
more explanations are needed and not the removal of a perfectly fine 
feature. Please don't change that behavior.


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Shawn O. Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> On Wed, 29 Oct 2008, Sam Vilain wrote:
> > From: Sam Vilain <samv@vilain.net>
> > 
> > For cross-command CLI changes to be effective, they need to be
> > cohesively planned.  Add a planning document for this next set of
> > changes.
> > 
> > Signed-off-by: Sam Vilain <sam@vilain.net>
> [...]
> 
> > +  * 'git checkout branch' would, if there is a remote branch called
> > +    'branch' on exactly one remote, do what
> > +    'git checkout -b branch thatremote/branch' does now.  If it is
> > +    ambiguous, it would be an error, forcing the explicit notation.
> 
> I can't do otherwise but disagree with this.  Currently, when a remote 
> branch is checked out, the commit corresponding to that remote branch is 
> put on a detached head which is IMHO completely sane and coherent. It 
> even tells you how to create a local branch from there if that's what 
> you wanted to do.  So if it is still too confusing at that point then 
> more explanations are needed and not the removal of a perfectly fine 
> feature. Please don't change that behavior.

+1 to Nico's NAK.

Although I was at the GitTogether I don't remember this change to
checkout being discussed.  I must have been asleep reading email
or something.  I am _NOT_ in favor of this change; I think the
current behavior of "git checkout origin/master" is correct and as
sane as we can make it.

-- 
Shawn.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Mike Hommey]

On Thu, Oct 30, 2008 at 07:52:53AM -0700, Shawn O. Pearce <spearce@spearce.org> wrote:
> Nicolas Pitre <nico@cam.org> wrote:
> > On Wed, 29 Oct 2008, Sam Vilain wrote:
> > > From: Sam Vilain <samv@vilain.net>
> > > 
> > > For cross-command CLI changes to be effective, they need to be
> > > cohesively planned.  Add a planning document for this next set of
> > > changes.
> > > 
> > > Signed-off-by: Sam Vilain <sam@vilain.net>
> > [...]
> > 
> > > +  * 'git checkout branch' would, if there is a remote branch called
> > > +    'branch' on exactly one remote, do what
> > > +    'git checkout -b branch thatremote/branch' does now.  If it is
> > > +    ambiguous, it would be an error, forcing the explicit notation.
> > 
> > I can't do otherwise but disagree with this.  Currently, when a remote 
> > branch is checked out, the commit corresponding to that remote branch is 
> > put on a detached head which is IMHO completely sane and coherent. It 
> > even tells you how to create a local branch from there if that's what 
> > you wanted to do.  So if it is still too confusing at that point then 
> > more explanations are needed and not the removal of a perfectly fine 
> > feature. Please don't change that behavior.
> 
> +1 to Nico's NAK.
> 
> Although I was at the GitTogether I don't remember this change to
> checkout being discussed.  I must have been asleep reading email
> or something.  I am _NOT_ in favor of this change; I think the
> current behavior of "git checkout origin/master" is correct and as
> sane as we can make it.

Except he was talking about 'git checkout branch', not 'git checkout
origin/branch'. And I would be fine with 'git checkout branch' doing
what 'git checkout -b branch $remote/branch' does if $remote is unique
(i.e. there is no other 'branch' branch in any other remote) and the
'branch' branch doesn't already exist.

Mike

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1165 bytes --]

On Thu, Oct 30, 2008 at 02:59:28PM +0000, Mike Hommey wrote:
> On Thu, Oct 30, 2008 at 07:52:53AM -0700, Shawn O. Pearce <spearce@spearce.org> wrote:
> > +1 to Nico's NAK.
> > 
> > Although I was at the GitTogether I don't remember this change to
> > checkout being discussed.  I must have been asleep reading email
> > or something.  I am _NOT_ in favor of this change; I think the
> > current behavior of "git checkout origin/master" is correct and as
> > sane as we can make it.
> 
> Except he was talking about 'git checkout branch', not 'git checkout
> origin/branch'. And I would be fine with 'git checkout branch' doing
> what 'git checkout -b branch $remote/branch' does if $remote is unique
> (i.e. there is no other 'branch' branch in any other remote) and the
> 'branch' branch doesn't already exist.

Seconded.

Having git-checkout $foo being a shorthand for git checkout -b $foo
origin/$foo when origin/$foo exists and $foo doesn't is definitely handy.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Thu, 30 Oct 2008, Pierre Habouzit wrote:

> On Thu, Oct 30, 2008 at 02:59:28PM +0000, Mike Hommey wrote:
> > On Thu, Oct 30, 2008 at 07:52:53AM -0700, Shawn O. Pearce <spearce@spearce.org> wrote:
> > > +1 to Nico's NAK.
> > > 
> > > Although I was at the GitTogether I don't remember this change to
> > > checkout being discussed.  I must have been asleep reading email
> > > or something.  I am _NOT_ in favor of this change; I think the
> > > current behavior of "git checkout origin/master" is correct and as
> > > sane as we can make it.
> > 
> > Except he was talking about 'git checkout branch', not 'git checkout
> > origin/branch'. And I would be fine with 'git checkout branch' doing
> > what 'git checkout -b branch $remote/branch' does if $remote is unique
> > (i.e. there is no other 'branch' branch in any other remote) and the
> > 'branch' branch doesn't already exist.
> 
> Seconded.
> 
> Having git-checkout $foo being a shorthand for git checkout -b $foo
> origin/$foo when origin/$foo exists and $foo doesn't is definitely handy.

No.  This is only the first step towards insanity.

In many cases origin/$foo == origin/master so this can't work in that 
case which is, after all, the common case.  Therefore I think this is 
wrong to add magic operations which are not useful for the common case 
and actively _hide_ how git actually works.  Not only will you have to 
explain how git works anyway for that common origin/master case, but 
you'll also have to explain why sometimes the magic works and sometimes 
not.  Please keep such convenience shortcuts for your own scripts and/or 
aliases.


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 12:53 -0400, Nicolas Pitre wrote:
> > Seconded.
> > 
> > Having git-checkout $foo being a shorthand for git checkout -b $foo
> > origin/$foo when origin/$foo exists and $foo doesn't is definitely handy.
> 
> No.  This is only the first step towards insanity.
> 
> In many cases origin/$foo == origin/master so this can't work in that 
> case which is, after all, the common case.

I don't understand that argument at all, can you explain further?

>   Therefore I think this is 
> wrong to add magic operations which are not useful for the common case 
> and actively _hide_ how git actually works.  Not only will you have to 
> explain how git works anyway for that common origin/master case, but 
> you'll also have to explain why sometimes the magic works and sometimes 
> not.  Please keep such convenience shortcuts for your own scripts and/or 
> aliases.

It's not about magic, it's about sensible defaults.  Currently this use
case is an error, and the resultant command is very long to type, and
involves typing the branch name twice.  I end up writing things like:

  git checkout -b {,origin/}wr34251-do-something

For the user who doesn't know to use the ksh-style {} blocks this is
voodoo.  The longer form is cumbersome.

For the case where the thing you type is a resolvable reference, it
would just check it out, as now.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Thu, 30 Oct 2008, Sam Vilain wrote:

> On Thu, 2008-10-30 at 12:53 -0400, Nicolas Pitre wrote:
> > > Seconded.
> > > 
> > > Having git-checkout $foo being a shorthand for git checkout -b $foo
> > > origin/$foo when origin/$foo exists and $foo doesn't is definitely handy.
> > 
> > No.  This is only the first step towards insanity.
> > 
> > In many cases origin/$foo == origin/master so this can't work in that 
> > case which is, after all, the common case.
> 
> I don't understand that argument at all, can you explain further?

By default, git creates a branch called "master.  Hence, by default, if 
you clone that repository, this branch will be called origin/master.  So 
by default $foo is already ambiguous.

> >   Therefore I think this is 
> > wrong to add magic operations which are not useful for the common case 
> > and actively _hide_ how git actually works.  Not only will you have to 
> > explain how git works anyway for that common origin/master case, but 
> > you'll also have to explain why sometimes the magic works and sometimes 
> > not.  Please keep such convenience shortcuts for your own scripts and/or 
> > aliases.
> 
> It's not about magic, it's about sensible defaults.  Currently this use
> case is an error, and the resultant command is very long to type, and
> involves typing the branch name twice.  I end up writing things like:
> 
>   git checkout -b {,origin/}wr34251-do-something
> 
> For the user who doesn't know to use the ksh-style {} blocks this is
> voodoo.  The longer form is cumbersome.

This is no excuse for promoting semantics only useful in such special 
cases.

> For the case where the thing you type is a resolvable reference, it
> would just check it out, as now.

As long as it checks it out with a detached head if it is a remote 
branch then I have no issue.


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Yann Dirson]

On Thu, Oct 30, 2008 at 02:28:35PM -0400, Nicolas Pitre wrote:
> > It's not about magic, it's about sensible defaults.  Currently this use
> > case is an error, and the resultant command is very long to type, and
> > involves typing the branch name twice.  I end up writing things like:
> > 
> >   git checkout -b {,origin/}wr34251-do-something
> > 
> > For the user who doesn't know to use the ksh-style {} blocks this is
> > voodoo.  The longer form is cumbersome.
> 
> This is no excuse for promoting semantics only useful in such special 
> cases.

It is really not so rare to have an upstream repo with branches such
as "stable", "next" and the like.  This syntax extension would make is
as straightforward to work on "stable" as it is on remote HEAD
(usually master, which has already been magically setup for you).


BTW this use case reminds me that the remote HEAD has its own special
treatment for "clone", which AFAIK cannot be overriden from
command-line (I still sometimes lack what cogito provided as "cg clone
URL#branch").


> As long as it checks it out with a detached head if it is a remote 
> branch then I have no issue.

Yes it is possible, but that does not necessarily make a UI
improvement worthless.

Best regards,
-- 
Yann

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 14:28 -0400, Nicolas Pitre wrote:
> > For the case where the thing you type is a resolvable reference, it
> > would just check it out, as now.
> As long as it checks it out with a detached head if it is a remote 
> branch then I have no issue.

Absolutely - if you've already got a branch "master", then
"git checkout master" should definitely give it to you.  If you go
"git checkout origin/master", you get a floating head.  But I quite often
find myself wanting to check out a remote branch, and give it a name just
like on the remote.  I want "git checkout blah" to assume that's
what I mean, until I make a local branch "blah".

> By default, git creates a branch called "master.  Hence, by default, if 
> you clone that repository, this branch will be called origin/master.  So 
> by default $foo is already ambiguous.

Right - 'master' in this case resolves to something.  The ambiguity is
resolved by defaulting to the thing that resolves.  The fall-back
behaviour is only triggered if you asked for something that is currently
an error.  Because breaking expectations sucks.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jakub Narebski]

Sam Vilain wrote:

> It's not about magic, it's about sensible defaults.  Currently this use
> case is an error, and the resultant command is very long to type, and
> involves typing the branch name twice.  I end up writing things like:
> 
>   git checkout -b {,origin/}wr34251-do-something

Can't you use currently

    git checkout --track origin/wr34251-do-something


P.S. Somehow I don't see first message in this thread on GMane...
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Fri, 2008-10-31 at 00:55 +0100, Jakub Narebski wrote:
> > involves typing the branch name twice.  I end up writing things like:
> > 
> >   git checkout -b {,origin/}wr34251-do-something
> 
> Can't you use currently
> 
>     git checkout --track origin/wr34251-do-something

Ah, that's a new feature.  Still, I think it's poorly Huffman coded; far
too verbose.

But let's resume this discussion after I dig up the old thread about
pushing and pulling too... I think it makes sense to look at this as a
whole.

Cheers,
Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jakub Narebski]

Dnia piątek 31. października 2008 07:51, Sam Vilain napisał:
> On Fri, 2008-10-31 at 00:55 +0100, Jakub Narebski wrote:

> > > involves typing the branch name twice.  I end up writing things like:
> > > 
> > >   git checkout -b {,origin/}wr34251-do-something
> > 
> > Can't you use currently
> > 
> >     git checkout --track origin/wr34251-do-something
> 
> Ah, that's a new feature.  Still, I think it's poorly Huffman coded; far
> too verbose.

Well, either you have a little bit more verbose, or you have to have
some DWIM-mery, which (as usual with DWIM) can go wrong.

-- 
Jakub Narebski
Poland

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Fri, 2008-10-31 at 08:36 +0100, Jakub Narebski wrote:
> > >     git checkout --track origin/wr34251-do-something
> > 
> > Ah, that's a new feature.  Still, I think it's poorly Huffman coded; far
> > too verbose.
> 
> Well, either you have a little bit more verbose, or you have to have
> some DWIM-mery, which (as usual with DWIM) can go wrong.

That's right, you need to choose when to assume that the user meant
something that they didn't write very carefully.

But look at this:

  git checkout origin/master

  git checkout -t origin/master

The option is called "--track", yet in this case what it actually means
in the default situation where you have autosetupmerge (or whatever it's
really called) set to true, is that it modifies the command to imply "-b
master".  So, in this situation, that is clearly what was meant.

Perhaps you can give an example of why this particular piece of DWIM
might not be WYM?

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jakub Narebski]

Dnia poniedziałek 3. listopada 2008 09:43, Sam Vilain napisał:
> On Fri, 2008-10-31 at 08:36 +0100, Jakub Narebski wrote:

> > > >     git checkout --track origin/wr34251-do-something
> > > 
> > > Ah, that's a new feature.  Still, I think it's poorly Huffman coded; far
> > > too verbose.
> > 
> > Well, either you have a little bit more verbose, or you have to have
> > some DWIM-mery, which (as usual with DWIM) can go wrong.
> 
> That's right, you need to choose when to assume that the user meant
> something that they didn't write very carefully.
> 
> But look at this:
> 
>   git checkout origin/master
> 
>   git checkout -t origin/master
> 
> The option is called "--track", yet in this case what it actually means
> in the default situation where you have autosetupmerge (or whatever it's
> really called) set to true, is that it modifies the command to imply "-b
> master".  So, in this situation, that is clearly what was meant.
> 
> Perhaps you can give an example of why this particular piece of DWIM
> might not be WYM?

I was not talking about "git checkout -t origin/master" being shortcut
for "git checkout -b master -t origin/master", but about proposed
DWIM-mery for "git checkout -b <branch>" which would be

                             { git checkout -b <branch> -t <remote>/<branch>
  git checkout -b <branch> = {        if there exists <remote>/<branch> 
                             {
                             { git checkout -b <branch> HEAD
                             {        otherwise
-- 
Jakub Narebski
Poland

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Johannes Schindelin]

Hi,

On Thu, 30 Oct 2008, Pierre Habouzit wrote:

> On Thu, Oct 30, 2008 at 02:59:28PM +0000, Mike Hommey wrote:
> > On Thu, Oct 30, 2008 at 07:52:53AM -0700, Shawn O. Pearce <spearce@spearce.org> wrote:
> > > +1 to Nico's NAK.
> > > 
> > > Although I was at the GitTogether I don't remember this change to
> > > checkout being discussed.  I must have been asleep reading email
> > > or something.  I am _NOT_ in favor of this change; I think the
> > > current behavior of "git checkout origin/master" is correct and as
> > > sane as we can make it.
> > 
> > Except he was talking about 'git checkout branch', not 'git checkout
> > origin/branch'. And I would be fine with 'git checkout branch' doing
> > what 'git checkout -b branch $remote/branch' does if $remote is unique
> > (i.e. there is no other 'branch' branch in any other remote) and the
> > 'branch' branch doesn't already exist.
> 
> Seconded.
> 
> Having git-checkout $foo being a shorthand for git checkout -b $foo
> origin/$foo when origin/$foo exists and $foo doesn't is definitely handy.

Have you guys actually checked out what

	git checkout -t origin/foo

does?

Ciao,
Dscho

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Wed, Oct 29, 2008 at 08:48:05PM -0700, Sam Vilain wrote:
> From: Sam Vilain <samv@vilain.net>
> 
> For cross-command CLI changes to be effective, they need to be
> cohesively planned.  Add a planning document for this next set of
> changes.

Here are my favorites:

* Add the command "git revert-file <files>" which is syntactic sugar for:

        git checkout HEAD -- <files>

  Rationale: Many other SCM's have a way of undoing local edits to a
  file very simply, i.e."hg revert <file>" or "svn revert <file>", and
  for many developers's workflow, it's useful to be able to undo local
  edits to a single file, but not to everything else in the working
  directory.  And "git checkout HEAD -- <file>" is rather cumbersome
  to type, and many beginning users don't find it intuitive to look in
  the "git-checkout" man page for instructions on how to revert a
  local file.

* Change the argument handling for "git format-patch" so it is
  consistent with everything else which takes a set of commits.  Yes,
  it means that where people have gotten used to typing "git
  format-patch origin", they'll have to type instead: "git
  format-patch origin..", but's much more consistent.  We've done the
  best we can by documenting the existing behavior, but if'we re going
  to make major, potentially incompatible, CLI changes, this is
  something to at least consider.  Maybe with a config file for people
  who really don't want to retrain their fingers to type the two extra
  periods?

						- Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2159 bytes --]

On Thu, Oct 30, 2008 at 02:39:18PM +0000, Theodore Tso wrote:
> On Wed, Oct 29, 2008 at 08:48:05PM -0700, Sam Vilain wrote:
> > From: Sam Vilain <samv@vilain.net>
> > 
> > For cross-command CLI changes to be effective, they need to be
> > cohesively planned.  Add a planning document for this next set of
> > changes.
> 
> Here are my favorites:
> 
> * Add the command "git revert-file <files>" which is syntactic sugar for:
> 
>         git checkout HEAD -- <files>
> 
>   Rationale: Many other SCM's have a way of undoing local edits to a
>   file very simply, i.e."hg revert <file>" or "svn revert <file>", and
>   for many developers's workflow, it's useful to be able to undo local
>   edits to a single file, but not to everything else in the working
>   directory.  And "git checkout HEAD -- <file>" is rather cumbersome
>   to type, and many beginning users don't find it intuitive to look in
>   the "git-checkout" man page for instructions on how to revert a
>   local file.

This is what is currently proposed for undo, but yeah, revert-file or
maybe rather revert-changes may be suitable.

> * Change the argument handling for "git format-patch" so it is
>   consistent with everything else which takes a set of commits.  Yes,
>   it means that where people have gotten used to typing "git
>   format-patch origin", they'll have to type instead: "git
>   format-patch origin..", but's much more consistent.  We've done the
>   best we can by documenting the existing behavior, but if'we re going
>   to make major, potentially incompatible, CLI changes, this is
>   something to at least consider.  Maybe with a config file for people
>   who really don't want to retrain their fingers to type the two extra
>   periods?

git format-patch origin/next.. works already. I'm used to the asymetric
git format-patch origin/next syntax, and I would be sorry if it
disappeared though, and I see no really good reason to get rid of it.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Thu, Oct 30, 2008 at 03:43:21PM +0100, Pierre Habouzit wrote:
> 
> git format-patch origin/next.. works already. I'm used to the asymetric
> git format-patch origin/next syntax, and I would be sorry if it
> disappeared though, and I see no really good reason to get rid of it.

The reason why it annoys me is because I often what to cherry-pick a
single patch to send to someone, and so while "git show 332d2e78"
shows me the patch, but if I want to use git-send-email for that
particular patch, "git format-patch 332d2e78" doesn't DTRT.  I have to
type "git format-patch 332d2e78^..332d2e78" instead.  I've learned to
live with it, but it's annoying each time I have to do it.

More generally, the fact that the CLI has different ways the same set
of arguments can be decoded can be quite confusing.  The most obvious
way this turns up is to consider which set of commits are
displayed/formatted via these three commands:

   git format-patch 332d2e78
   git show 332d2e78
   git log -p 332d2e78

The first formats all patches that follow commit 332d2e78 (not
including commit 332d2e78), the second shows just commit 332d2e78, and
the last prints all commits starting at 332d2e78 and before it.

For many workflows, the default way a single commit-id is interpreted
makes a lot of sense.  But for a newcomer, it's very confusing.  I'm
not saying that we should collapse everything down to a single way of
doing things, but git format-patch is an exception, and I don't think
anything else actually works that way; looking at the man page makes
it clear that it treats its argument as a revision range EXCEPT when
only a single commit is specified.

It can be justified, and maybe it's convenient enough that this is one
of those places where tutorials should just explicitly call this out
as one of those exceptions that make sense given common workflows.
But just as English can be heard to learn because "though", "through",
"plough", "cough", and "tough" don't rhyme even though they look like
they should (even though native speakers have no problem with it),
similarly this is one of those inconsistencies that makes git hard to
learn.  

(And I get annoyed when I want to run git format-patch on a single
patch not at the tip of the tree; but if it's just me, I can write a
"git format-single-patch" wrapper script to get around it.)

     	      	       		     	    	 - Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1370 bytes --]

On Thu, Oct 30, 2008 at 04:30:56PM +0000, Theodore Tso wrote:
> On Thu, Oct 30, 2008 at 03:43:21PM +0100, Pierre Habouzit wrote:
> > 
> > git format-patch origin/next.. works already. I'm used to the asymetric
> > git format-patch origin/next syntax, and I would be sorry if it
> > disappeared though, and I see no really good reason to get rid of it.
> 
> The reason why it annoys me is because I often what to cherry-pick a
> single patch to send to someone, and so while "git show 332d2e78"
> shows me the patch, but if I want to use git-send-email for that
> particular patch, "git format-patch 332d2e78" doesn't DTRT.  I have to
> type "git format-patch 332d2e78^..332d2e78" instead.  I've learned to
> live with it, but it's annoying each time I have to do it.
[...]
> (And I get annoyed when I want to run git format-patch on a single
> patch not at the tip of the tree; but if it's just me, I can write a
> "git format-single-patch" wrapper script to get around it.)

In fact I believe that what we lack is a shorthand for:

$sha1^..$sha1 because that would solve both of your issues, and it's
something that has bothered me in the past too for other commands.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 17:43 +0100, Pierre Habouzit wrote:
> In fact I believe that what we lack is a shorthand for:
> 
> $sha1^..$sha1 because that would solve both of your issues, and it's
> something that has bothered me in the past too for other commands.

There is already a shorthand for that;

  $sha1^!

Indeed passing that to git-format-patch has the intended effect; it
causes it to save a patch for just the commit in question.

I agree that it would make more sense for the current behaviour to be
changed;

  git format-patch origin/master..

Isn't that much more to type than:

  git format-patch origin/master

And it makes the case where you just want to format a single patch work
better.

However, I worry about the backwards incompatibility.  The other changes
I listed didn't really violate existing expectations.

That being said, the case where a single commit reference is passed,
with no range, should be relatively easy to detect.  In this situation
it could return an error, and encourage the user to use "--since" or
"--only"; or to configure one of those to be the default.

I'm wondering whether it's worth building some kind of mechanism to
notice that settings like this have not been set, and to print a warning
like "warning: you are using a git that introduced minor command
changes; use 'git config --new' to pick your defaults" - that way,
changes to command operation could be introduced that would not annoy
older users so much.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Thu, 30 Oct 2008, Theodore Tso wrote:

> On Thu, Oct 30, 2008 at 03:43:21PM +0100, Pierre Habouzit wrote:
> > 
> > git format-patch origin/next.. works already. I'm used to the asymetric
> > git format-patch origin/next syntax, and I would be sorry if it
> > disappeared though, and I see no really good reason to get rid of it.
> 
> The reason why it annoys me is because I often what to cherry-pick a
> single patch to send to someone, and so while "git show 332d2e78"
> shows me the patch, but if I want to use git-send-email for that
> particular patch, "git format-patch 332d2e78" doesn't DTRT.  I have to
> type "git format-patch 332d2e78^..332d2e78" instead.

try:

	git show --pretty=email 332d2e78


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> On Thu, Oct 30, 2008 at 03:43:21PM +0100, Pierre Habouzit wrote:
>> 
>> git format-patch origin/next.. works already. I'm used to the asymetric
>> git format-patch origin/next syntax, and I would be sorry if it
>> disappeared though, and I see no really good reason to get rid of it.
>
> The reason why it annoys me is because I often what to cherry-pick a
> single patch to send to someone, and so while "git show 332d2e78"
> shows me the patch, but if I want to use git-send-email for that
> particular patch, "git format-patch 332d2e78" doesn't DTRT.  I have to
> type "git format-patch 332d2e78^..332d2e78" instead.
> ...
> (And I get annoyed when I want to run git format-patch on a single
> patch not at the tip of the tree; but if it's just me, I can write a
> "git format-single-patch" wrapper script to get around it.)

Huh?  I am so used to "git format-patch -1 HEAD" (or "332d2e78") that I am
very surprised.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Sat, Nov 01, 2008 at 11:08:06PM -0700, Junio C Hamano wrote:
> > (And I get annoyed when I want to run git format-patch on a single
> > patch not at the tip of the tree; but if it's just me, I can write a
> > "git format-single-patch" wrapper script to get around it.)
> 
> Huh?  I am so used to "git format-patch -1 HEAD" (or "332d2e78") that I am
> very surprised.

Well, the explanation is that "-<n>" isn't in the SYNPOSIS section of
'git format-patch', and so I never knew you could do it that way.  A
new user of git has to paw through approximately 50 options in the
OPTIONS section of the man page before finding "-<n>"; and somehow
I've always missed it.  I'd suggest adding an explicit mention of -<n>
to the DESCRIPTION section, perhaps in the paragraph:

   A single commit, when interpreted as a <revision range> expression,
   means "everything that leads to that commit", but if you write git
   format-patch <commit>, the previous rule applies to that command
   line and you do not get "everything since the beginning of the
   time". If you want to format everything since project inception to
   one commit, say "git format-patch --root <commit>" to make it clear
   that it is the latter case.

Adding the sentence:

   If you want to format a single commit, you can do this via 
   "git format-patch -1 <commit>" or the more esoteric and perl-ish,
   "git format-patch <commit>^!"

might be helpful.

						- Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Andreas Ericsson]

Theodore Tso wrote:
> On Wed, Oct 29, 2008 at 08:48:05PM -0700, Sam Vilain wrote:
>> From: Sam Vilain <samv@vilain.net>
>>
>> For cross-command CLI changes to be effective, they need to be
>> cohesively planned.  Add a planning document for this next set of
>> changes.
> 
> Here are my favorites:
> 
> * Add the command "git revert-file <files>" which is syntactic sugar for:
> 
>         git checkout HEAD -- <files>
> 
>   Rationale: Many other SCM's have a way of undoing local edits to a
>   file very simply, i.e."hg revert <file>" or "svn revert <file>", and
>   for many developers's workflow, it's useful to be able to undo local
>   edits to a single file, but not to everything else in the working
>   directory.  And "git checkout HEAD -- <file>" is rather cumbersome
>   to type, and many beginning users don't find it intuitive to look in
>   the "git-checkout" man page for instructions on how to revert a
>   local file.
> 

I like it, although I guess one would have to add a "--staged" flag to
git revert-file to be able to checkout files from index as well, or people
will wonder why that can't be done.

> * Change the argument handling for "git format-patch" so it is
>   consistent with everything else which takes a set of commits.  Yes,
>   it means that where people have gotten used to typing "git
>   format-patch origin", they'll have to type instead: "git
>   format-patch origin..", but's much more consistent.  We've done the
>   best we can by documenting the existing behavior, but if'we re going
>   to make major, potentially incompatible, CLI changes, this is
>   something to at least consider.  Maybe with a config file for people
>   who really don't want to retrain their fingers to type the two extra
>   periods?
> 

"git format-patch" does exactly the same thing as other commit-range handling
commands do, which is assume that the missing commit end-point is HEAD, so it
actually is consistent, although it doesn't quite look as if it is.

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

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

Hi,

On Thu, Oct 30, 2008 at 9:02 AM, Andreas Ericsson <ae@op5.se> wrote:
> I like it, although I guess one would have to add a "--staged" flag to
> git revert-file to be able to checkout files from index as well, or people
> will wonder why that can't be done.

Ew.  'git revert-file --staged foo'?  If you want to revert the
*unstaged* changes of a file, it should be 'git revert-file --unstaged
foo'.
I would expect 'git revert-file --staged foo' to revert the staged
changes in foo, i.e. it should do what 'git reset -- foo' does (except
that it should also work for the initial commit).  Thus, there'd be
little need for a --staged flag to revert-file, unless we allowed
reverting individual files back to some revision prior to HEAD (like
bzr and hg do)...

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Matthieu Moy]

Theodore Tso <tytso@mit.edu> writes:

> * Add the command "git revert-file <files>" which is syntactic sugar for:
>
>         git checkout HEAD -- <files>

I don't think "revert-file" is a good name for this: although other
SCM often call this "revert", what Git calls "revert" is about
reverting an existing commit (it's "backout" in hg for example). The
terminology to revert the working tree to the last commited version is
already here in Git, it's "reset".

I've already argued in favor of allowing "git reset --hard <files>",
which is consistant with existing terminology and doesn't add an extra
command, but without success.

-- 
Matthieu

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Thu, 30 Oct 2008, Matthieu Moy wrote:

> I've already argued in favor of allowing "git reset --hard <files>",
> which is consistant with existing terminology and doesn't add an extra
> command, but without success.

If you have a file argument, the --hard option is redundant, isn't it?
So what about simply "git reset <file>" ?


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 744 bytes --]

On Thu, Oct 30, 2008 at 05:00:18PM +0000, Nicolas Pitre wrote:
> On Thu, 30 Oct 2008, Matthieu Moy wrote:
> 
> > I've already argued in favor of allowing "git reset --hard <files>",
> > which is consistant with existing terminology and doesn't add an extra
> > command, but without success.
> 
> If you have a file argument, the --hard option is redundant, isn't it?
> So what about simply "git reset <file>" ?

errrrm, git reset <file> resets the index notion of the file to its status
in HEAD... which I'm sure is *somehow* useful to "some" people ;P

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Nicolas Pitre]

On Thu, 30 Oct 2008, Pierre Habouzit wrote:

> On Thu, Oct 30, 2008 at 05:00:18PM +0000, Nicolas Pitre wrote:
> > On Thu, 30 Oct 2008, Matthieu Moy wrote:
> > 
> > > I've already argued in favor of allowing "git reset --hard <files>",
> > > which is consistant with existing terminology and doesn't add an extra
> > > command, but without success.
> > 
> > If you have a file argument, the --hard option is redundant, isn't it?
> > So what about simply "git reset <file>" ?
> 
> errrrm, git reset <file> resets the index notion of the file to its status
> in HEAD... which I'm sure is *somehow* useful to "some" people ;P

Too bad...


Nicolas

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 13:17 -0400, Nicolas Pitre wrote:
> > errrrm, git reset <file> resets the index notion of the file to its status
> > in HEAD... which I'm sure is *somehow* useful to "some" people ;P
> 
> Too bad...

The changes need to not unnecessarily break scripts or let down people's
expectations.  I'd be happy to deprecate the use of reset with file
arguments, to keep 'reset' focused on resetting the current HEAD and not
concerned with files; but changing its behaviour on a subtle level like
this is sure to annoy...

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> On Thu, Oct 30, 2008 at 05:00:18PM +0000, Nicolas Pitre wrote:
>
>> If you have a file argument, the --hard option is redundant, isn't it?
>> So what about simply "git reset <file>" ?
>
> errrrm, git reset <file> resets the index notion of the file to its status
> in HEAD... which I'm sure is *somehow* useful to "some" people ;P

I'd agree that 'reset' is rather unfortunate.  It very originally was all
about the index (the "mixed" semantics, specifically "git reset" without
any committish nor any pathspec, was the original use case) and nothing
else.  IOW, "I staged a wrong change, let's start over by discarding all
staged changes".  A logical extension to it is "git reset -- pathspec",
IOW, "I know which paths I fubared, please reset only these paths, as
other staged changes are Ok".

So "reset <file>" is very much useful.

Then 'reset' learned to also muck with HEAD, so "reset HEAD^" (still
mixed, without any pathspec) can be used to amend the latest commit but
without losing the state you would eventually want to arrive at.  A
logical extension to this was "git reset --hard HEAD^" to nuking instead
of amending the mistake, and "git reset --soft HEAD^" to save the trouble
of staging the changes when the mistake you are fixing is small compared
to the entire change.

"checkout [$committish] $path" came much later, and the command is all
about index and files, and never about resetting HEAD.  "checkout $path"
does "reset --hard $path" (notice there is no $committish in either one)
would have done, so we stopped enhancing the "reset" command in that
direction.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Sun, 2008-11-02 at 14:17 -0800, Junio C Hamano wrote:
> I'd agree that 'reset' is rather unfortunate.  It very originally was all
> about the index (the "mixed" semantics, specifically "git reset" without
> any committish nor any pathspec, was the original use case) and nothing
> else.  IOW, "I staged a wrong change, let's start over by discarding all
> staged changes".  A logical extension to it is "git reset -- pathspec",
> IOW, "I know which paths I fubared, please reset only these paths, as
> other staged changes are Ok".
> 
> So "reset <file>" is very much useful.
> 
> Then 'reset' learned to also muck with HEAD, so "reset HEAD^" (still
> mixed, without any pathspec) can be used to amend the latest commit but
> without losing the state you would eventually want to arrive at.  A
> logical extension to this was "git reset --hard HEAD^" to nuking instead
> of amending the mistake, and "git reset --soft HEAD^" to save the trouble
> of staging the changes when the mistake you are fixing is small compared
> to the entire change.
> 
> "checkout [$committish] $path" came much later, and the command is all
> about index and files, and never about resetting HEAD.  "checkout $path"
> does "reset --hard $path" (notice there is no $committish in either one)
> would have done, so we stopped enhancing the "reset" command in that
> direction.

Interesting.

I'm wondering whether the important thing here is not making a new
command, but simply deprecating "revert", and pointing the user to "git
reset" - then making sure that you can do everything revert-like (eg, as
Elijah points out) from that command.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

Hi,

On Thu, Oct 30, 2008 at 9:20 AM, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:
> Theodore Tso <tytso@mit.edu> writes:
>
>> * Add the command "git revert-file <files>" which is syntactic sugar for:
>>
>>         git checkout HEAD -- <files>
>
> I don't think "revert-file" is a good name for this: although other
> SCM often call this "revert", what Git calls "revert" is about
> reverting an existing commit (it's "backout" in hg for example). The
> terminology to revert the working tree to the last commited version is
> already here in Git, it's "reset".

git's reset is _not_ the same as svn/bzr/hg's revert; and it's overlap
in functionality is smaller than you realize.

> I've already argued in favor of allowing "git reset --hard <files>",
> which is consistant with existing terminology and doesn't add an extra
> command, but without success.

Such a command would
  * delete newly added files instead of simply untracking them.
That's the right thing for reset, but not for a svn/bzr/hg-like revert
(and unfortunately means unintended data loss.)
  * doesn't make sense during an incomplete merge, unless you add some
way of specifying which branch users want to revert their files back
to.  Aren't there enough confusing flags for reset already?  (One
surprisingly common comment I get about eg is that git reset is too
hard to understand and eg reset fixes it -- despite the fact that I
merely renamed two flags and hid the second form of the command.)
  * doesn't work for the initial commit
  * provides no way to revert files or subdirectories back to their
state at some previous revision (hg and bzr revert have a flag to
provide this; it's not useful all the time but is on occasion)  Also,
if users try to modify their command slightly to get such behavior,
say 'git reset --hard REVISION' instead of 'git reset --hard .', then
they're in trouble.  (Recoverable, but they need an 'expert' to help
them now.)


Also, there's three different kinds of "undo": switching to an old
revision (git checkout REVISION, or svn/hg update -r, etc.),
forgetting or discarding commits/merges/rebases (git reset), and
modifying files to undo previous modifications without touching HEAD
(svn/bzr/hg revert).  Users get confused enough between these
different kinds of undo; overloading them further would be really bad,
IMO.

(Part of the reason for users getting confused between these kinds of
undo is the fact that git doesn't implemented svn/bzr/hg-like revert,
and tends to steer them towards git checkout and git reset, which are
commands typically meant for the *other* kinds of undo.)


Just my $0.02,
Elijah

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 10:39 -0400, Theodore Tso wrote:
> * Add the command "git revert-file <files>" which is syntactic sugar for:
> 
>         git checkout HEAD -- <files>
> 
>   Rationale: Many other SCM's have a way of undoing local edits to a
>   file very simply, i.e."hg revert <file>" or "svn revert <file>", and
>   for many developers's workflow, it's useful to be able to undo local
>   edits to a single file, but not to everything else in the working
>   directory.  And "git checkout HEAD -- <file>" is rather cumbersome
>   to type, and many beginning users don't find it intuitive to look in
>   the "git-checkout" man page for instructions on how to revert a
>   local file.

Well, I don't have strong feelings on the exact command name used; I
suggested "undo", probably also ambiguous.  But still, a significant
number of users are surprised when they type 'git revert' and they get a
backed out patch.  It's such an uncommon operation, it doesn't deserve
to be triggered so easily.  And reverting files to the state in the
index and/or HEAD is a common operation that deserves being short to
type.

Making it plain "revert" would violate expectations of existing users;
it seems a better idea to just deprecate it, and point the users to the
new method - cherry-pick --revert - or the command they might have meant
- whatever that becomes.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Thu, Oct 30, 2008 at 10:51:08AM -0700, Sam Vilain wrote:
> 
> Well, I don't have strong feelings on the exact command name used; I
> suggested "undo", probably also ambiguous.  But still, a significant
> number of users are surprised when they type 'git revert' and they get a
> backed out patch.

Yeah, that's why I suggested "git revert-file".  It's less ambiguous
than "undo", and it's easier for people used to "hg revert" and "svn
revert" to find "git revert-file".  And, it won't be run accidentally
by old-timers who are used to the old (to be deprecated) "git revert".
But I'm not that picky about the name; I just missed the "git undo"
proposal in your patch.

> Making it plain "revert" would violate expectations of existing users;
> it seems a better idea to just deprecate it, and point the users to the
> new method - cherry-pick --revert - or the command they might have meant
> - whatever that becomes.

Yup, I agree; that's why I suggested "git revert-file".

							- Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

Hi,

(Sorry for sending so many emails, and being late to the conversation.
 There's a couple others that I wanted to respond to but I'll wait off
on those and finish with this email to avoid spamming everyone any
more right now.)

On Thu, Oct 30, 2008 at 11:51 AM, Sam Vilain <sam@vilain.net> wrote:
> Well, I don't have strong feelings on the exact command name used; I
> suggested "undo", probably also ambiguous.  But still, a significant
> number of users are surprised when they type 'git revert' and they get a
> backed out patch.  It's such an uncommon operation, it doesn't deserve
> to be triggered so easily.  And reverting files to the state in the
> index and/or HEAD is a common operation that deserves being short to
> type.
>
> Making it plain "revert" would violate expectations of existing users;
> it seems a better idea to just deprecate it, and point the users to the
> new method - cherry-pick --revert - or the command they might have meant
> - whatever that becomes.

There is another option, though it has its own problems too.  There
are basically two kinds of reverting here -- reverting all the changes
*in* a given revision (which I'll called 'revert-in') and reverting
all the changes *since* a given revision (typically HEAD; I'll call
this 'revert-since').  These two operations can be supported from the
same command, though their use cases are different enough that it may
seem slightly weird:

     revert-since                        revert-in
     * is usually used in a dirty tree   * is typically used in a clean tree
     * specific paths are usually        * specific paths are not often
       specified                           specified
     * it is rare to want to commit      * making a commit after reverting
       immediately after reverting         is what you usually want
     * it is uncommon to need to
       specify a revision

I decided to combine them in EasyGit, simply because that made things
the most discoverable for both existing git and svn/bzr/hg users.  The
big problem here is that --commit is turned on by default when --in is
specified, and --no-commit is the default when --since is specified.
Anyway, some examples:

eg revert REVISION   =>   Error -- you must specify either --since or
--in when specifying a revision
eg revert --in REVISION  =>  Same as git revert REVISION
eg revert --since HEAD FILE1 FILE2  =>  Same as svn revert FILE1 FILE2
eg revert FILE1 FILE2  => shorthand for the previous command; --since
HEAD is default when no revision is specified
eg revert --since HEAD~3 SUBDIRECTORY => should be clear; an extension
over what svn revert can do

Then there's also the possibility that users only want to revert
unstaged changes, or only want to revert staged changes...


Anyway, just some food for thought.  I've spammed the list enough in
this thread, so I'll break for now.  Thanks for listening.

Elijah

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Sat, Nov 01, 2008 at 02:27:03PM -0600, Elijah Newren wrote:
> 
> There is another option, though it has its own problems too.  There
> are basically two kinds of reverting here -- reverting all the changes
> *in* a given revision (which I'll called 'revert-in') and reverting
> all the changes *since* a given revision (typically HEAD; I'll call
> this 'revert-since').  These two operations can be supported from the
> same command, though their use cases are different enough that it may
> seem slightly weird:

In my opinion, that is a Really Bad Idea from a usability and UI
design point of view.  Each command should do one and only one thing,
and not do different things depending on what options you give it.
Git violates this rules in a number of places already, What you call
"revert-since" and "revert-in" are so different that using the same
subcommand is just going to horribly confuse users.

Better to have "git revert" print a message explining that it is
deprecated, and to tell users that they probably want either "git
cherry-pick --revert" or "git revert-file", depending on whether they
are an experienced git user (in which case they probably want git
cherry-pick --revert"), or if that person who is familiar svn or hg's
"svn revert" or "hg revert", they probably want "git revert-file".

     	     	    	     	  	   - Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

On Sat, Nov 1, 2008 at 7:06 PM, Theodore Tso <tytso@mit.edu> wrote:
> In my opinion, that is a Really Bad Idea from a usability and UI
> design point of view.  Each command should do one and only one thing,
> and not do different things depending on what options you give it.
> Git violates this rules in a number of places already, What you call
> "revert-since" and "revert-in" are so different that using the same
> subcommand is just going to horribly confuse users.
>
> Better to have "git revert" print a message explining that it is
> deprecated, and to tell users that they probably want either "git
> cherry-pick --revert" or "git revert-file", depending on whether they
> are an experienced git user (in which case they probably want git
> cherry-pick --revert"), or if that person who is familiar svn or hg's
> "svn revert" or "hg revert", they probably want "git revert-file".

Yeah, good points.  I guess I could just make --no-commit the default
in all cases to remove the "magic", but then it's too much typing for
the revert-in case ("eg revert --commit --in REVISION" vs. "git revert
REVISION").  Two separate commands may make more sense, but then
there's the naming issue (I had difficulty coming up with a different
name that I liked, and it appears others are having a little trouble
with the naming too).  Tough nut to crack from any angle.  :-(

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

Hi,

On Thu, Oct 30, 2008 at 8:39 AM, Theodore Tso <tytso@mit.edu> wrote:
> Here are my favorites:
>
> * Add the command "git revert-file <files>" which is syntactic sugar for:
>
>        git checkout HEAD -- <files>
>
>  Rationale: Many other SCM's have a way of undoing local edits to a
>  file very simply, i.e."hg revert <file>" or "svn revert <file>", and
>  for many developers's workflow, it's useful to be able to undo local
>  edits to a single file, but not to everything else in the working
>  directory.  And "git checkout HEAD -- <file>" is rather cumbersome
>  to type, and many beginning users don't find it intuitive to look in
>  the "git-checkout" man page for instructions on how to revert a
>  local file.

I agree with the rationale, but the suggested implementation (as with
the original suggestion for "git undo") is somewhat problematic.  I
have a write-up somewhere documenting the ways various individual git
commands fail to be an appropriate replacement for svn/hg/bzr
revert[1], but in short the "git checkout HEAD -- <file>"
implementation for svn/hg/bzr-like revert fails in the following ways:
  * It does not work for the initial commit
  * It won't untrack or remove files (this is related to the previous
and following items)
  * It doesn't allow reverting a file or directory to a revision prior
to HEAD (making it like svn; note though that both bzr and hg have
such an option and I have found it handy a few times)
  * It's inappropriate to use during an incomplete merge.

The incomplete merge case is particularly interesting.  If the user
specifies a file or subdirectory, they should also specify a branch to
revert relative to (and it should be an error if they don't).  If the
user specifies "." then there's the question of whether they are
attempting to undo the merge (meaning that .git/MERGE_MSG and
.git/MERGE_HEAD should be removed).

Just as food for thought, here's what eg does in the incomplete merge case:

$ eg revert foo
Aborting: Cannot revert the changes since the last commit, since you are in
the middle of a merge and there are multiple last commits.  Please add
  --since BRANCH
to your flags to eg revert, where BRANCH is one of
  master, devel
If you simply want to abort your merge and undo its conflicts, run
  eg revert --since HEAD


There's a couple more issues here that I could go on about, but I'll
mention just one more thing for this email:  Since users often get
confused between different kinds of "reverting" or "undoing", a plain
'eg revert' is also pretty helpful in a wide variety of circumstances
(it always aborts with an error message, but one that detects what the
user might want and suggests appropriate commands in the various
cases.)

Elijah


[1] There are a number of different commands that people suggest for
new users to replace other systems' revert behavior, but each has
areas in which it will fail to do what users expect or do additional
things users don't want (including discarding data)  Interestingly,
I've tried four different alternative git porcelains and each one
implemented their svn/hg/bzr-like revert incorrectly.  One of these
was EasyGit, in which I got it wrong not once but three separate
times.  (And if alternative porcelain authors can't easily get it
right, we clearly can't expect normal users to know how to do so; I
think this is a pretty good argument for providing a function for this
behavior in core git.)  I think I finally have it implemented
correctly now in EasyGit, after my fourth try...

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> Here are my favorites:
>
> * Add the command "git revert-file <files>" which is syntactic sugar for:
>
>         git checkout HEAD -- <files>

This is good; I do not recall offhand what we do if some of the <files> do
not appear in HEAD right now, but I have a suspicion that it would be a
no-op, in which case interested parties may first want to fix checkout to
remove such paths.

Also I thiink you can add "git revert-commit [$committish]" as a synonym
to the current "git revert [$committish]" if it makes things easier to
explain to others.

> * Change the argument handling for "git format-patch" so it is
>   consistent with everything else which takes a set of commits.  Yes,
>   it means that where people have gotten used to typing "git
>   format-patch origin", they'll have to type instead: "git
>   format-patch origin..", but's much more consistent.

I think that has already happened some time ago in the sense that you can
say "origin.."  and it does what you want.  I do not think it merits to
deprecate the original one --- if you do not like it, you do not use it
nor teach it to others.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Elijah Newren]

Hi,

Good list..  I agree with others that the 'undo' name doesn't sound
right (and will discuss other issues with it in response to another
email) but otherwise nice work.

On Wed, Oct 29, 2008 at 9:48 PM, Sam Vilain <sam@vilain.net> wrote:
> +  * 'git push' to checked out branch of non-bare repository not
> +    allowed without special configuration.  Configuration available
> +    that allows working directory to be updated, known caveats
> +    notwithstanding.  Ideally, it would refuse only in situations
> +    where a broken working copy would be left (because you couldn't
> +    fix it), and work when it can be known to be safe.

Configuration of remote repository, special command-line override, or both?


Some food for thought: One thing I did in EasyGit was to disallow
pushes to non-bare repositories* unless both source and destinations
references were explicitly specified.  For example:

$ eg push origin master    # or 'eg push', in this case
Aborting: You are trying to push to a repository with an associated working
copy, which will leave its working copy out of sync with its repository.
Rather than pushing changes to that repository, you should go to where that
repository is located and pull changes into it (using eg pull).  If you
know what you are doing and know how to deal with the consequences, you can
override this check by explicitly specifying source and destination
references, e.g.
  eg push REMOTE BRANCH:REMOTE_BRANCH
Please refer to
  eg help topic refspecs
to learn what this syntax means and what the consequences of overriding this
check are.

$ eg push origin master:master
Counting objects: 5, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 260 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To /home/newren/testing/dumb/.git
   852ffee..f5596e4  master -> master


This seems to prevent errors for new users, while still allowing
people to work around firewall issues.

* The big problem was that I was only able to detect if a remote
repository was bare or not if it was accessed via the local filesystem
or via ssh; for git:// (or rsync://) repositories I didn't know how to
perform such a check and so I simply omitted it.


Elijah

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Wed, Oct 29, 2008 at 05:22:00PM -0700, Sam Vilain wrote:

>  Some suggestions, which have been briefly scanned over by some of the
>  (remaining) GitTogether attendees.  Please keep it constructive!  :)

Thanks for putting this together.

> +  * 'git stage' would do what 'git add' does now.
> +
> +  * 'git unstage' would do what 'git reset --' does now

These seem reasonable.

> +  * 'git status' would encourage the user to use
> +    'git diff --staged' to see staged changes as a patch

I notice the commit template message getting longer and longer. Maybe it
is time for status.verbosetemplate (which could default to true, I just
want to be able to turn it off).

> +  * 'git commit' with no changes should give useful information about
> +    using 'git stage', 'git commit -a' or 'git commit filename ...'

There is already infrastructure that figures out exactly what the
situation is (no changes versus changes in untracked files versus
changes in unstaged files), so it should just be a matter of tweaking
the messages.

> +  * 'git add' and 'git rm': no change
> +
> +  * 'git update-index' considered plumbing, not changed

Definitely.

> +  * 'git revert' deprecated in favour of 'git cherry-pick --revert'

I think I would make it "-R, --reverse", since it really is analagous to
"git diff -R".

> +  * 'git undo' would do what 'git checkout HEAD --' does now

This is an awful name, IMHO. It doesn't point out _what_ you're undoing,
so it leaves me with the feeling that you can undo arbitrary things.
I think the name needs to be considered along with related operations.

So think of us as having three "spots": the HEAD (H), the "stage"[1] (S),
and the working tree (W). And we want commands for moving content
between them. Now we have:

  W->S: add
  H->S: reset --
  S->W: checkout --
  S->H: commit (no paths)

And if you want to include things that jump the staging area:

  W->H: commit (paths or -a)
  H->W: checkout HEAD --

So I think with your stage/unstage, we have:

  W->S: stage
  H->S: unstage
  S->W: ?
  S->H: commit (no paths)
  W->H: commit (paths or -a)
  H->W: ?

So I think we can note something: movement commands are related based on
their _destination_. So since both of the missing ones impact the
working tree, they should have a related name.

But do note the difference between "stage vs unstage" as opposed to
"commit versus commit -a". I think this is because the stage sits in the
middle. So it is mentally "which direction are changes coming from" and
not "how _far_ are changes coming from".

So by that rationale, we should have a single command which says "put
stuff in the working tree", with a flag for "from HEAD" versus "from the
staging area." And that's what we have right now with "git checkout".
The real problem with it is that it is an overload of checkout's other
behavior of switching branches.

So what I am saying is "git undo" _must_ support both "put index content
into working tree" as well as "put HEAD content into working tree", or
it will be a step backwards in consistency.

So I guess that doesn't really suggest a name. But "undo" is awful. ;P

Side note: there are actually _other_ places you might want to move
content. Like a stash. So now you can think of it as:

                 stash
                  ^  ^
                 /    \
                /      \
               v        v
  HEAD <--> stage <--> working tree

So maybe we just need a "git content" command. And then you can "git
content --from=HEAD --to=tree <paths>" or "git content --from=tree
--to=stash", with all equally supporting "--interactive".  And of course
I am kidding, because typing that would be awful. But I think
conceptually, it makes sense. To me, anyway.

> +  * 'git branch --switch' : alternative to checkout

Blech. I think switching branches is the one thing that checkout does
unconfusedly. And this is much more typing. Not to mention that So I
would rather see "git switch" if checkout is somehow unpalatable.

But I don't know that it is. This seems like an attempt to say "branch
operations should all be part of 'git branch'". But checkout isn't
necessarily a branch operation. Consider detaching HEAD to a tag. Should
it be "git tag --switch"?

> +  * 'git push --matching' does what 'git push' does today (without
> +    explicit configuration)

I think this is reasonable even without other changes, just to override
any configuration.

> +  * 'git push' with no ref args and no 'push =' configuration does
> +    what:
> +    'git push origin $(git symbolic-ref HEAD | sed "s!refs/heads/!!")'
> +    does today.  ie, it only pushes the current branch.
> +    If a branch was defined in branch.<name>.push, push to that ref
> +    instead of the matching one.  If there is no matching ref, and
> +    there is a branch.<name>.merge, push back there.

There was a thread between me and Junio some months ago that touched on
this. I don't remember all of the arguments, but it was resolved to keep
the current behavior. Any proposal along these lines should at least
revisit and respond to those arguments.

> +  * 'git push' to checked out branch of non-bare repository not
> +    allowed without special configuration.  Configuration available

I have this patch done and sitting in my repo, but I need to add the
"without special configuration" bit and add tests and docs.

> +Informational
> +-------------
> +
> +  * 'git branch' should default to '--color=auto -v'

This should at least be configurable (even if it defaults to "on"). "-v"
is more expensive, and not always wanted.

I, for one, just use "git branch" to get the current branch. I don't
know of a more obvious way to ask for it (and please don't mention an
ever-changing bash prompt).

> +  * 'git tag -l' should show more information

I remember somebody talking about this, but not the details. Which
information?

> +  * 'git am -3' the default; with global option to make it not the
> +    default for those that prefer the speed of -2

I would prefer that personally. I think Linus has been very reasonable
in the past about recognizing that his workflow and speed requirements
aren't always typical, and being willing to accept setting a
configuration flag in those cases. So I think if he ack'd such a patch,
nobody else would complain.

> +  * 'git export' command that does what
> +    'git archive --format=tar --prefix=dir | tar x' does now

I agree, if you mean "does what ... does now" means "looks to the user
like ... is happening". This is much more sanely done using
git-checkout-index (though somebody suggested "remote export", which
would need to use tar itself).

> +  * 'git init --server' (or similar) should do everything required for
> +    exporting::
> +----
> +chmod -R a+rX
> +touch git-daemon-export-ok
> +git gc
> +git update-server-info
> +chmod u+x .git/hooks/post-update
> +git config core.sharedrepository=1
> +----

But not all of those things are necessarily related, and some of them
have security implications. I would hate to get a bug report like "I
used --server because I wanted to share my content via dumb http, but my
repo was p0wned because of too-loose group permissions."

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Thu, 2008-10-30 at 20:31 -0400, Jeff King wrote:
> >  Some suggestions, which have been briefly scanned over by some of the
> >  (remaining) GitTogether attendees.  Please keep it constructive!  :)
> Thanks for putting this together.

No problem!  Thanks for responding.  I've been amazed that it seems to
have been largely taken well :)  But there are still very important
changes required.

> > +  * 'git status' would encourage the user to use
> > +    'git diff --staged' to see staged changes as a patch
> 
> I notice the commit template message getting longer and longer. Maybe it
> is time for status.verbosetemplate (which could default to true, I just
> want to be able to turn it off).

Right.  We'll have to work through that when we look at how 'git status'
output is displayed.  There may be some people who parse the existing
output, but they should get to read the release notes about the proper
ways to do that.  I think the whole output could do with a shake-up.

> > +  * 'git undo' would do what 'git checkout HEAD --' does now
> This is an awful name, IMHO. It doesn't point out _what_ you're undoing,

As others have said, yes.

> So I think with your stage/unstage, we have:
> 
>   W->S: stage
>   H->S: unstage
>   S->W: ?
>   S->H: commit (no paths)
>   W->H: commit (paths or -a)
>   H->W: ?
> 
> So I think we can note something: movement commands are related based on
> their _destination_. So since both of the missing ones impact the
> working tree, they should have a related name.

An interesting observation.

I still think it's OK to use 'git revert-files' for this; it just seems
so long.  Switches could specify where to and from.

> Side note: there are actually _other_ places you might want to move
> content. Like a stash. So now you can think of it as:
> 
>                  stash
>                   ^  ^
>                  /    \
>                 /      \
>                v        v
>   HEAD <--> stage <--> working tree
> 
> So maybe we just need a "git content" command. And then you can "git
> content --from=HEAD --to=tree <paths>" or "git content --from=tree
> --to=stash", with all equally supporting "--interactive".  And of course
> I am kidding, because typing that would be awful. But I think
> conceptually, it makes sense. To me, anyway.

Again interesting, you could look at the stash as a whole bunch of
staged commits yet to happen.  Of course, adding a file when the version
in HEAD doesn't match the version in the base of the stash is a bit
insane, so should probably be an error.

I'll have a ponder over this and whether there is a simple word for this
all.

> > +  * 'git branch --switch' : alternative to checkout
> 
> Blech. I think switching branches is the one thing that checkout does
> unconfusedly. And this is much more typing. Not to mention that So I
> would rather see "git switch" if checkout is somehow unpalatable.
>
> But I don't know that it is. This seems like an attempt to say "branch
> operations should all be part of 'git branch'". But checkout isn't
> necessarily a branch operation. Consider detaching HEAD to a tag. Should
> it be "git tag --switch"?

You're right with all that.  I don't think that it is necessarily wrong
to have two ways to get at functionality, depending on whether you start
with the noun or the verb first; so long as it doesn't introduce
confusion.  And if anything, I think --switch is wrong; --checkout is
probably more consistent.

I think I might have to mark this one as [maybe], and make it --checkout
- as you say, it would need to go on all the other commands that are
nouns and able to be checked out to be consistent.  Let's see how that
looks in round 2.

> > +  * 'git push --matching' does what 'git push' does today (without
> > +    explicit configuration)
> 
> I think this is reasonable even without other changes, just to override
> any configuration.

Excellent, I have another vote towards this push sanity!  :)

> > +  * 'git push' with no ref args and no 'push =' configuration does
> > +    what:
> > +    'git push origin $(git symbolic-ref HEAD | sed "s!refs/heads/!!")'
> > +    does today.  ie, it only pushes the current branch.
> > +    If a branch was defined in branch.<name>.push, push to that ref
> > +    instead of the matching one.  If there is no matching ref, and
> > +    there is a branch.<name>.merge, push back there.
> 
> There was a thread between me and Junio some months ago that touched on
> this. I don't remember all of the arguments, but it was resolved to keep
> the current behavior. Any proposal along these lines should at least
> revisit and respond to those arguments.

Right.  So, before round 2, I'll read and attempt to summarise that
thread - assuming I can find it!  :)

> > +  * 'git push' to checked out branch of non-bare repository not
> > +    allowed without special configuration.  Configuration available
> I have this patch done and sitting in my repo, but I need to add the
> "without special configuration" bit and add tests and docs.

Looking forward to that!  Thanks.

> > +  * 'git branch' should default to '--color=auto -v'
> This should at least be configurable (even if it defaults to "on"). "-v"
> is more expensive, and not always wanted.
> 
> I, for one, just use "git branch" to get the current branch. I don't
> know of a more obvious way to ask for it (and please don't mention an
> ever-changing bash prompt).

What's wrong with 'git symbolic-ref HEAD' ?  *ducks*

Of course 'git branch -q' would then be the quick version, or 'git
br' (after git config --global alias.br 'branch -q')

Another command people often want is 'git info' to tell them stuff like
they might get from 'git status' or 'git remote' but without all the
file details...

> > +  * 'git tag -l' should show more information
> 
> I remember somebody talking about this, but not the details. Which
> information?

Oh, good point.  Basically the same stuff that 'git branch -v' shows; in
any case, its behaviour should be relatively consistent compared to 'git
branch'.

> > +  * 'git init --server' (or similar) should do everything required for
> > +    exporting::
> > +----
> > +chmod -R a+rX
> > +touch git-daemon-export-ok
> > +git gc
> > +git update-server-info
> > +chmod u+x .git/hooks/post-update
> > +git config core.sharedrepository=1
> > +----
> 
> But not all of those things are necessarily related, and some of them
> have security implications. I would hate to get a bug report like "I
> used --server because I wanted to share my content via dumb http, but my
> repo was p0wned because of too-loose group permissions."

ok.  That should come down to the detail of how '--server' is specified,
I think.  I'll expand on that during round 2.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2655 bytes --]

On Fri, Oct 31, 2008 at 06:40:38AM +0000, Sam Vilain wrote:
> On Thu, 2008-10-30 at 20:31 -0400, Jeff King wrote:
> > >  Some suggestions, which have been briefly scanned over by some of the
> > >  (remaining) GitTogether attendees.  Please keep it constructive!  :)
> > Thanks for putting this together.
> 
> No problem!  Thanks for responding.  I've been amazed that it seems to
> have been largely taken well :)  But there are still very important
> changes required.

Well, most of it we discussed IRL, that helps tremendously ;)

> I still think it's OK to use 'git revert-files' for this; it just seems
> so long.  Switches could specify where to and from.

Well the point is we will probably just deprecate git-revert and remove
it alltogether in git 2.6. At that time you will be able to define
git-revert as an alias to git cherry-pick -R if you're an old fart, or
git revert-files if you're an svn user ;)

But I see no convincing name that hasn't "revert" in them, hence will be
long :/

> Of course 'git branch -q' would then be the quick version, or 'git
> br' (after git config --global alias.br 'branch -q')

oh no, not -q please, -q is quiet, -h is help, -v is verbose. I mean
POSIX should define these. Do not give those switch any other kind of
sementics anymore, we've done that, and it hurts. -Q is fine with me
though.

> Another command people often want is 'git info' to tell them stuff like
> they might get from 'git status' or 'git remote' but without all the
> file details...

And to say to them if they're in the midle of a merge, of a rebase, an
am, on a detached, head, .... what is in the __git_ps1 of bash actually.

> > > +  * 'git init --server' (or similar) should do everything required for
> > > +    exporting::
> > > +----
> > > +chmod -R a+rX
> > > +touch git-daemon-export-ok
> > > +git gc
> > > +git update-server-info
> > > +chmod u+x .git/hooks/post-update
> > > +git config core.sharedrepository=1
> > > +----
> > 
> > But not all of those things are necessarily related, and some of them
> > have security implications. I would hate to get a bug report like "I
> > used --server because I wanted to share my content via dumb http, but my
> > repo was p0wned because of too-loose group permissions."
> 
> ok.  That should come down to the detail of how '--server' is specified,
> I think.  I'll expand on that during round 2.

What about git init --svn-like ? /me *ducks*

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Thu, Oct 30, 2008 at 11:40:38PM -0700, Sam Vilain wrote:

> > I notice the commit template message getting longer and longer. Maybe it
> > is time for status.verbosetemplate (which could default to true, I just
> > want to be able to turn it off).
> Right.  We'll have to work through that when we look at how 'git status'
> output is displayed.  There may be some people who parse the existing
> output, but they should get to read the release notes about the proper
> ways to do that.  I think the whole output could do with a shake-up.

Maybe I am wrong, but I thought at some point we decided that parsing
the output of "git status" was insane and wrong, since it's porcelain.
OTOH, it is also an easy way for editors to see what is happening in a
commit whose message you are editing (and to do, for example, syntax
highlighting on it). So it may be that it is getting parsed anyway.

> [moving content from HEAD or index to working tree]
> I still think it's OK to use 'git revert-files' for this; it just seems
> so long.  Switches could specify where to and from.

Yeah, revert-files is pretty painful to type. And I'm not looking
forward to fielding UI questions about "why isn't it just revert?" :)

Somebody suggested "clobber", which I think is a bit _too_ intense.

I guess something like "retrieve" is too ambiguous. You really need
something that implies movement of content, and something that implies
the working directory. "Checkout" is actually not a bad name; if only we
had "git switch" instead of "git checkout" for switching branches, it
would be perfect.

So I am a bit stumped. Maybe "clobber" is not so bad. ;)

> Again interesting, you could look at the stash as a whole bunch of
> staged commits yet to happen.  Of course, adding a file when the version
> in HEAD doesn't match the version in the base of the stash is a bit
> insane, so should probably be an error.
> 
> I'll have a ponder over this and whether there is a simple word for this
> all.

Whether or not we come up with a simple word, I think it makes sense to
expose this through "git stash -i" (since, after all, we are just
putting stuff into an index there).

> You're right with all that.  I don't think that it is necessarily wrong
> to have two ways to get at functionality, depending on whether you start
> with the noun or the verb first; so long as it doesn't introduce
> confusion.  And if anything, I think --switch is wrong; --checkout is
> probably more consistent.

Agreed on --checkout. I think your "noun or verb" comment hits the nail
right on the head. I wonder if there are other places where
functionality can be exposed in either direction (I think we already
have some in "git fetch <remote>" versus "git remote update").

> > There was a thread between me and Junio some months ago that touched on
> > this. I don't remember all of the arguments, but it was resolved to keep
> > the current behavior. Any proposal along these lines should at least
> > revisit and respond to those arguments.
> 
> Right.  So, before round 2, I'll read and attempt to summarise that
> thread - assuming I can find it!  :)

I think it was "Minor annoyance with git push" from this past February.
Quite a long thread, but there is some in this subthread:

http://thread.gmane.org/gmane.comp.version-control.git/73038/focus=73208

> Another command people often want is 'git info' to tell them stuff like
> they might get from 'git status' or 'git remote' but without all the
> file details...

Yeah, I don't know if you have followed the other threads in the past
month or so, but I think there is some desire for a "new" status with
a nicer format.

And I think it might be nice to structure it as a long list of things it
_can_ report on, and then let you tweak those with command-line options
and config settings. E.g., I might set info.currentbranch, info.staged,
and info.untracked because that is what _I_ like to see to get a sense
of what is happening in the repo.

And I will get around to designing that after I clear the other 100
things off my todo list. ;)

> > > +  * 'git tag -l' should show more information
> > I remember somebody talking about this, but not the details. Which
> > information?
> Oh, good point.  Basically the same stuff that 'git branch -v' shows; in
> any case, its behaviour should be relatively consistent compared to 'git
> branch'.

OK, that makes sense to me. I think of "git tag -l" as plumbing-ish,
though, so we might be breaking people's scripts (yes, I know the "real"
plumbing for this is for-each-ref, but it really is a pain to parse the
tags out of that versus "for i in `git tag -l`").

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso]

On Sun, Nov 02, 2008 at 12:18:33AM -0400, Jeff King wrote:
> 
> Yeah, revert-files is pretty painful to type. And I'm not looking
> forward to fielding UI questions about "why isn't it just revert?" :)
> 

At least for me, I don't use it *that* often, so it's not that painful
for me (I have it as an "git revert-file" as an alias already).   

And the answer, "because 'git revert' used to do something else" is I
think a perfectly reasonable answer.  I probably do "git revert-files"
about 3-5 times more often than I do "git revert", so it's a bit
strange from a character count perspective, but history is history.

> Somebody suggested "clobber", which I think is a bit _too_ intense.
> 
> I guess something like "retrieve" is too ambiguous. You really need
> something that implies movement of content, and something that implies
> the working directory. "Checkout" is actually not a bad name; if only we
> had "git switch" instead of "git checkout" for switching branches, it
> would be perfect.

If people really want a shorter name, how about bk's "unedit"?  I'd
still worry about people being able to find it, since the reality is
that most of the world knows this command as revert, though.

     	     	       	     	  	     	     - Ted

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Johannes Schindelin]

Hi,

On Thu, 30 Oct 2008, Jeff King wrote:

> On Wed, Oct 29, 2008 at 05:22:00PM -0700, Sam Vilain wrote:
> 
> > +  * 'git branch --switch' : alternative to checkout
> 
> Blech. I think switching branches is the one thing that checkout does 
> unconfusedly. And this is much more typing. Not to mention that So I 
> would rather see "git switch" if checkout is somehow unpalatable.

You know, I asked for this because a _user_ told me "Guess how long it 
took me to find out how to check out a branch!".

I think if you are not confused by CVS/SVN, the name "checkout" is utterly 
unintuitive.

Ciao,
Dscho

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Fri, Oct 31, 2008 at 05:46:35PM +0100, Johannes Schindelin wrote:

> > > +  * 'git branch --switch' : alternative to checkout
> > 
> > Blech. I think switching branches is the one thing that checkout does 
> > unconfusedly. And this is much more typing. Not to mention that So I 
> > would rather see "git switch" if checkout is somehow unpalatable.
> 
> You know, I asked for this because a _user_ told me "Guess how long it 
> took me to find out how to check out a branch!".
> 
> I think if you are not confused by CVS/SVN, the name "checkout" is utterly 
> unintuitive.

OK. I am not opposed to such a change as long as:

 - this is not just _a_ user, but a _common_ user confusion. IOW, I
   don't recall this complaint coming up a lot (or at least not nearly
   as often as other ones do). But maybe you have more data.

 - it is done consistently.

   My initial "blech" was a little premature, as I was thinking "instead
   of checkout", though it does clearly say "alternative" there.

   However, (and somebody else in the thread very cleverly came up with
   this analysis, not me), this is basically going from "verb the noun"
   to "noun --verb". And that's reasonable, if users think in terms of
   nouns. But we should be consistent in applying that transformation,
   and make it available for other nouns that match that verb. In other
   words, "git tag --switch". And however one might manipulate remote
   tracking branches ("git branch -r --switch", I guess).

   Personally I find it somewhat backwards, but I think CVS rotted my
   brain long ago.

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Thu, Oct 30, 2008 at 08:31:54PM -0400, Jeff King wrote:

> So think of us as having three "spots": the HEAD (H), the "stage"[1] (S),
> and the working tree (W). And we want commands for moving content

Re-reading this, I realized I forgot to fill in my footnote. But it was
going to be:

 [1] Actually, the term "the stage" is growing on me.

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> +  * 'git push --matching' does what 'git push' does today (without
>> +    explicit configuration)
>
> I think this is reasonable even without other changes, just to override
> any configuration.

I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
recall that there is a way to configure push that way for people too lazy
to type "origin HEAD" after "git push".

>> +  * 'git export' command that does what
>> +    'git archive --format=tar --prefix=dir | tar x' does now
>
> I agree, if you mean "does what ... does now" means "looks to the user
> like ... is happening". This is much more sanely done using
> git-checkout-index (though somebody suggested "remote export", which
> would need to use tar itself).

I think I was neutral in the discussion that led to the removal of
"git-export", but the rationale IIRC was exactly because "git-export" can
be done by simply piping "git-tar" to tar.  On the other hand, if all you
had was "export" and you wanted to create a release tar/zip ball, you have
to first create a (potentially huge) hierarchy in the filesystem only to
archive it.  This change needs to defend that the benefit of being able to
create a new non-git checkout elsewhere on the filesystem far outweighs
the downside of addition of another command (i.e. "eek, why does git have
that many commands" from new people).

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Sun, 2008-11-02 at 14:27 -0800, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> >> +  * 'git push --matching' does what 'git push' does today (without
> >> +    explicit configuration)
> >
> > I think this is reasonable even without other changes, just to override
> > any configuration.
> 
> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
> recall that there is a way to configure push that way for people too lazy
> to type "origin HEAD" after "git push".

I don't think it's about laziness, it's more about making sure that
without specifying behaviour, the action of the command is conservative.
Pushing all matching refs is not conservative; it's "magic".  And in my
experience, people get bitten by it, because they think, "ok, time to
push this branch", type "git push" and then a lot more than they
expected gets pushed.

I can see that some people want this behaviour by default; but to me
"push the current branch back to where it came from" seems like far more
a rational default for at least 90% of users.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jakub Narebski]

Sam Vilain wrote:
> On Sun, 2008-11-02 at 14:27 -0800, Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>>>> +  * 'git push --matching' does what 'git push' does today (without
>>>> +    explicit configuration)
>>>
>>> I think this is reasonable even without other changes, just to override
>>> any configuration.
>> 
>> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
>> recall that there is a way to configure push that way for people too lazy
>> to type "origin HEAD" after "git push".
> 
> I don't think it's about laziness, it's more about making sure that
> without specifying behaviour, the action of the command is conservative.
> Pushing all matching refs is not conservative; it's "magic".  And in my
> experience, people get bitten by it, because they think, "ok, time to
> push this branch", type "git push" and then a lot more than they
> expected gets pushed.
> 
> I can see that some people want this behaviour by default; but to me
> "push the current branch back to where it came from" seems like far more
> a rational default for at least 90% of users.

"git remote <remote> push" for push matching?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sverre Rabbelier]

On Mon, Nov 3, 2008 at 10:48, Jakub Narebski <jnareb@gmail.com> wrote:
> "git remote <remote> push" for push matching?

Not another command that is made to perform yet another piece of
funcionality. Let's let remote handle (configuring, and maintaining
of) remote related things, not also make it do push stuff.
Unless ofcourse, you mean that "git remote push <remote>" (certainly
not the other way around) is for configuration only.

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Dmitry Potapov]

On Mon, Nov 03, 2008 at 06:59:20PM +1300, Sam Vilain wrote:
> 
> I can see that some people want this behaviour by default; but to me
> "push the current branch back to where it came from" seems like far more
> a rational default for at least 90% of users.

I think it depends on one's workflow. If you use a centralized workflow
as with CVS then yes, 90% cases you want to push the current branch. On
the other hand, if people push their changes to the server only for
review, it means that accidentally pushing more than one intended is not
a big deal. The only one who does publishing to the official repository
is the maintainer, and the maintainer is most likely to run some tests
after merging all changes, which takes some time. So, it is rarely push
the current branch, it is usually the branch that has been tested, so
the name of the branch should be specified explicitly anyway.

Dmitry

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Sam Vilain]

On Tue, 2008-11-04 at 12:18 +0300, Dmitry Potapov wrote:
> > I can see that some people want this behaviour by default; but to me
> > "push the current branch back to where it came from" seems like far more
> > a rational default for at least 90% of users.
> 
> I think it depends on one's workflow. If you use a centralized workflow
> as with CVS then yes, 90% cases you want to push the current branch. On
> the other hand, if people push their changes to the server only for
> review, it means that accidentally pushing more than one intended is not
> a big deal.

Perhaps not, but it was still unintended.  I really can't understand the
opposition to making this command make many people less angry at it.

>  The only one who does publishing to the official repository
> is the maintainer, and the maintainer is most likely to run some tests
> after merging all changes, which takes some time. So, it is rarely push
> the current branch, it is usually the branch that has been tested, so
> the name of the branch should be specified explicitly anyway.

Why is that relevant?  That person can still use the explicit version of
the command.

Sam.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Sam Vilain <sam@vilain.net> writes:

> On Tue, 2008-11-04 at 12:18 +0300, Dmitry Potapov wrote:
> ...
>>  The only one who does publishing to the official repository
>> is the maintainer, and the maintainer is most likely to run some tests
>> after merging all changes, which takes some time. So, it is rarely push
>> the current branch, it is usually the branch that has been tested, so
>> the name of the branch should be specified explicitly anyway.
>
> Why is that relevant?  That person can still use the explicit version of
> the command.

Back when "git push $there :" were not available, the default matching
behaviour was the _only_ way to say "I know the set of branches I want to
publish, and I have many more private branches in my primary work
repository.  I do not want to list the set of branches to publish every
time when I type 'git push', nor I want to configure it --- Heck, I
shouldn't have to list them, the public repository I am pushing to already
has that list, and it is the set of branches that exist there".

These days, people who would want the maching behaviour can explicitly ask
for it, so there is one less reason to resist changing the default
(i.e. earlier explicitly askinf for "matching" was impossible, but now we
can).  The remaining reason of resistance is pure inertia (i.e. not
changing the behaviour of the command only because you upgraded your git),
and the only way to address it is to start issuing the warning when "git
push" or "git push $there" is used and the matching behaviour was chosen
without configuration (i.e. no "remote.<there>.push = :"), and keep it
that way for two release cycles, and finally change the default.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Tue, Nov 04, 2008 at 11:46:36AM -0800, Junio C Hamano wrote:

> These days, people who would want the maching behaviour can explicitly ask
> for it, so there is one less reason to resist changing the default
> (i.e. earlier explicitly askinf for "matching" was impossible, but now we
> can).  The remaining reason of resistance is pure inertia (i.e. not
> changing the behaviour of the command only because you upgraded your git),
> and the only way to address it is to start issuing the warning when "git
> push" or "git push $there" is used and the matching behaviour was chosen
> without configuration (i.e. no "remote.<there>.push = :"), and keep it
> that way for two release cycles, and finally change the default.

Hmm. It really seems to me that there are two desires for push behavior,
based on particular workflows. I.e., some people seem to want the
matching behavior by default, and others want to push the current
branch.

And we already can control that via configuration of the refspec. So any
argument that "git push should do the same thing even on somebody else's
setup" is already wrong. But I do think Junio has a good point, which is
that there is going to be confusion if upgrading git suddenly causes
"git push" to do something else.

So why not take one step back in the behavior change? We can set up the
"push just this branch" refspec during clone, which will leave existing
repositories untouched. And to make things even gentler, we can start
with opt-in to the clone feature, notify users via the release notes
(which, as we have established, EVERYONE reads), and then decide if and
when to switch the option on by default.

So something like a "remote.push" config option, the value of which gets
added to newly created remotes (including those created on clone). It
would default to ":", but you could easily set "git config remote.push
HEAD" to get the other behavior.

No, this doesn't get rid of the eventual need to choose whether to
switch the default. But I think it eases us into it a little more. And I
think such an option is a lot more generally applicable than a "default
push to matching versus HEAD" option.

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> So why not take one step back in the behavior change? We can set up the
> "push just this branch" refspec during clone, which will leave existing
> repositories untouched.

That is not good enough.

People who (think) know what an unconfigured "git push" would do would
suddenly see "git push" start misbehaving in their new repositories.

Here is a patch to do what I suggested earlier.  It

 * Adds "--matching" option; if we ever change the default to "current
   branch only", then "git push $there :" forces people to type $there.
   "git push --matching" allows us to honor "branch.<name>.remote".

 * Issues a deprecation warning when "git push" and "git push $there" is
   used to trigger the "matching" behaviour, without configuration or
   explicit command line refspec ":".

Whoever wants to change the default to "current branch only" can change
the part that calls push_deprecation_warning().

I'll leave it up to people who want to change the default to implement the
same for non native transports and document the transition plan, as I am
not very keen on changing the default myself.

---

 builtin-push.c      |   11 +++++++----
 builtin-send-pack.c |    2 ++
 remote.c            |    8 ++++++++
 remote.h            |    1 +
 send-pack.h         |    1 +
 transport.c         |    1 +
 transport.h         |    1 +
 7 files changed, 21 insertions(+), 4 deletions(-)

diff --git c/builtin-push.c w/builtin-push.c
index 122fdcf..21418ab 100644
--- c/builtin-push.c
+++ w/builtin-push.c
@@ -10,7 +10,7 @@
 #include "parse-options.h"
 
 static const char * const push_usage[] = {
-	"git push [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-v] [<repository> <refspec>...]",
+	"git push [--all | --mirror] [--dry-run] [--matching] [--tags] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-v] [<repository> <refspec>...]",
 	NULL,
 };
 
@@ -71,9 +71,11 @@ static int do_push(const char *repo, int flags)
 		return error("--mirror can't be combined with refspecs");
 	}
 
-	if ((flags & (TRANSPORT_PUSH_ALL|TRANSPORT_PUSH_MIRROR)) ==
-				(TRANSPORT_PUSH_ALL|TRANSPORT_PUSH_MIRROR)) {
-		return error("--all and --mirror are incompatible");
+	if (HAS_MULTI_BITS(flags &
+			   (TRANSPORT_PUSH_ALL|
+			    TRANSPORT_PUSH_MIRROR|
+			    TRANSPORT_PUSH_MATCHING))) {
+		return error("--all, --mirror, --matching are incompatible");
 	}
 
 	if (!refspec
@@ -123,6 +125,7 @@ int cmd_push(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN( 0 , "tags", &tags, "push tags"),
 		OPT_BIT( 0 , "dry-run", &flags, "dry run", TRANSPORT_PUSH_DRY_RUN),
 		OPT_BIT('f', "force", &flags, "force updates", TRANSPORT_PUSH_FORCE),
+		OPT_BIT( 0 , "matching", &flags, "push matching", TRANSPORT_PUSH_MATCHING),
 		OPT_BOOLEAN( 0 , "thin", &thin, "use thin pack"),
 		OPT_STRING( 0 , "receive-pack", &receivepack, "receive-pack", "receive pack program"),
 		OPT_STRING( 0 , "exec", &receivepack, "receive-pack", "receive pack program"),
diff --git c/builtin-send-pack.c w/builtin-send-pack.c
index d68ce2d..f5dda88 100644
--- c/builtin-send-pack.c
+++ w/builtin-send-pack.c
@@ -402,6 +402,8 @@ static int do_send_pack(int in, int out, struct remote *remote, const char *dest
 		flags |= MATCH_REFS_ALL;
 	if (args.send_mirror)
 		flags |= MATCH_REFS_MIRROR;
+	if (args.send_matching)
+		flags |= MATCH_REFS_MATCHING;
 
 	/* No funny business with the matcher */
 	remote_tail = get_remote_heads(in, &remote_refs, 0, NULL, REF_NORMAL,
diff --git c/remote.c w/remote.c
index e530a21..ce4f54c 100644
--- c/remote.c
+++ w/remote.c
@@ -1017,6 +1017,12 @@ static const struct refspec *check_pattern_match(const struct refspec *rs,
 		return NULL;
 }
 
+static void push_deprecation_warning(void)
+{
+	warning("'git push [$remote]' will stop pushing 'matching refs' in a future release");
+	warning("please train your fingers to say 'git push --matching' instead.");
+}
+
 /*
  * Note. This is used only by "push"; refspec matching rules for
  * push and fetch are subtly different, so do not try to reuse it
@@ -1031,6 +1037,8 @@ int match_refs(struct ref *src, struct ref *dst, struct ref ***dst_tail,
 	static const char *default_refspec[] = { ":", 0 };
 
 	if (!nr_refspec) {
+		if (!(flags & MATCH_REFS_MATCHING))
+			push_deprecation_warning();
 		nr_refspec = 1;
 		refspec = default_refspec;
 	}
diff --git c/remote.h w/remote.h
index d2e170c..2a702cb 100644
--- c/remote.h
+++ w/remote.h
@@ -124,6 +124,7 @@ enum match_refs_flags {
 	MATCH_REFS_NONE		= 0,
 	MATCH_REFS_ALL 		= (1 << 0),
 	MATCH_REFS_MIRROR	= (1 << 1),
+	MATCH_REFS_MATCHING	= (1 << 2),
 };
 
 /* Reporting of tracking info */
diff --git c/send-pack.h w/send-pack.h
index 8ff1dc3..133cb67 100644
--- c/send-pack.h
+++ w/send-pack.h
@@ -6,6 +6,7 @@ struct send_pack_args {
 	unsigned verbose:1,
 		send_all:1,
 		send_mirror:1,
+		send_matching:1,
 		force_update:1,
 		use_thin_pack:1,
 		dry_run:1;
diff --git c/transport.c w/transport.c
index 56831c5..4057d27 100644
--- c/transport.c
+++ w/transport.c
@@ -680,6 +680,7 @@ static int git_transport_push(struct transport *transport, int refspec_nr, const
 	args.receivepack = data->receivepack;
 	args.send_all = !!(flags & TRANSPORT_PUSH_ALL);
 	args.send_mirror = !!(flags & TRANSPORT_PUSH_MIRROR);
+	args.send_matching = !!(flags & TRANSPORT_PUSH_MATCHING);
 	args.force_update = !!(flags & TRANSPORT_PUSH_FORCE);
 	args.use_thin_pack = data->thin;
 	args.verbose = !!(flags & TRANSPORT_PUSH_VERBOSE);
diff --git c/transport.h w/transport.h
index 6bbc1a8..fb98128 100644
--- c/transport.h
+++ w/transport.h
@@ -34,6 +34,7 @@ struct transport {
 #define TRANSPORT_PUSH_DRY_RUN 4
 #define TRANSPORT_PUSH_MIRROR 8
 #define TRANSPORT_PUSH_VERBOSE 16
+#define TRANSPORT_PUSH_MATCHING 32
 
 /* Returns a transport suitable for the url */
 struct transport *transport_get(struct remote *, const char *);

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Dmitry Potapov]

On Wed, Nov 05, 2008 at 07:10:31AM +1300, Sam Vilain wrote:
> On Tue, 2008-11-04 at 12:18 +0300, Dmitry Potapov wrote:
> > > I can see that some people want this behaviour by default; but to me
> > > "push the current branch back to where it came from" seems like far more
> > > a rational default for at least 90% of users.
> > 
> > I think it depends on one's workflow. If you use a centralized workflow
> > as with CVS then yes, 90% cases you want to push the current branch. On
> > the other hand, if people push their changes to the server only for
> > review, it means that accidentally pushing more than one intended is not
> > a big deal.
> 
> Perhaps not, but it was still unintended.

Even if it were unintended, it will be noticed and corrected immediately,
while forgetting to push some changes is not so obvious... Anyway, your
workflow assumes that one wants to push changes immediately before
switching to another branch, while there are many people who do that
later (after some additional testing or just at the end of their workday).

> I really can't understand the
> opposition to making this command make many people less angry at it.

Because it breaks how this command works now. So I don't think it is a
good idea to make some people less angry while enraging many others over
breaking their workflow. Compatibility should not be taken lightly.

Dmitry

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Sun, Nov 02, 2008 at 02:27:57PM -0800, Junio C Hamano wrote:

> >> +  * 'git push --matching' does what 'git push' does today (without
> >> +    explicit configuration)
> >
> > I think this is reasonable even without other changes, just to override
> > any configuration.
> 
> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
> recall that there is a way to configure push that way for people too lazy
> to type "origin HEAD" after "git push".

I think you are reading more into my statement than I intended. I meant
that adding an explicit --matching was reasonable, _even if it matches
the default_. I can think of two reasons:

 1. Even if it is a no-op, it is more explicit for showing newbies what
    is going on. And it also means that _if_ we wanted to introduce
    new behavior or configurability, we will have already had
    "--matching" for some time. So it will be safe(r) at that point to
    immediately start saying "--matching" in your scripts to specify the
    behavior you want, without as much worry about confusing an older
    version.

 2. Even today, the behavior of push can be modified with configuration
    in remote.*.mirror. I would expect "git push --matching" to override
    this. Though perhaps that is too confusing a behavior, as mirroring
    does more than just ref selection, including force-updating.

So my statement was not anything about "git push $there HEAD", but just
that adding "--matching" was reasonable.

> I think I was neutral in the discussion that led to the removal of
> "git-export", but the rationale IIRC was exactly because "git-export" can
> be done by simply piping "git-tar" to tar.  On the other hand, if all you
> had was "export" and you wanted to create a release tar/zip ball, you have
> to first create a (potentially huge) hierarchy in the filesystem only to
> archive it.  This change needs to defend that the benefit of being able to
> create a new non-git checkout elsewhere on the filesystem far outweighs
> the downside of addition of another command (i.e. "eek, why does git have
> that many commands" from new people).

I think the complaint is just that it is awkward to have to pipe to tar
(and harder to check error status), when "export to directory" is a
reasonably common request.

If the concern is about another command, then perhaps rather than "git
export" it would be simpler to have "git archive --format=dir" as a
convenience (and it could even use the checkout-index optimization in
the local case, rather than generating a tar).

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Mon, Nov 03, 2008 at 01:56:36AM -0500, Jeff King wrote:

> So my statement was not anything about "git push $there HEAD", but just
> that adding "--matching" was reasonable.

And btw, I am not saying I necessarily disagree with Sam's proposal
about bare "git push". I am undecided about the best course of action
there.

I just wanted to make clear that it was not what I was talking about in
the original mail.

-Peff

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1396 bytes --]

On Sun, Nov 02, 2008 at 10:27:57PM +0000, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> >> +  * 'git push --matching' does what 'git push' does today (without
> >> +    explicit configuration)
> >
> > I think this is reasonable even without other changes, just to override
> > any configuration.
> 
> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
> recall that there is a way to configure push that way for people too lazy
> to type "origin HEAD" after "git push".

Yes, but it's broken in the sense that if you're in a non matching
branch it creates it remotely. The way to configure it is to say
remote.push = HEAD in your .gitconfig or sth similar. I removed it
because I've created 2 times a new branch remotely that I didn't want to
because I was tired and forgot to checkout and merge into the proper
one.

I rarely do mistakes with git, but something like more than half of my
mistakes are with push. I've argued that in the past, I know most of the
other core git developers disagree with the fact that git-push UI is not
helping users to not shoot themselves in the foot, I disagree, but there
is not much I can do if I'm 1:10 to think that ;)
-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> On Sun, Nov 02, 2008 at 10:27:57PM +0000, Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>> >> +  * 'git push --matching' does what 'git push' does today (without
>> >> +    explicit configuration)
>> >
>> > I think this is reasonable even without other changes, just to override
>> > any configuration.
>> 
>> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
>> recall that there is a way to configure push that way for people too lazy
>> to type "origin HEAD" after "git push".
>
> Yes, but it's broken in the sense that if you're in a non matching
> branch it creates it remotely.

Ok, I agree that may be a problem.

But that would not change if you only changed the default behaviour from
matching to _this branch_.  You need to also teach a new mode of operation
to send-pack/receive-pack pair, which is to "update the same branch as the
one I am on locally, but do not do anything if there is no such branch
over there".  I do not think we have such a mode of operation currently.

By the way, didn't we add a feature to let you say "git push $there :"
which is to do what "git push --matching $there" would do?

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1644 bytes --]

On Mon, Nov 03, 2008 at 11:33:10PM +0000, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> 
> > On Sun, Nov 02, 2008 at 10:27:57PM +0000, Junio C Hamano wrote:
> >> Jeff King <peff@peff.net> writes:
> >> 
> >> >> +  * 'git push --matching' does what 'git push' does today (without
> >> >> +    explicit configuration)
> >> >
> >> > I think this is reasonable even without other changes, just to override
> >> > any configuration.
> >> 
> >> I don't.  Can't you say "git push $there HEAD" these days?  I vaguely
> >> recall that there is a way to configure push that way for people too lazy
> >> to type "origin HEAD" after "git push".
> >
> > Yes, but it's broken in the sense that if you're in a non matching
> > branch it creates it remotely.
> 
> Ok, I agree that may be a problem.
> 
> But that would not change if you only changed the default behaviour from
> matching to _this branch_.  You need to also teach a new mode of operation
> to send-pack/receive-pack pair, which is to "update the same branch as the
> one I am on locally, but do not do anything if there is no such branch
> over there".  I do not think we have such a mode of operation currently.

You're right.

> By the way, didn't we add a feature to let you say "git push $there :"
> which is to do what "git push --matching $there" would do?

I don't know, I thought git push --matching $remote would be the same as
git push $remote ?

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

>> Ok, I agree that may be a problem.
>> 
>> But that would not change if you only changed the default behaviour from
>> matching to _this branch_.  You need to also teach a new mode of operation
>> to send-pack/receive-pack pair, which is to "update the same branch as the
>> one I am on locally, but do not do anything if there is no such branch
>> over there".  I do not think we have such a mode of operation currently.
>
> You're right.

Perhaps "git push --no-create"?

In hindsight, _if_ we did not have to worry about backward compatibility
at all, I might agree that the way "git push" ought to work with least
surprise would be:

 * "git push" is the same as "git push origin" (override 'origin' with
   branch.$current_branch.remote);

 * "git push $remote" is the same as "git push --no-create $remote HEAD"
   (override 'HEAD' with remote.$remote.push);

 * "git push $remote $any_non_empty_refspec" does what it is told without
   configuration interfering.

Current behaviour satisfies the first one and the third one.  Instead of
the second, the current behaviour is:

 * "git push $remote" is the same as "git push $remote :" (override ':'
   with remote.$remote.push).

>> By the way, didn't we add a feature to let you say "git push $there :"
>> which is to do what "git push --matching $there" would do?
>
> I don't know, I thought git push --matching $remote would be the same as
> git push $remote ?

I think the point of "push --matching" (or an explicit "push $there :") is
so that you can defeat what you configured.  For example, you could have:

	[branch "master"]
        	remote = gitster
	[remote "gitster"]
        	url = gitster:/pub/git/git.git/
                push = HEAD

And with such a configuration, "git push" or "git push gitster" would only
push to the current branch.

You can countermand with "push gitster master next", of course, but you
would need a way to ask for the matching from the command line without
listing all the names, hence you would say "push gitster :".

I think you meant to give the  --matching option the same efffect.  My
comment is that you do not need a new option, as we already have that
feature.

Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Jeff King]

On Mon, Nov 03, 2008 at 03:33:10PM -0800, Junio C Hamano wrote:

> By the way, didn't we add a feature to let you say "git push $there :"
> which is to do what "git push --matching $there" would do?

Oh, indeed: a83619d (add special "matching refs" refspec) from April.
So given that, I think my arguments for "--matching" are pointless.

-Peff