What's in git.git (stable)

What's in git.git (stable)

[Junio C Hamano]

We have a handful fixes on 'maint'; I will be cutting v1.4.4.3 by
the end of the week.

On the 'master' front, this round has many topics (most of which
have been cooking in the 'next' branch) merged since the last
announcement.

 - Johannes Schindelin's built-in shortlog is in.

 - Johannes Schindelin's built-in 'RCS merge replacement' is
   in.  Hopefully this would make merge-recursive more portable
   and faster.

 - Shawn Pearce and Johannes Schindelin spotted and fixed a few
   corner cases in merge-recursive.

 - Updates to gitk from Paul Mackerras to fix longstanding menu
   issues on Mac OS X.

 - Eric Wong fixed use of rerere in many places.

 - Eric also has quite a few fixes to git-svn.

 - Nico updated 'git-add' to really mean 'add contents', not
   'add to the set of tracked paths'.  Also updated was the
   documentation for 'git commit' to make it easier to teach new
   people after a long discussion.

 - Lars Hjemli taught 'git-branch' to rename branches.

 - Andy Parkins taught 'git-branch' to be colorful.

 - Robin Rosenberg improved cvsexportcommit for unusual
   pathnames.

 - 'git push $URL :refs/tags/that' (notice the colon) can be
   used to delete 'that' tag from the remote repository; this
   needs the latest git on both ends.

 - branch."master".{remote,merge} configuration items are set up
   by 'git-clone', thanks to Andy Parkins.

 - 'git-commit' gives 'diff --summary' output to remind mode
   changes and added/deleted files.

 - 'git-diff --numstat' matches 'git-apply --numstat' when
   talking about binary changes.

 - 'git-merge' is now a first class UI, not just a mere driver
   for strategies.

I am hoping that we can start a stabilization cycle for v1.5.0
based on what we have in 'master'.  The theme is "usability and
teachability".

Things that need to be done to complete what have been merged to
'master' are:

 - 'git-rm' needs to be fixed up as Linus outlined; remove
   working tree file and index entry but have a sanity check to
   make sure the working tree file match the index and HEAD.

 - 'git-branch' may need to be taught about renaming the
   matching per-branch configuration at the same time.

 - 'git-merge-file' needs to be documented and linked from
   git.txt.

 - 'git-clone' probably should be updated to use wild-card in
   remote.origin.fetch, instead of listing all the branches it
   found when the clone was made.

 - tutorials and other Porcelain documentation pages need to be
   updated to match the updated 'git-add' and 'git-rm' (to be
   updated), and their description should be made much less
   about implementation; they should talk in terms of end-user
   workflows.  I will send a draft for 'git diff' out later, but
   somebody needs a full sweep on Porcelain-ish documentation.

 - 'git diff --index' patch should be reverted (already done in
   'next'), although we may have to come up with a better
   wording for --cached.

----------------------------------------------------------------
* The 'maint' branch has these fixes since v1.4.4.2.

   Alex Riesen (1):
      Clarify fetch error for missing objects.

   Brian Gernhardt (1):
      Move Fink and Ports check to after config file

   Chris Wright (1):
      no need to install manpages as executable

   Eric Wong (2):
      git-svn: exit with status 1 for test failures
      git-svn: correctly display fatal() error messages

   Jim Meyering (1):
      Don't use memcpy when source and dest. buffers may overlap

   Martin Langhoff (1):
      cvsserver: Avoid miscounting bytes in Perl v5.8.x

   Shawn O. Pearce (1):
      Make sure the empty tree exists when needed in merge-recursive.


* The 'master' branch has these since the last announcement.

   Alex Riesen (3):
      git-blame: fix rev parameter handling.
      Make perl/ build procedure ActiveState friendly.
      Clarify fetch error for missing objects.

   Andreas Ericsson (2):
      ls-files: Give hints when errors happen.
      git-diff: Introduce --index and deprecate --cached.

   Andy Parkins (6):
      Use .git/config for storing "origin" shortcut repository
      Document git-repo-config --bool/--int options.
      De-emphasise the symbolic link documentation.
      Explicitly add the default "git pull" behaviour to .git/config on clone
      Colourise git-branch output
      Allow subcommand.color and color.subcommand color configuration

   Brian Gernhardt (1):
      Move Fink and Ports check to after config file

   Chris Wright (1):
      no need to install manpages as executable

   David Miller (1):
      Pass -M to diff in request-pull

   Eric Wong (21):
      git-svn: use ~/.subversion config files when using SVN:: libraries
      git-svn: enable delta transfers during fetches when using SVN:: libs
      git-svn: update tests for recent changes
      git-svn: error out when the SVN connection fails during a fetch
      git-svn: fix output reporting from the delta fetcher
      git-svn: color support for the log command
      git-svn: documentation updates
      git-svn: fix multi-init
      git-svn: avoid fetching files twice in the same revision
      git-svn: avoid network timeouts for long-running fetches
      git-svn: extra error check to ensure we open a file correctly
      git-svn: use do_switch for --follow-parent if the SVN library supports it
      rerere: add clear, diff, and status commands
      rerere: record (or avoid misrecording) resolved, skipped or aborted rebase/am
      git-svn: enable logging of information not supported by git
      git-svn: allow dcommit to take an alternate head
      git-svn: correctly display fatal() error messages
      git-svn: correctly handle packed-refs in refs/remotes/
      git-svn: exit with status 1 for test failures
      git-svn: correctly display fatal() error messages
      git-svn: correctly handle "(no author)" when using an authors file

   Han-Wen Nienhuys (1):
      ident.c: Trim hint printed when gecos is empty.

   J. Bruce Fields (4):
      cvs-migration: improved section titles, better push/commit explanation
      Documentation: reorganize cvs-migration.txt
      Documentation: update git-clone man page with new behavior
      Documentation: simpler shared repository creation

   Jakub Narebski (4):
      gitweb: Fix Atom feed <logo>: it is $logo, not $logo_url
      git-clone: Rename --use-immingled-remote option to --no-separate-remote
      Document git-diff whitespace flags -b and -w
      gitweb: Allow PNG, GIF, JPEG images to be displayed in "blob" view

   Jeff King (1):
      shortlog: fix segfault on empty authorname

   Jim Meyering (2):
      Set permissions of each new file before "cvs add"ing it.
      Don't use memcpy when source and dest. buffers may overlap

   Johannes Schindelin (18):
      Build in shortlog
      shortlog: do not crash on parsing "[PATCH"
      shortlog: read mailmap from ./.mailmap again
      shortlog: handle email addresses case-insensitively
      shortlog: fix "-n"
      shortlog: use pager
      sha1_object_info(): be consistent with read_sha1_file()
      xdiff: add xdl_merge()
      xdl_merge(): fix an off-by-one bug
      xdl_merge(): fix thinko
      git-mv: search more precisely for source directory in index
      diff -b: ignore whitespace at end of line
      xdl_merge(): fix and simplify conflict handling
      cvs-migration document: make the need for "push" more obvious
      Add builtin merge-file, a minimal replacement for RCS merge
      merge-file: support -p and -q; fix compile warnings
      Get rid of the dependency on RCS' merge program
      merge-recursive: add/add really is modify/modify with an empty base

   Josef Weidendorfer (1):
      Add branch.*.merge warning and documentation update

   Junio C Hamano (45):
      Store peeled refs in packed-refs file.
      remove merge-recursive-old
      git-merge: make it usable as the first class UI
      merge: allow merging into a yet-to-be-born branch.
      Store peeled refs in packed-refs (take 2).
      git-fetch: reuse ls-remote result.
      git-fetch: fix dumb protocol transport to fetch from pack-pruned ref
      git-fetch: allow glob pattern in refspec
      Allow git push to delete remote ref.
      git-shortlog: fix common repository prefix abbreviation.
      git-shortlog: make common repository prefix configurable with .mailmap
      git-commit: show --summary after successful commit.
      git-fetch: allow forcing glob pattern in refspec
      fetch-pack: do not barf when duplicate re patterns are given
      git-merge: tighten error checking.
      git-merge: do not leak rev-parse output used for checking internally.
      cvsimport: style fixup.
      git blame -C: fix output format tweaks when crossing file boundary.
      tutorial: talk about user.name early and don't start with commit -a
      git-merge: fix confusion between tag and branch
      xmerge: make return value from xdl_merge() more usable.
      merge-recursive: use xdl_merge().
      receive-pack: do not insist on fast-forward outside refs/heads/
      unpack-trees: make sure "df_conflict_entry.name" is NUL terminated.
      read-tree: further loosen "working file will be lost" check.
      Loosen "working file will be lost" check in Porcelain-ish
      read-tree: document --exclude-per-directory
      git-reset to remove "$GIT_DIR/MERGE_MSG"
      git-merge: squelch needless error message.
      git-merge: fix "fix confusion between tag and branch" for real
      Fix perl/ build.
      git-rerere: add 'gc' command.
      Documentation/git-commit: rewrite to make it more end-user friendly.
      git-commit: allow --only to lose what was staged earlier.
      shortlog: remove "[PATCH]" prefix from shortlog output
      shortlog: fix segfault on empty authorname
      diff --numstat: show binary with '-' to match "apply --numstat"
      add test case for recursive merge
      git-push: document removal of remote ref with :<dst> pathspec
      git merge: reword failure message.
      spurious .sp in manpages
      git-push: accept tag <tag> as advertised.
      send-pack: tighten checks for remote names
      branch --color: change default color selection.
      config documentation: group color items together.

   Lars Hjemli (3):
      git-branch: add options and tests for branch renaming
      rename_ref: use lstat(2) when testing for symlink
      git-branch: let caller specify logmsg

   Martin Langhoff (1):
      cvsserver: Avoid miscounting bytes in Perl v5.8.x

   Michael Loeffler (1):
      git-fetch: ignore dereferenced tags in expand_refs_wildcard

   Nicolas Pitre (4):
      builtin git-shortlog is broken
      pack-objects: remove redundent status information
      make 'git add' a first class user friendly interface to the index
      change the unpack limit treshold to a saner value

   Paul Mackerras (1):
      gitk: Fix enabling/disabling of menu items on Mac OS X

   René Scharfe (1):
      shortlog: remove range check

   Robin Rosenberg (1):
      Make cvsexportcommit work with filenames with spaces and non-ascii characters.

   Sean Estabrooks (1):
      Update documentation to remove incorrect GIT_DIFF_OPTS example.

   Shawn O. Pearce (17):
      Teach git-completion.bash how to complete git-merge.
      Hide plumbing/transport commands from bash completion.
      Teach bash how to complete options for git-name-rev.
      Add current branch in PS1 support to git-completion.bash.
      Teach bash how to complete git-format-patch.
      Teach bash how to complete git-cherry-pick.
      Teach bash how to complete git-rebase.
      Teach bash about git log/show/whatchanged options.
      Support bash completion of refs/remote.
      Teach bash about git-repo-config.
      Support --strategy=x completion in addition to --strategy x.
      Cache the list of merge strategies and available commands during load.
      Teach bash about git-am/git-apply and their whitespace options.
      Teach bash how to complete long options for git-commit.
      Fix broken bash completion of local refs.
      Make sure the empty tree exists when needed in merge-recursive.
      Remove uncontested renamed files during merge.

   Uwe Zeisberger (1):
      Fix documentation copy&paste typo

Re: What's in git.git (stable)

[Andy Parkins]

On Wednesday 2006, December 13 21:35, Junio C Hamano wrote:
> I am hoping that we can start a stabilization cycle for v1.5.0
> based on what we have in 'master'.  The theme is "usability and
> teachability".

This is what I have in my "niggles" list.  These are surface level things that 
I think are easy to fix.  A large part of the scariness is (I think) git's 
unfriendly output.  Too many messages require understanding of git internals.  

The major barrier to implementing these sorts of changes is, I think, worries 
about users of the output of these commands in scripts.  I say: screw them, 
porcelain is there for the breaking :-)

 * git-fetch has to be in working root.  If I can do git-push from anywhere in 
   my tree, why can't I do git-fetch?
 * git-reset has to be in working root.  If you typically sit in, say "src/", 
   it's annoying to have to change directory to do a reset.
 * git-commit doesn't (generally) have output - after a commit, it's difficult
   to know if anything happened.  Get users used to the idea of hashes to 
   identify commits by telling them which one they just made.  Tell them if 
   they made a branch as well, which branch they are now on.
 * git-init-db says "defaulting to local storage area", as if that is
   meant to be a helpful message
 * git-revert should be called git-invert.  It doesn't remove a change
   from history, it simply applies another commit that does the
   opposite of whatever commit you are "revert"ing.  That's an inversion.
 * git-merge output is horrible - this affects git-pull, git-rebase,
   and git-cherry-pick.  Issuing "fatal" errors and then carrying on is very
   confusing.  Errors in merges appear multiple times.  The files upon which
   which there is a conflict are spread throughout the output.  Most of the
   output is not relevant to an average user.
 * git-apply output is horrible.  It says a few things about whitespace on 
   stdin then just finishes.  When it succeeds.   When it fails, it just says
   failed, it doesn't say why a particular hunk failed.
 * git-branch is not verbose enough when creating a new branch, for a new user
   a little reassurance that what they meant to happen has happened would be 
   nice.
 * git-commit without "-a" and without an "update-index" says "nothing
   to commit", which isn't an adequate message to help a user who hasn't
   realised they need to update the index
 * git-rebase --skip requires that the offending file be clean with
     git-checkout HEAD file
   before the skip will work.  Why?  The fact of the skip is enough
   knowledge for rebase to know that I don't care if the merge is lost
 * git-rebase/git-cherry-pick/git-reset/etc should all tell the user that they 
   need to run git-prune to tidy up after themselves.
 * git-add has no output, whether it works or not
 * git-cat-file is badly named.  git-cat-object would be slightly
   better.
 * git-fetch output is confusing:
    remote: Generating pack...
    remote: Done counting 189146 objects.
    remote: Result has 186566 objects.
    remote: Deltifying 186566 objects.
    remote:  100% (186566/186566) done
    Unpacking 186566 objects
    24% (44792/186566) done
   Some questions from the point of view of a newbie: what is a pack?  what is 
   an object? Why is the remote counting them?  Which remote am I reading 
   from?  What am I fetching?  What is "Deltifying"?  How much data do I have 
   to download (number of objects doesn't tell me).  How long has this taken?  
   How long is left to go?
 * Similar things can be said about git-clone
 * Similar things can be said about git-push
 * git-show-branch output is cryptic.
 * In general the principle for messages should be the same as for 
   presentations:
    - say what you're going to do
    - do it
    - say what you did
   So for example, "git-branch newbranch existingbranch" would say
    Branching at "existingbranch", hash XXXXXXXXXXXXXXXXXX
     - created branch "newbranch"
     - your working branch is "existingbranch"
   Rather than the nothing that it currently outputs.
 * It would be really nice to be able to do an arbitrary checkout, rather than
   having to make a branch for it.  Then I could do
    git-checkout remotes/origin/master && make
   (obviously committing with a non-branch HEAD would be prevented)
 * git-verify-tag would be nicer as a switch to git-tag


Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: What's in git.git (stable)

[Jakub Narebski]

Andy Parkins wrote:

> This is what I have in my "niggles" list.  These are surface level things that 
> I think are easy to fix.  A large part of the scariness is (I think) git's 
> unfriendly output.  Too many messages require understanding of git internals.

Nice list, although I'd rather add extra output only if command is used
with -v/--verbose (or -V/--verbose) option; if not, then add -q/--quiet
(or -s/--silent) option to be used in scripts. I'm partial to --verbose
solution, as advanced users are not interested in any output; they know
the commands, and want them to be fast. C.f GNU tar: it outputs something
only with -v/--verbose option.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Andy Parkins]

On Wednesday 2006 December 13 22:48, Jakub Narebski wrote:

> Nice list, although I'd rather add extra output only if command is used
> with -v/--verbose (or -V/--verbose) option; if not, then add -q/--quiet
> (or -s/--silent) option to be used in scripts. I'm partial to --verbose

I'd rather have the scripts requiring "--quiet"; because otherwise it's 
another switch for a newbie to guess at.  However, I don't think that 
switches is the answer.  Output for these porcelain-level commands is not 
structured enough to be used in scripts anyway (e.g. git-pull), but what it 
does output is a confusing lump.

> solution, as advanced users are not interested in any output; they know
> the commands, and want them to be fast. C.f GNU tar: it outputs something
> only with -v/--verbose option.

tar is doing a considerably less complicated sequence of operations than many 
of git's commands, so I don't think that's a fair comparison.

Also; I don't think "experts" should care about the extra output - I can't 
imagine that an extra few lines of text is going to slow git down.  Further, 
I think the problem in most cases is that git outputs _too much_.  Also, I'm 
not imagining that "git-add ." would list every file that it added - who is 
that going to help?  It should say "added X files to index" or similar.  You 
surely can't be arguing that that slows down your expert workflow?

I believe that a good set of output will be useful to both newbies and experts 
alike.  The idea that experts don't like to know what's going on is simply 
not true.  The idea that newbies want to see every file listed and every 
operation described is simply not true.



Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Shawn Pearce]

Andy Parkins <andyparkins@gmail.com> wrote:
> I think the problem in most cases is that git outputs _too much_.  Also, I'm 
> not imagining that "git-add ." would list every file that it added - who is 
> that going to help?  It should say "added X files to index" or similar.  You 
> surely can't be arguing that that slows down your expert workflow?

git-commit-tree's "committing initial tree" and git-init-db's
"defaulting to local storage area" are both probably too verbose
and should just get removed.

The progress meters in git-pack-objects that you see during clone,
repack, fetch and push at least keep the user amused.  I do read
the output of repack every so often, but in general I don't care
about the output of clone, fetch or push - all I care about is
that my objects got to the remote system and were accepted, or not.
Which means that at least for me the output could be reduced down
to just the bandwidth transfer meter, for really slow links.

But I'm not sure that git-add should output anything.  Last I checked
the 'mv' command in Linux doesn't say "Move 5 files" when I move 5
files into a directory.  Likewise I don't think that knowing that
6781 files were added is useful, what if it should have really been
6782 files?  I'm unlikely to know, care, or realize it.

Your niggle list (is that what you called it) has been useful
fodder for discussion.  I'm glad you took the time to write it up,
and to argue it so well on the list.  There's a number of items on
it that I'd like to see happen too; enough that I may code some of
them if nobody beats me to it.

-- 

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 09:36, Shawn Pearce wrote:

> But I'm not sure that git-add should output anything.  Last I checked
> the 'mv' command in Linux doesn't say "Move 5 files" when I move 5
> files into a directory.  Likewise I don't think that knowing that
> 6781 files were added is useful, what if it should have really been
> 6782 files?  I'm unlikely to know, care, or realize it.

That's a very particular example you've picked out there.  Of course the user 
won't know if it should be 6781 or 6782; they might know if it should have 
been 2 or 10 though; 0 or 100.  In your example, output like "about six and a 
half thousand", would probably be perfectly useful, but why not just output 
the number?

> Your niggle list (is that what you called it) has been useful
> fodder for discussion.  I'm glad you took the time to write it up,
> and to argue it so well on the list.  There's a number of items on
> it that I'd like to see happen too; enough that I may code some of
> them if nobody beats me to it.

I'm glad it was useful.  I never know how many disclaimers to put on these 
things.  I always feel that every message I write should begin with "I love 
git and use it every day, so please don't take this the wrong way, but..."



Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> But I'm not sure that git-add should output anything.  Last I checked
> the 'mv' command in Linux doesn't say "Move 5 files" when I move 5
> files into a directory.  Likewise I don't think that knowing that
> 6781 files were added is useful, what if it should have really been
> 6782 files?  I'm unlikely to know, care, or realize it.

git-add -v does output added files already.

Re: What's in git.git (stable)

[Jakub Narebski]

Nicolas Pitre wrote:

> On Thu, 14 Dec 2006, Shawn Pearce wrote:
> 
>> But I'm not sure that git-add should output anything.  Last I checked
>> the 'mv' command in Linux doesn't say "Move 5 files" when I move 5
>> files into a directory.  Likewise I don't think that knowing that
>> 6781 files were added is useful, what if it should have really been
>> 6782 files?  I'm unlikely to know, care, or realize it.
> 
> git-add -v does output added files already.

Ha! Now only get it to accept --verbose as long alternative to -v option,
and add -v/--verbose option to other similar commands (git-mv for example).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> The major barrier to implementing these sorts of changes is, I
> think, worries about users of the output of these commands in
> scripts.  I say: screw them, porcelain is there for the
> breaking :-)

I like that ;-).

Thanks for the list.  I'll comment only on no brainers.  Things
I cannot decide to agree or disagree are not mentioned in this
message.

>  * git-fetch has to be in working root.  If I can do git-push
>  from anywhere in my tree, why can't I do git-fetch?
>  * git-reset has to be in working root.  If you typically sit
>  in, say "src/", it's annoying to have to change directory to
>  do a reset.
>  * git-verify-tag would be nicer as a switch to git-tag

True and true and true; let's make them happen.

>  * git-commit doesn't (generally) have output - after a
>  commit, it's difficult to know if anything happened.  Get
>  users used to the idea of hashes to identify commits by
>  telling them which one they just made.

I am moderately against making a command verbosely report when
it did exactly what it was told to do, _unless_ the command is
expected to take longer than other commands in git suite, or it
is something the user rarely runs.

>  * git-branch is not verbose enough when creating a new
>  branch, for a new user a little reassurance that what they
>  meant to happen has happened would be nice.

The same comment applies here.  

However, perhaps you could make lack of "[user] expert = true"
in ~/.gitconfig to trigger more verbose messages that say "yes
sir I did what I was told to do".

Not interested in implementing that myself at all, though.

>  Tell them if they
>  made a branch as well, which branch they are now on.

I think you are talking about "checkout -b" not commit here;
this might be a borderline (branch creation is less often done
and it might warrant assuring feedback), but I think it still
falls into the "doing exactly what it was told to do" category.

>  * git-init-db says "defaulting to local storage area", as if that is
>    meant to be a helpful message

It probably used to be back when the original tutorial Linus
wrote was still called tutorial.txt; but I agree that the
message is not helpful anymore.

>  * git-merge output is horrible - this affects git-pull,
>  git-rebase, and git-cherry-pick.  Issuing "fatal" errors and
>  then carrying on is very confusing.  Errors in merges appear
>  multiple times.  The files upon which which there is a
>  conflict are spread throughout the output.  Most of the
>  output is not relevant to an average user.

Yes.

>  * git-apply output is horrible.  It says a few things about
>  whitespace on stdin then just finishes.  When it succeeds.
>  When it fails, it just says failed, it doesn't say why a
>  particular hunk failed.

No.  It either says patch is corrupt, or a hunk at this line
does not apply.  I do not see what more would you would want to
ask it to say.

>  * git-commit without "-a" and without an "update-index" says "nothing
>    to commit", which isn't an adequate message to help a user who hasn't
>    realised they need to update the index

Perhaps.

"\n(hint: 'git add' to stage your changes, or 'git commit --all')\n"
in wt-status.c under "[user] expert = false" mode?

>  * git-rebase --skip requires that the offending file be clean with
>      git-checkout HEAD file
>    before the skip will work.  Why?  The fact of the skip is enough
>    knowledge for rebase to know that I don't care if the merge is lost

As long as your solution does not accidentally lose local,
unrelated changes, changing "git-rebase --skip" to do the needed
clean-up itself for the user would be Ok (I think we would want
to loosen the requirement for starting in a totally clean
working tree in the future).

>  * git-rebase/git-cherry-pick/git-reset/etc should all tell
>  the user that they need to run git-prune to tidy up after
>  themselves.

While I agree the users need to be taught about 'prune', I do
think immediately after running the above commands is exactly
the wrong point to run 'prune'.  'prune' should not be run while
you are busily munging the tip of the branch with rebase and
reset to come up with something that you can call "oh, I am done
with this series for now."  Otherwise even lost-found would not
be able to help you.

Also, this sequence creates crufts that need to be pruned:

	edit hello.c
	git add hello.c
        edit hello.c
        git add hello.c

I do not think we would want to suggest 'git prune' upon every
'git add'.

>  * git-add has no output, whether it works or not

"git add no-such-file" complains, and I think that is adequate.
Now with Nico's 'add means adding contents, not path' change is
in, we _might_ want to differentiate adding a path that was
untracked before and updating the contents, but I think this
again falls into "doing exactly as told" category.

>  * git-cat-file is badly named.  git-cat-object would be slightly
>    better.

Not a Porcelain.

We might want to add a pair of built-in internal aliases though:

	[alias]
        	cat = cat-file -p
                less = -p cat-file -p

or have these as samples in template .git/config file.

>  * In general the principle for messages should be the same as for 
>    presentations:
>     - say what you're going to do
>     - do it
>     - say what you did
>    So for example, "git-branch newbranch existingbranch" would say
>     Branching at "existingbranch", hash XXXXXXXXXXXXXXXXXX
>      - created branch "newbranch"
>      - your working branch is "existingbranch"
>    Rather than the nothing that it currently outputs.

In general the principle ought to be not to say anything if the
command does exactly what it was told to do successfully, unless
the operation is expected to take longer than other normal
commands in the git suite, or something that is rarely used.

Perhaps under "[user] expert" control.

Re: What's in git.git (stable)

[Peter Baumann]

>>  * git-branch is not verbose enough when creating a new
>>  branch, for a new user a little reassurance that what they
>>  meant to happen has happened would be nice.
>
> The same comment applies here.  
>
> However, perhaps you could make lack of "[user] expert = true"
> in ~/.gitconfig to trigger more verbose messages that say "yes
> sir I did what I was told to do".
>
> Not interested in implementing that myself at all, though.
>
>>  Tell them if they
>>  made a branch as well, which branch they are now on.
>
> I think you are talking about "checkout -b" not commit here;
> this might be a borderline (branch creation is less often done
> and it might warrant assuring feedback), but I think it still
> falls into the "doing exactly what it was told to do" category.
>

Yes. checkout -b works. But only _if_ you have read the manpage.
Someone thinking about branching at the current commit would just have

	git branch

in mind (so would I). Its not obvious to say

	git checkout -b <newbranchname> oldbranch

becouse checkout implies to advance to another version.

-Peter

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Wed, 13 Dec 2006, Junio C Hamano wrote:

> Andy Parkins <andyparkins@gmail.com> writes:
> 
> >  * git-cat-file is badly named.  git-cat-object would be slightly
> >    better.
> 
> Not a Porcelain.
> 
> We might want to add a pair of built-in internal aliases though:
> 
> 	[alias]
>         	cat = cat-file -p
>                 less = -p cat-file -p
> 
> or have these as samples in template .git/config file.

I sent a patch which makes "git show" have that functionality, and 
frankly, I disagree "less" would be a good name for it. It uses the 
_pager_, which is not always "less", and besides, what it does is to show 
that particular blob. So obviously, I think my patch is the best approach.

BTW if you now say "git show master:README" it will show _nothing_, not 
even an error message.

Ciao,

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Johannes Schindelin wrote:

> Hi,
> 
> On Wed, 13 Dec 2006, Junio C Hamano wrote:
> 
> > We might want to add a pair of built-in internal aliases though:
> > 
> > 	[alias]
> >         	cat = cat-file -p
> >                 less = -p cat-file -p
> > 
> > or have these as samples in template .git/config file.
> 
> I sent a patch which makes "git show" have that functionality, and 
> frankly, I disagree "less" would be a good name for it. It uses the 
> _pager_, which is not always "less", and besides, what it does is to show 
> that particular blob. So obviously, I think my patch is the best approach.

I think your approach is pretty sensible too.

Re: What's in git.git (stable)

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> On Thu, 14 Dec 2006, Johannes Schindelin wrote:
>
>> I sent a patch which makes "git show" have that functionality, and 
>> frankly, I disagree "less" would be a good name for it. It uses the 
>> _pager_, which is not always "less", and besides, what it does is to show 
>> that particular blob. So obviously, I think my patch is the best approach.
>
> I think your approach is pretty sensible too.

I think so too for a few reasons.

 * cat-file is a very low level plumbing.  Giving it -p was a
   mistake made by somebody lazy long time ago back when we were
   not all that hot about "user friendliness in Porcelain-ish"
   (the option -p was not originally even meant to be the user
   level; it was merely a helper feature for verify-tag).

 * If we were to call something 'cat' and make a user-level
   command, adding the feature to 'show' is a lot more sensible
   than cat-file; the former takes more than one args already.
   People expect 'cat' to concatenate the arguments.  cat-file
   doesn't.

 * Throwing ls-tree output is the most sensible thing to do at
   'cat-file -p <tree-ish>' level, but not at the UI level (Andy
   compared ls-tree with 'svn list' today).  With 'git show', it
   would be more natural to show ls-tree --name-only by default
   for tree-ish objects, and control the verbosity level with
   command line option.

One minor issue we may need to decide is what to do when show is
given a tag object.  Personally I think the current behaviour of
dereferencing it to commit is fine (people who want to see the
tag can always do 'git-verify-tag -v').

git-show, was Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Wed, 13 Dec 2006, Junio C Hamano wrote:

> One minor issue we may need to decide is what to do when show is
> given a tag object.  Personally I think the current behaviour of
> dereferencing it to commit is fine (people who want to see the
> tag can always do 'git-verify-tag -v').

How about adding the command line option "--tag" to git-show, which makes 
it only show that tag. I'd also vote for a "--verbose|-v" flag to show the 
contents of the tag _before_ showing the referenced object.

Ciao,
Dscho

Re: git-show, was Re: What's in git.git (stable)

[Junio C Hamano]

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

> Hi,
>
> On Wed, 13 Dec 2006, Junio C Hamano wrote:
>
>> One minor issue we may need to decide is what to do when show is
>> given a tag object.  Personally I think the current behaviour of
>> dereferencing it to commit is fine (people who want to see the
>> tag can always do 'git-verify-tag -v').
>
> How about adding the command line option "--tag" to git-show, which makes 
> it only show that tag. I'd also vote for a "--verbose|-v" flag to show the 
> contents of the tag _before_ showing the referenced object.

Sounds sensible.  Please make it so.

Re: git-show, was Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > Hi,
> >
> > On Wed, 13 Dec 2006, Junio C Hamano wrote:
> >
> >> One minor issue we may need to decide is what to do when show is
> >> given a tag object.  Personally I think the current behaviour of
> >> dereferencing it to commit is fine (people who want to see the
> >> tag can always do 'git-verify-tag -v').
> >
> > How about adding the command line option "--tag" to git-show, which makes 
> > it only show that tag. I'd also vote for a "--verbose|-v" flag to show the 
> > contents of the tag _before_ showing the referenced object.
> 
> Sounds sensible.  Please make it so.

Actually, I rethought it. A tag _without_ what it tags makes no sense. See 
my upcoming patch. And git-show really is as Porcelain as it gets, so it 
should Do What I Mean.

Ciao,
Dscho

Re: What's in git.git (stable)

[Andreas Ericsson]

Junio C Hamano wrote:
> Andy Parkins <andyparkins@gmail.com> writes:
> 
>>  * git-add has no output, whether it works or not
> 
> "git add no-such-file" complains, and I think that is adequate.
> Now with Nico's 'add means adding contents, not path' change is
> in, we _might_ want to differentiate adding a path that was
> untracked before and updating the contents, but I think this
> again falls into "doing exactly as told" category.
> 

Well, it should really let the user know if it fails. I for one would 
like to know that. I wasn't aware of the fact that it was silent even in 
those situations (perhaps because I've never run across it).

The errors that need to be reported are, afaics:
Content in 'path/to/file' is ignored according to path/to/.gitignore.
System error X happened while attempting Y.
Hash collisions.

Hash collisions wouldn't be too bad to check for in git add, because it 
only has to compare a single object, although I agree that it probably 
isn't necessary.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: What's in git.git (stable)

[Jakub Narebski]

Andreas Ericsson wrote:
> Junio C Hamano wrote:
>> Andy Parkins <andyparkins@gmail.com> writes:
>> 
>>>  * git-add has no output, whether it works or not
>> 
>> "git add no-such-file" complains, and I think that is adequate.
>> Now with Nico's 'add means adding contents, not path' change is
>> in, we _might_ want to differentiate adding a path that was
>> untracked before and updating the contents, but I think this
>> again falls into "doing exactly as told" category.
>> 
> 
> Well, it should really let the user know if it fails. I for one would 
> like to know that. I wasn't aware of the fact that it was silent even in 
> those situations (perhaps because I've never run across it).
> 
> The errors that need to be reported are, afaics:
> Content in 'path/to/file' is ignored according to path/to/.gitignore.

This is not an error, just a warning. Sometimes user want's to add a file
which is otherwise ignored (e.g. due to glob), sometimes user adds ignored
file by mistake.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Andy Parkins]

On Wednesday 2006 December 13 23:31, Junio C Hamano wrote:

> I am moderately against making a command verbosely report when

I'm not sure "verbose" is the word for one extra line of output:

$ git commit
Revision XXXXXXXXXXXXXXXXXX successfully added.

I'd actually argue that git-commit is a particular problem because it's too 
fast.  You quit editing your commit message and bang, you're back at the 
command line.  Then you run git-log to make sure it really was committed.

> it did exactly what it was told to do, _unless_ the command is
> expected to take longer than other commands in git suite, or it
> is something the user rarely runs.

In the specific case of commit I really think the hash that was added needs to 
be printed.  I often do a series of git-commits on separate files; to find 
out the hash of one of those recent commits I then hop over to qgit to look.  
If it were right there on my terminal I wouldn't need to have qgit open all 
the time.

> >  * git-branch is not verbose enough when creating a new
> The same comment applies here.

Right back at you.  "what it was told to do", is not a clear cut thing.  Bear 
in mind that users make mistakes (I certainly do), so what I told it to do 
was not necessarily what I wanted it to do.  With no output to tell me what 
actually happened, it makes it harder to go back and see what you did wrong.

> However, perhaps you could make lack of "[user] expert = true"
> in ~/.gitconfig to trigger more verbose messages that say "yes
> sir I did what I was told to do".

I've always thought that programs that needed an expert/beginner split were 
badly designed.

I'm not sure you're characterising the messages correctly with "yes
sir I did what I was told to do".  That sort of output would truly be useless.  
However, going back to my git-commit example, I didn't say "commit and give 
this the hash XXXXXXXX", I said "commit".  git makes up the hash for me, and 
so should really tell me that hash.

> Not interested in implementing that myself at all, though.

I've gotten a far more positive response than I'd expected, so it doesn't 
surprise me.

> >  Tell them if they
> >  made a branch as well, which branch they are now on.
>
> I think you are talking about "checkout -b" not commit here;
> this might be a borderline (branch creation is less often done
> and it might warrant assuring feedback), but I think it still
> falls into the "doing exactly what it was told to do" category.

You're right, I was.  The reason I think feedback is useful is because of the 
two ways of making a new branch:
 - git-branch XYZ
   This makes a new branch but DOESN'T leave me on XYZ
 - git-commit -b XYZ
   This makes a new branch and switches to XYZ
I can't tell you the number of times I get this wrong.  It's not because I 
don't know if I stop to think, it's because I'm thinking about the project, 
not the VCS.

> No.  It either says patch is corrupt, or a hunk at this line
> does not apply.  I do not see what more would you would want to
> ask it to say.

I've been building a repository that contains every kernel release since 
v1.0.0; I did it by downloading every patch and "git-apply"ing them one at a 
time.  Along the way, I had a few occasions where the patch didn't apply.  I 
would get the "hunk didn't apply" message. (e.g. v1.1/patch54.bz2 if you're 
interested)

Now - it /should/ apply, this is a published patch; I investigated each one, 
and it was always down to a whitespace problem.  The current version didn't 
have the same whitespace as the patch was expecting; often part of a much 
larger patch which mostly applied.  git-apply could have told me...

While applying hunk #17, the following update would not apply to the file
this/that/theother.c
-#endif
+#endif

Instead I had to git-checkout HEAD; bzcat patch | git-apply --reject; 
find . -name "*.rej"; vim; git update-index; blah, blah blah.

> As long as your solution does not accidentally lose local,
> unrelated changes, changing "git-rebase --skip" to do the needed
> clean-up itself for the user would be Ok (I think we would want

Of course; never discarding data always takes precedence.

> While I agree the users need to be taught about 'prune', I do
> think immediately after running the above commands is exactly
> the wrong point to run 'prune'.  'prune' should not be run while
> you are busily munging the tip of the branch with rebase and
> reset to come up with something that you can call "oh, I am done
> with this series for now."  Otherwise even lost-found would not
> be able to help you.

Absolutely; I wasn't suggesting that the message should say "now run 
git-prune"; otherwise we might as well run git-prune ourselves.  I don't 
really know that the solution is; but I do think we need one.

> In general the principle ought to be not to say anything if the
> command does exactly what it was told to do successfully, unless
> the operation is expected to take longer than other normal
> commands in the git suite, or something that is rarely used.

git is its own worst enemy here I think.  I still have doubts that something 
actually happened when I run commands because they return so quickly.

> Perhaps under "[user] expert" control.

I think the problem with that is going to be that there will be disagreement 
about which commands should output what in which mode.  "I like git-commit to 
tell me what it committed, but don't want git-add to list files" sorts of 
thing.



Andy

-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> $ git commit
> Revision XXXXXXXXXXXXXXXXXX successfully added.
>
> I'd actually argue that git-commit is a particular problem because it's too 
> fast.  You quit editing your commit message and bang, you're back at the 
> command line.  Then you run git-log to make sure it really was committed.

You keep repeating that you want to know the object name of the
newly created commit.  I would very strongly agree with you that
it would be a fatal UI bug of git-commit if that information
were vital for the end user after making each commit.

But you never communicate with your own git repository using the
SHA-1 object names when talking about commits you made recently
(you would have the SHA-1 output from your updated version of
'git commit' command on the screen or in your scrollbuffer for
them -- you would need to refer to commits older than what your
scrollbuffer has in different way anyway).  Git gives branch~<n>
notation, and commands like "git log --pretty=short" and friends
would show them which you can easily cut&paste.  When people
talk about object names on the mailing list, they do so by
asking "git log" and friends to find them out -- it is pretty
much "on demand" type of thing and I do not think continually
mentioning SHA-1 object names buys us anything.

In other words, the following transcript would be possible but
not realistic:

	$ git commit
        Revision deadbeef0000 created.
        : now what did I do?
        $ git show deadbeef0000
        : oops, that is wrong
        $ git reset --hard deadbeef0000^

So I do not think "git commit" is a valid example.  I also agree
with Shawn that "git add" that says 6781 files were added is
pointless.

>> However, perhaps you could make lack of "[user] expert = true"
>> in ~/.gitconfig to trigger more verbose messages that say "yes
>> sir I did what I was told to do".
>
> I've always thought that programs that needed an expert/beginner split were 
> badly designed.

There probably is a truth in that.  Let's not add verbosity
unnecessarily.

I agree with you that making some commands with progress
indication less chatty would be a good clean-up.

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 10:21, Junio C Hamano wrote:

> You keep repeating that you want to know the object name of the

Oh dear, you're right; I am terribly repetative.  Sorry.
Oh dear, you're right; I am terribly repetative.  Sorry.

;-)

> But you never communicate with your own git repository using the
> SHA-1 object names when talking about commits you made recently

How's this then:

$ git commit
$ git commit
$ git commit
$ git reset HEAD^^^

"AGGGHHHHHH!  I meant HEAD^^"

At this point I start running "git-prune -n | grep commit" and some liberal 
use of git-show to try and find the hash of the object so I can do

$ git reset --hard HASH_OF_OBJECT_I_STUPIDLY_ORPHANED

> So I do not think "git commit" is a valid example.  I also agree
> with Shawn that "git add" that says 6781 files were added is
> pointless.

Okay.

> > I've always thought that programs that needed an expert/beginner split
> > were badly designed.
>
> There probably is a truth in that.  Let's not add verbosity
> unnecessarily.

My habit is always to be overly verbose in program output; however, I realise 
that not everybody likes that.  None of these things cause me any difficulty 
in my use of git.  However, my Dad also is an engineer, but he's not so 
comfortable with VCS; for him almost every part of git is a mystery.  
Commands that run and don't say anything are confusing because he didn't 
really know what they were /meant/ to do; he's just got a set of recipes that 
he knows to type.  He's probably an extreme case, and not a good model for 
typical user - on the other hand, I would say that if he can use it, then it 
is officially newbie-friendly. :-)

> I agree with you that making some commands with progress
> indication less chatty would be a good clean-up.

These are actually the ones I feel more strongly about.  Too much output just 
drowns out the information that people really need.


Andy

-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Shawn Pearce]

Andy Parkins <andyparkins@gmail.com> wrote:
> How's this then:
> 
> $ git commit
> $ git commit
> $ git commit
> $ git reset HEAD^^^
> 
> "AGGGHHHHHH!  I meant HEAD^^"
> 
> At this point I start running "git-prune -n | grep commit" and some liberal 
> use of git-show to try and find the hash of the object so I can do

At this point I usually try to politely suggest that users do:

  git repo-config --global core.logAllRefUpdates true

and in the future do something like:

> $ git commit         # {4}
> $ git commit         # {3}
> $ git commit         # {2}
> $ git reset HEAD^^^  # {1}
> 
> "AGGGHHHHHH!  I meant HEAD^^"

  $ git reset HEAD@{4}

should give you what

  $ git reset HEAD^^

would have given had you not added the extra ^.  :-)
 
-- 

Re: What's in git.git (stable)

[Carl Worth]

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

On Thu, 14 Dec 2006 06:45:46 -0500, Shawn Pearce wrote:
> At this point I usually try to politely suggest that users do:
>
>   git repo-config --global core.logAllRefUpdates true
>
> and in the future do something like:

This when-you-first-learn-you-want-them-it's-too-late-to-get-them
aspect of ref logs is really annoying. It sets up an unkind trap for
users.

I know several people have suggested they be enabled by
default. What's the status of that suggestion?  Rejected? Just
awaiting a patch?

-Carl

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

Re: What's in git.git (stable)

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
> This when-you-first-learn-you-want-them-it's-too-late-to-get-them
> aspect of ref logs is really annoying. It sets up an unkind trap for
> users.

Yes.  Which is why its in my ~/.gitconfig.  :-(
 
> I know several people have suggested they be enabled by
> default. What's the status of that suggestion?  Rejected? Just
> awaiting a patch?

Its been suggested and discussed.

But the problem raised is that there are many types of repositories,
and not all should always have reflogs enabled, and its hard to
tell which one should and which shouldn't by default, and its even
worse to force it into a user's ~/.gitconfig as then repositories
which should not have reflogs are getting them anyway.

 * Normal working repository (wants reflogs);
 * Bare private (backup) repository (wants reflogs);
 * Bare shared repository (probably doesn't want reflogs);
 * Import generated repository (probably doesn't want reflogs);

...

Find a way to make git-init-db know the difference magically and
you'll probably see a patch emerge quickly afterwards.  But right
now I don't think anyone really has a great solution to the problem.

I know Junio wrote something on this not too long ago (and it was a
good writeup too) but I can never find threads in gmane's archives,
so I'm just going to leave that to someone else...

-- 

reflog by default?, was Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Shawn Pearce wrote:

>  * Normal working repository (wants reflogs);
>  * Bare private (backup) repository (wants reflogs);
>  * Bare shared repository (probably doesn't want reflogs);
>  * Import generated repository (probably doesn't want reflogs);

In contrast, I think that reflogs make lots of sense for shared repos, 
and less sense for bare (non-shared) ones...

So, I'd say: enable reflog by default, unless it is bare _and_ not shared. 
But then, cmd_init_db() no longer knows if it was called with "--bare" or 
not.

Ciao,
Dscho

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> But the problem raised is that there are many types of repositories,
> and not all should always have reflogs enabled, and its hard to
> tell which one should and which shouldn't by default, and its even
> worse to force it into a user's ~/.gitconfig as then repositories
> which should not have reflogs are getting them anyway.

Thank you for reminding me the reasons why.

However I'd argue that the lack of reflog data is much much worse than 
needlessly having it.

It is therefore much saner to disable it in the config and remove the 
unwanted reflog files than being sorry because it wasn't enabled when 
you would have needed it.

>  * Normal working repository (wants reflogs);
>  * Bare private (backup) repository (wants reflogs);
>  * Bare shared repository (probably doesn't want reflogs);
>  * Import generated repository (probably doesn't want reflogs);

And what would be the actual problem if reflog was enabled (i.e. was not 
explicitly disabled if enabled by default) in those last two cases?

> Find a way to make git-init-db know the difference magically and 
> you'll probably see a patch emerge quickly afterwards.  But right now 
> I don't think anyone really has a great solution to the problem.

I'd say screw that.  The solution should really be this patch:

diff --git a/environment.c b/environment.c
index 84d870c..98275b2 100644
--- a/environment.c
+++ b/environment.c
@@ -15,7 +15,7 @@ int use_legacy_headers = 1;
 int trust_executable_bit = 1;
 int assume_unchanged;
 int prefer_symlink_refs;
-int log_all_ref_updates;
+int log_all_ref_updates = 1;
 int warn_ambiguous_refs = 1;
 int repository_format_version;
 char git_commit_encoding[MAX_ENCODING_LENGTH] = "utf-8";

> I know Junio wrote something on this not too long ago (and it was a
> good writeup too) but I can never find threads in gmane's archives,
> so I'm just going to leave that to someone else...

Well I must have missed it.

But unless there is real harm to have reflog enabled even when you don't 
need it I really think the default should be set to enabled.

Re: What's in git.git (stable)

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> I'd say screw that.  The solution should really be this patch:
>
> diff --git a/environment.c b/environment.c
> index 84d870c..98275b2 100644
> --- a/environment.c
> +++ b/environment.c
> @@ -15,7 +15,7 @@ int use_legacy_headers = 1;
>  int trust_executable_bit = 1;
>  int assume_unchanged;
>  int prefer_symlink_refs;
> -int log_all_ref_updates;
> +int log_all_ref_updates = 1;
>  int warn_ambiguous_refs = 1;
>  int repository_format_version;
>  char git_commit_encoding[MAX_ENCODING_LENGTH] = "utf-8";
>

That changes what the command does to existing repositories,
which is somewhat impolite.

I am not opposed too much to an updated version of the tool that
sets the configuration on by default for newly created
repositories, though.

Re: What's in git.git (stable)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Nicolas Pitre <nico@cam.org> writes:
> 
> > I'd say screw that.  The solution should really be this patch:
> >
> > diff --git a/environment.c b/environment.c
> > index 84d870c..98275b2 100644
> > --- a/environment.c
> > +++ b/environment.c
> > @@ -15,7 +15,7 @@ int use_legacy_headers = 1;
> >  int trust_executable_bit = 1;
> >  int assume_unchanged;
> >  int prefer_symlink_refs;
> > -int log_all_ref_updates;
> > +int log_all_ref_updates = 1;
> >  int warn_ambiguous_refs = 1;
> >  int repository_format_version;
> >  char git_commit_encoding[MAX_ENCODING_LENGTH] = "utf-8";
> >
> 
> That changes what the command does to existing repositories,
> which is somewhat impolite.

Yes, but users are forgetting to enable them.  They will work in
a new repository having that feature, move to an older one and not
have it, but expect it to be there.

As I recall the primary objection to enabling them by default
when I first introduced them was that core.logAllRefUpdates=true
meant that refs/tags/<name> were also being logged.  This was not a
great idea as tags generally did not change once they were created.
You fixed that and now it just makes sense to enable it for branch
heads all of the time.

> I am not opposed too much to an updated version of the tool that
> sets the configuration on by default for newly created
> repositories, though.

I almost did that in my patch - but decided against it for the
reason I just noted above.

Does anyone on the mailing list really have an objection to having
reflogs on by default?

About the only trouble that can cause is a failed push when
git-receive-pack needs to generate the reflog entry but cannot
get the user's committer data because their gecos information
doesn't exist.

-- 

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> Junio C Hamano <junkio@cox.net> wrote:
> > That changes what the command does to existing repositories,
> > which is somewhat impolite.
> 
> Yes, but users are forgetting to enable them.  They will work in
> a new repository having that feature, move to an older one and not
> have it, but expect it to be there.

I concur entirely.

> > I am not opposed too much to an updated version of the tool that
> > sets the configuration on by default for newly created
> > repositories, though.
> 
> I almost did that in my patch - but decided against it for the
> reason I just noted above.
> 
> Does anyone on the mailing list really have an objection to having
> reflogs on by default?

I certainly don't.

Re: What's in git.git (stable)

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Does anyone on the mailing list really have an objection to having
> reflogs on by default?

When you talk about potential breakage for existing users, you
should not be asking people on THIS list.  You instead should
talk with or at least think about people on linux-kernel, x.org
and wine people, and possibly others.  git is maturing, and we
cannot expect that most of the users are paying attention to
what is happening on this list anymore.

I 100% agree that it makes sense to have reflog enabled for a
repository with an associated worktree.  I would say that we do
not even need it to be conditional on the configuration variable
for such a repository.

My answer to your question is:

	kernel.org:/pub/scm/

I would REALLY be worried to have reflog enabled at a public
distribution point where the only ways the owners interact with
it daily are 'git push' and 'git pull'.  As you mentioned, there
is one extra potential receive-pack failure, and in general it
is one more thing that can go wrong, and hard to notice breakage
because it is on the other side of the connection.

Worse yet, there is no easy way to garbage collect.  Even in an
end-user repository with a worktree, the only way to garbage
collect older reflog entries is to edit the reflog files to
remove the top part.

Maybe a check to say if $GIT_DIR is ".git" or ends with "/.git"
then enable it and otherwise honor the configuration variable,
without changing the default in the code (with your patch) nor
in the default configuration ("enable for new repositories" as I
suggested) might be a workable compromise.

[PATCH] Enable reflogs by default in any repository with a working directory.

[Shawn O. Pearce]

New and experienced Git users alike are finding out too late that
they forgot to enable reflogs in the current repository, and cannot
use the information stored within it to recover from an incorrectly
entered command such as `git reset --hard HEAD^^^` when they really
meant HEAD^^ (aka HEAD~2).

So enable reflogs by default in all future versions of Git, unless
the user specifically disables it with:

  [core]
    logAllRefUpdates = false

in their .git/config or ~/.gitconfig.

We only enable reflogs in repositories that have a working directory
associated with them, as shared/bare repositories do not have
an easy means to prune away old log entries, or may fail logging
entirely if the user's gecos information is not valid during a push.
This heuristic was suggested on the mailing list by Junio.

Documentation was also updated to indicate the new default behavior.
We probably should start to teach usuing the reflog to recover
from mistakes in some of the tutorial material, as new users are
likely to make a few along the way and will feel better knowing
they can recover from them quickly and easily, without fsck-objects'
lost+found features.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 Documentation/config.txt |    7 +++++--
 builtin-init-db.c        |    4 ++++
 cache.h                  |    1 +
 environment.c            |    9 +++++++++
 4 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index a3587f8..8abb082 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -79,8 +79,11 @@ core.logAllRefUpdates::
 	file is automatically created for branch heads.
 
 	This information can be used to determine what commit
-	was the tip of a branch "2 days ago".  This value is
-	false by default (no automated creation of log files).
+	was the tip of a branch "2 days ago".
+
+	This value is true by default in a repository that has
+	a working directory associated with it, and false by
+	default in a bare repository.
 
 core.repositoryFormatVersion::
 	Internal variable identifying the repository format and layout
diff --git a/builtin-init-db.c b/builtin-init-db.c
index 235a0ee..214fc8e 100644
--- a/builtin-init-db.c
+++ b/builtin-init-db.c
@@ -239,6 +239,10 @@ static void create_default_files(const char *git_dir, const char *template_path)
 		git_config_set("core.filemode",
 			       filemode ? "true" : "false");
 	}
+
+	/* Enable logAllRefUpdates if a working tree is attached */
+	git_config_set("core.logallrefupdates",
+		!is_bare_git_dir(git_dir) ? "true" : "false");
 }
 
 static const char init_db_usage[] =
diff --git a/cache.h b/cache.h
index f2ec5c8..2d3df98 100644
--- a/cache.h
+++ b/cache.h
@@ -123,6 +123,7 @@ extern int cache_errno;
 #define INDEX_ENVIRONMENT "GIT_INDEX_FILE"
 #define GRAFT_ENVIRONMENT "GIT_GRAFT_FILE"
 
+extern int is_bare_git_dir(const char *dir);
 extern const char *get_git_dir(void);
 extern char *get_object_directory(void);
 extern char *get_refs_directory(void);
diff --git a/environment.c b/environment.c
index 84d870c..b7256eb 100644
--- a/environment.c
+++ b/environment.c
@@ -48,6 +48,15 @@ static void setup_git_env(void)
 	git_graft_file = getenv(GRAFT_ENVIRONMENT);
 	if (!git_graft_file)
 		git_graft_file = xstrdup(git_path("info/grafts"));
+	log_all_ref_updates = !is_bare_git_dir(git_dir);
+}
+
+int is_bare_git_dir (const char *dir)
+{
+	if (!strcmp(dir, DEFAULT_GIT_DIR_ENVIRONMENT))
+		return 0;
+	const char *s = strrchr(dir, '/');
+	return !s || strcmp(s + 1, DEFAULT_GIT_DIR_ENVIRONMENT);
 }
 
 const char *get_git_dir(void)
-- 

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[J. Bruce Fields]

On Thu, Dec 14, 2006 at 05:41:17PM -0500, Shawn O. Pearce wrote:
> New and experienced Git users alike are finding out too late that
> they forgot to enable reflogs in the current repository, and cannot
> use the information stored within it to recover from an incorrectly
> entered command such as `git reset --hard HEAD^^^` when they really
> meant HEAD^^ (aka HEAD~2).

Stupid question--I assume a mention in the reflog doesn't count as a
real reference to an object, so they won't save you in the case when you
pruned recently?

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[Shawn Pearce]

"J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Thu, Dec 14, 2006 at 05:41:17PM -0500, Shawn O. Pearce wrote:
> > New and experienced Git users alike are finding out too late that
> > they forgot to enable reflogs in the current repository, and cannot
> > use the information stored within it to recover from an incorrectly
> > entered command such as `git reset --hard HEAD^^^` when they really
> > meant HEAD^^ (aka HEAD~2).
> 
> Stupid question--I assume a mention in the reflog doesn't count as a
> real reference to an object, so they won't save you in the case when you
> pruned recently?

Not a stupid question.  Your assumption is correct, its not a real
reference, so prune will remove things that the log mentions but
that refs don't currently mention.

-- 

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[J. Bruce Fields]

On Thu, Dec 14, 2006 at 06:18:32PM -0500, Shawn Pearce wrote:
> "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > Stupid question--I assume a mention in the reflog doesn't count as a
> > real reference to an object, so they won't save you in the case when you
> > pruned recently?
> 
> Not a stupid question.  Your assumption is correct, its not a real
> reference, so prune will remove things that the log mentions but
> that refs don't currently mention.

OK, thanks.  So we just need to make sure that's documented someplace.

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Shawn O. Pearce wrote:

> +int is_bare_git_dir (const char *dir)
> +{
> +	if (!strcmp(dir, DEFAULT_GIT_DIR_ENVIRONMENT))
> +		return 0;
> +	const char *s = strrchr(dir, '/');
> +	return !s || strcmp(s + 1, DEFAULT_GIT_DIR_ENVIRONMENT);
>  }

This function does not really determine if the repo is bare. I have no 
better name for it, though.

Ciao,
Dscho

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[Shawn Pearce]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> Hi,
> 
> On Thu, 14 Dec 2006, Shawn O. Pearce wrote:
> 
> > +int is_bare_git_dir (const char *dir)
> > +{
> > +	if (!strcmp(dir, DEFAULT_GIT_DIR_ENVIRONMENT))
> > +		return 0;
> > +	const char *s = strrchr(dir, '/');
> > +	return !s || strcmp(s + 1, DEFAULT_GIT_DIR_ENVIRONMENT);
> >  }
> 
> This function does not really determine if the repo is bare. I have no 
> better name for it, though.

guess_if_bare_git_dir ?

I struggled to name that thing because it can't really tell, its just
guessing... but it is going to be right most of the time.  Of course
I'm sure there's some Git user somewhere who will confuse it.

-- 

Re: [PATCH] Enable reflogs by default in any repository with a working directory.

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
>> Hi,
>> 
>> On Thu, 14 Dec 2006, Shawn O. Pearce wrote:
>> 
>> > +int is_bare_git_dir (const char *dir)
>> > +{
>> > +	if (!strcmp(dir, DEFAULT_GIT_DIR_ENVIRONMENT))
>> > +		return 0;
>> > +	const char *s = strrchr(dir, '/');
>> > +	return !s || strcmp(s + 1, DEFAULT_GIT_DIR_ENVIRONMENT);
>> >  }
>> 
>> This function does not really determine if the repo is bare. I have no 
>> better name for it, though.
>
> guess_if_bare_git_dir ?
>
> I struggled to name that thing because it can't really tell, its just
> guessing... but it is going to be right most of the time.  Of course
> I'm sure there's some Git user somewhere who will confuse it.

I think the name is fine, but probably a comment in front would
help unconfuse people.

	/* Does it look like a repository without a working tree? */

Unfortunately there currently are public bare repositories that
have index under them because they were primed by rsync from
developers' working repositories.  I do not think it is
unreasonable to persuade owners of them to drop index -- then we
could use absence of $GIT_DIR/index as a strong clue that the
repository is bare.

Re: What's in git.git (stable)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Maybe a check to say if $GIT_DIR is ".git" or ends with "/.git"
> then enable it and otherwise honor the configuration variable,
> without changing the default in the code (with your patch) nor
> in the default configuration ("enable for new repositories" as I
> suggested) might be a workable compromise.

See my latest patch.  Though that patch also sets the value in the
config file, much as core.filemode is also set in the config file,
based on the guess determined by init-db at the time it was executed.

-- 

Re: What's in git.git (stable)

[Andreas Ericsson]

Shawn Pearce wrote:
> 
> About the only trouble that can cause is a failed push when
> git-receive-pack needs to generate the reflog entry but cannot
> get the user's committer data because their gecos information
> doesn't exist.
> 

In that case, it would be best if it let the commit go through using 
only the username. Reflogs are fixable afterwards, so there's no real 
harm done.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: What's in git.git (stable)

[Junio C Hamano]

Andreas Ericsson <ae@op5.se> writes:

> Shawn Pearce wrote:
>>
>> About the only trouble that can cause is a failed push when
>> git-receive-pack needs to generate the reflog entry but cannot
>> get the user's committer data because their gecos information
>> doesn't exist.
>
> In that case, it would be best if it let the commit go through using
> only the username. Reflogs are fixable afterwards, so there's no real
> harm done.

This sounds sensible, regardless of the current discussion on
the default 'logallrefupdates' setting.

Volunteers?

Re: What's in git.git (stable)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Andreas Ericsson <ae@op5.se> writes:
> 
> > Shawn Pearce wrote:
> >>
> >> About the only trouble that can cause is a failed push when
> >> git-receive-pack needs to generate the reflog entry but cannot
> >> get the user's committer data because their gecos information
> >> doesn't exist.
> >
> > In that case, it would be best if it let the commit go through using
> > only the username. Reflogs are fixable afterwards, so there's no real
> > harm done.
> 
> This sounds sensible, regardless of the current discussion on
> the default 'logallrefupdates' setting.
> 
> Volunteers?

Its a good idea.  I'll do it later tonight, after dinner.

-- 

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > I'd say screw that.  The solution should really be this patch:
> >
> > diff --git a/environment.c b/environment.c
> > index 84d870c..98275b2 100644
> > --- a/environment.c
> > +++ b/environment.c
> > @@ -15,7 +15,7 @@ int use_legacy_headers = 1;
> >  int trust_executable_bit = 1;
> >  int assume_unchanged;
> >  int prefer_symlink_refs;
> > -int log_all_ref_updates;
> > +int log_all_ref_updates = 1;
> >  int warn_ambiguous_refs = 1;
> >  int repository_format_version;
> >  char git_commit_encoding[MAX_ENCODING_LENGTH] = "utf-8";
> >
> 
> That changes what the command does to existing repositories,
> which is somewhat impolite.

You must be kidding, aren't you?

Just in case you really are serious, let's pretend that being impolite 
for something that has the potential of saving people's arses is 
certainly worth it, much more that the little inconvenience of having 
log files mysteriously appear and make no harm otherwise.

> I am not opposed too much to an updated version of the tool that
> sets the configuration on by default for newly created
> repositories, though.

Hmmm....

Well it is just that I strongly believe users with existing repos have 
no really valid reason to not have this feature enabled.  But making it 
on in a default config file at repo creation time is better than 
nothing.

Re: What's in git.git (stable)

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> That changes what the command does to existing repositories,
>> which is somewhat impolite.
>
> You must be kidding, aren't you?

I am dead serious.  I do not have _any_ issue on existing
repositories with a working tree, but I care deeply about public
distribution points.  See my other message.

[PATCH] Enable reflogs by default in all repositories.

[Shawn O. Pearce]

New and experienced Git users alike are finding out too late that
they forgot to enable reflogs in the current repository, and cannot
use the information stored within it to recover from an incorrectly
entered command such as `git reset --hard HEAD^^^` when they really
meant HEAD^^ (aka HEAD~2).

So enable reflogs by default in all future versions of Git, unless
the user specifically disables it with:

  [core]
    logAllRefUpdates = false

in their .git/config or ~/.gitconfig.

Documentation was also updated to indicate the new default behavior.
We probably should start to teach usuing the reflog to recover
from mistakes in some of the tutorial material, as new users are
likely to make a few along the way and will feel better knowing
they can recover from them quickly and easily, without fsck-objects'
lost+found features.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 Documentation/config.txt |    3 ++-
 environment.c            |    2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index a3587f8..e093bcd 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -80,7 +80,8 @@ core.logAllRefUpdates::
 
 	This information can be used to determine what commit
 	was the tip of a branch "2 days ago".  This value is
-	false by default (no automated creation of log files).
+	true by default to activate automated creation of log
+	files for all branch heads.
 
 core.repositoryFormatVersion::
 	Internal variable identifying the repository format and layout
diff --git a/environment.c b/environment.c
index 84d870c..98275b2 100644
--- a/environment.c
+++ b/environment.c
@@ -15,7 +15,7 @@ int use_legacy_headers = 1;
 int trust_executable_bit = 1;
 int assume_unchanged;
 int prefer_symlink_refs;
-int log_all_ref_updates;
+int log_all_ref_updates = 1;
 int warn_ambiguous_refs = 1;
 int repository_format_version;
 char git_commit_encoding[MAX_ENCODING_LENGTH] = "utf-8";
-- 

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> Andy Parkins <andyparkins@gmail.com> wrote:
> > How's this then:
> > 
> > $ git commit
> > $ git commit
> > $ git commit
> > $ git reset HEAD^^^
> > 
> > "AGGGHHHHHH!  I meant HEAD^^"
> > 
> > At this point I start running "git-prune -n | grep commit" and some liberal 
> > use of git-show to try and find the hash of the object so I can do
> 
> At this point I usually try to politely suggest that users do:
> 
>   git repo-config --global core.logAllRefUpdates true
> 

And this is where I politely say that this option should be true by 
default for everybody.

I don't recall why it isn't so yet.

Re: What's in git.git (stable)

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Andy Parkins <andyparkins@gmail.com> wrote:
>> How's this then:
>> 
>> $ git commit
>> $ git commit
>> $ git commit
>> $ git reset HEAD^^^
>> 
>> "AGGGHHHHHH!  I meant HEAD^^"
>> 
>> At this point I start running "git-prune -n | grep commit" and some liberal 
>> use of git-show to try and find the hash of the object so I can do
>
> At this point I usually try to politely suggest that users do:
>
>   git repo-config --global core.logAllRefUpdates true
>
> and in the future do something like:
>
>> $ git commit         # {4}
>> $ git commit         # {3}
>> $ git commit         # {2}
>> $ git reset HEAD^^^  # {1}
>> 
>> "AGGGHHHHHH!  I meant HEAD^^"
>
>   $ git reset HEAD@{4}
>
> should give you what
>
>   $ git reset HEAD^^
>
> would have given had you not added the extra ^.  :-)

Correct but a bad example that does not demonstrate the real
power of reflog.  Andy's AGGGHHHHHH can be recovered with a
simple:

	$ git reset ORIG_HEAD

The real beauty of reflog is that you can usually count number
of commands (not just commit) the way you did and recover with
the @{n} syntax.  With one caveat -- a porcelain might implement
what it does as more than one transaction on the ref, in which
case counting commands does not help.  You need to first make
sure the value of n in @{n} you thought is appropriate is really
the one you want; you would always run "git show -s HEAD@{4}"
before doing the recovering reset in practice, in other words.

And it is not very easy to view where ref was in each step with
existing set of tools.

Not until the attached patch, which was very lightly tested.
You would use it like this:

    $ git-show-branch --reflog next
    ! [next@{0}] Merge branch 'js/show' into next
     ! [next@{1}] Merge branch 'jc/cdup' into next
      ! [next@{2}] Merge branch 'master' into next
       ! [next@{3}] Merge branch 'jc/cdup' into next
    ----
    -    [next@{0}] Merge branch 'js/show' into next
    +    [next@{0}^2] git-show: grok blobs, trees and tags, too
    --   [next@{1}] Merge branch 'jc/cdup' into next
    ++   [next@{1}^2] git-reset [--mixed] <tree> [--] <paths>...
    ++   [next@{1}^2^] git-reset: make it work from within a subdirectory.
    ++   [next@{1}^2~2] git-fetch: make it work from within a subdirectory.
    ++   [next@{0}^2^] INSTALL: no need to have GNU diff installed
    --   [next@{0}^2~2] Merge branch 'maint'
    ++   [next@{0}^2~2^2] Bypass expensive content comparsion during...
       - [next@{3}] Merge branch 'jc/cdup' into next
       + [next@{3}^2] git-reset [--mixed] <tree> [--] <paths>...
       + [next@{3}^2^] git-reset: make it work from within a subdirectory.
       + [next@{3}^2~2] git-fetch: make it work from within a subdirectory.
       + [next@{3}^2~3] Bypass expensive content comparsion during re...
    ++ + [next@{0}^2~3] Update git-diff documentation
    -- - [next@{0}^2~4] Merge branch 'jc/diff--cached'
    ++ + [next@{0}^2~5] git-svn: allow both diff.color and color.diff
    ++ + [next@{0}^2~6] repacked packs should be read-only
    ---- [next@{2}] Merge branch 'master' into next

This shows the actual reflog from the 'next' branch on my
primary repository.  It shows that I did a merge of jc/cdup
branch into 'next' to run tests at next@{3}, but later rewound
that merge at next@{2} and merged the rebased jc/cdup again
later at next@{1} [*1*].  


[Footnote]

*1* Of course, I did all of the above rewinding and rebasing
before pushing the result out, so the general public do not have
to worry about rewinding and rebasing.


---

diff --git a/builtin-show-branch.c b/builtin-show-branch.c
index fb1a400..559bb18 100644
--- a/builtin-show-branch.c
+++ b/builtin-show-branch.c
@@ -6,7 +6,7 @@
 #include "builtin.h"
 
 static const char show_branch_usage[] =
-"git-show-branch [--sparse] [--current] [--all] [--heads] [--tags] [--topo-order] [--more=count | --list | --independent | --merge-base ] [--topics] [<refs>...]";
+"git-show-branch [--sparse] [--current] [--all] [--heads] [--tags] [--topo-order] [--more=count | --list | --independent | --merge-base ] [--topics] [<refs>...] | --reflog[=n] <branch>";
 
 static int default_num;
 static int default_alloc;
@@ -17,6 +17,8 @@ static const char **default_arg;
 #define REV_SHIFT	 2
 #define MAX_REVS	(FLAG_BITS - REV_SHIFT) /* should not exceed bits_per_int - REV_SHIFT */
 
+#define DEFAULT_REFLOG	4
+
 static struct commit *interesting(struct commit_list *list)
 {
 	while (list) {
@@ -570,6 +572,7 @@ int cmd_show_branch(int ac, const char **av, const char *prefix)
 	int head_at = -1;
 	int topics = 0;
 	int dense = 1;
+	int reflog = 0;
 
 	git_config(git_show_branch_config);
 
@@ -615,6 +618,15 @@ int cmd_show_branch(int ac, const char **av, const char *prefix)
 			dense = 0;
 		else if (!strcmp(arg, "--date-order"))
 			lifo = 0;
+		else if (!strcmp(arg, "--reflog")) {
+			reflog = DEFAULT_REFLOG;
+		}
+		else if (!strncmp(arg, "--reflog=", 9)) {
+			char *end;
+			reflog = strtoul(arg + 9, &end, 10);
+			if (*end != '\0')
+				die("unrecognized reflog count '%s'", arg + 9);
+		}
 		else
 			usage(show_branch_usage);
 		ac--; av++;
@@ -622,7 +634,7 @@ int cmd_show_branch(int ac, const char **av, const char *prefix)
 	ac--; av++;
 
 	/* Only one of these is allowed */
-	if (1 < independent + merge_base + (extra != 0))
+	if (1 < independent + merge_base + (extra != 0) + (!!reflog))
 		usage(show_branch_usage);
 
 	/* If nothing is specified, show all branches by default */
@@ -631,9 +643,22 @@ int cmd_show_branch(int ac, const char **av, const char *prefix)
 
 	if (all_heads + all_tags)
 		snarf_refs(all_heads, all_tags);
-	while (0 < ac) {
-		append_one_rev(*av);
-		ac--; av++;
+	if (reflog) {
+		int reflen;
+		if (!ac)
+			die("--reflog option needs one branch name");
+		reflen = strlen(*av);
+		for (i = 0; i < reflog; i++) {
+			char *name = xmalloc(reflen + 20);
+			sprintf(name, "%s@{%d}", *av, i);
+			append_one_rev(name);
+		}
+	}
+	else {
+		while (0 < ac) {
+			append_one_rev(*av);
+			ac--; av++;
+		}
 	}
 
 	head_p = resolve_ref("HEAD", head_sha1, 1, NULL);

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006, December 14 21:58, Junio C Hamano wrote:

> Correct but a bad example that does not demonstrate the real
> power of reflog.  Andy's AGGGHHHHHH can be recovered with a
> simple:
>
> 	$ git reset ORIG_HEAD

HAHA!  I knew reading this mailing list would pay off.

It amazes me that there is always an answer.  It's almost becoming a 
pantomime - I say "well git can't do this", and you say "oh yes it can".


Andy

-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: What's in git.git (stable)

[Jakub Narebski]

Andy Parkins wrote:

> On Thursday 2006, December 14 21:58, Junio C Hamano wrote:
> 
>> Correct but a bad example that does not demonstrate the real
>> power of reflog.  Andy's AGGGHHHHHH can be recovered with a
>> simple:
>>
>>      $ git reset ORIG_HEAD
> 
> HAHA!  I knew reading this mailing list would pay off.
> 
> It amazes me that there is always an answer.  It's almost becoming a 
> pantomime - I say "well git can't do this", and you say "oh yes it can".

And it is mentioned in git-reset(1), although:

 * it would be nice to have example with ORIG_HEAD about how
   to recover from bad (wrong) git reset in EXAMPLES section.

 * it would be nice to mention that the first example can
   be now done with simply "edit; git commit -a --amend"
   instead of "git reset --soft HEAD^; edit; git commit -a -c ORIG_HEAD"
   (which can fail for merges).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Jakub Narebski]

Andy Parkins wrote:

By the way, could you use slightly smaller number of columns? TIA.

> On Thursday 2006 December 14 10:21, Junio C Hamano wrote:

>> But you never communicate with your own git repository using the
>> SHA-1 object names when talking about commits you made recently
> 
> How's this then:
> 
> $ git commit
> $ git commit
> $ git commit
> $ git reset HEAD^^^
> 
> "AGGGHHHHHH!  I meant HEAD^^"
> 
> At this point I start running "git-prune -n | grep commit" and some liberal 
> use of git-show to try and find the hash of the object so I can do
> 
> $ git reset --hard HASH_OF_OBJECT_I_STUPIDLY_ORPHANED

That is what reflog is for. By the way, is core.logAllRefUpdates set
to "true" (or "heads") by default now?

Although I'm not against

  $ git commit -v
  Revision XXXXXXXXXXXXXXXXXX successfully added.
 
Notice -v/-verbose option.

>> So I do not think "git commit" is a valid example.  I also agree
>> with Shawn that "git add" that says 6781 files were added is
>> pointless.
> 
> Okay.

And git-add has -v option (although not --verbose).

>>> I've always thought that programs that needed an expert/beginner split
>>> were badly designed.
>>
>> There probably is a truth in that.  Let's not add verbosity
>> unnecessarily.
> 
> My habit is always to be overly verbose in program output; however, I realise 
> that not everybody likes that.  None of these things cause me any difficulty 
> in my use of git.  However, my Dad also is an engineer, but he's not so 
> comfortable with VCS; for him almost every part of git is a mystery.  
> Commands that run and don't say anything are confusing because he didn't 
> really know what they were /meant/ to do; he's just got a set of recipes that 
> he knows to type.  He's probably an extreme case, and not a good model for 
> typical user - on the other hand, I would say that if he can use it, then it 
> is officially newbie-friendly. :-)

It would be nice to have some generic place in git config to specify
default options to git commands (at least for interactive shell). It
cannot be done using aliases. Perhaps defaults.<command> config variable?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Nicolas Pitre]

On Fri, 15 Dec 2006, Jakub Narebski wrote:

> It would be nice to have some generic place in git config to specify
> default options to git commands (at least for interactive shell). It
> cannot be done using aliases. Perhaps defaults.<command> config variable?

I would say the alias facility has to be fixed then.

In bash you can alias "ls" to "ls -l" and it just works.

Re: What's in git.git (stable)

[Andreas Ericsson]

Nicolas Pitre wrote:
> On Fri, 15 Dec 2006, Jakub Narebski wrote:
> 
>> It would be nice to have some generic place in git config to specify
>> default options to git commands (at least for interactive shell). It
>> cannot be done using aliases. Perhaps defaults.<command> config variable?
> 
> I would say the alias facility has to be fixed then.
> 
> In bash you can alias "ls" to "ls -l" and it just works.
> 

I think this is because git scripts that need a certain git command to 
work a certain way don't want some alias to kick in and destroy things 
for them. Shell-scripts would have the same problem if you alias "awk" 
to "grep" f.e., which is why prudent shell-scripters use the "unalias 
-a" thing.

Anyways, this should be largely solvable by inventing a "--no-aliases" 
switch to the git wrapper, or by the scripts calling the programs they 
need directly which, afaik, bypasses the alias logic. If it doesn't, it 
should.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: What's in git.git (stable)

[Nicolas Pitre]

On Fri, 15 Dec 2006, Andreas Ericsson wrote:

> Nicolas Pitre wrote:
> > On Fri, 15 Dec 2006, Jakub Narebski wrote:
> > 
> > > It would be nice to have some generic place in git config to specify
> > > default options to git commands (at least for interactive shell). It
> > > cannot be done using aliases. Perhaps defaults.<command> config variable?
> > 
> > I would say the alias facility has to be fixed then.
> > 
> > In bash you can alias "ls" to "ls -l" and it just works.
> > 
> 
> I think this is because git scripts that need a certain git command to work a
> certain way don't want some alias to kick in and destroy things for them.
> Shell-scripts would have the same problem if you alias "awk" to "grep" f.e.,
> which is why prudent shell-scripters use the "unalias -a" thing.

Wouldn't it be possible for aliases to be effective only when issued 
from an interactive shell?  It is certainly true that aliases just make 
no sense in a script.

Re: What's in git.git (stable)

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> Wouldn't it be possible for aliases to be effective only when issued 
> from an interactive shell?  It is certainly true that aliases just make 
> no sense in a script.

Probably, but on Cygwin gitk needs to use 'git foo' to invoke a
command, even if 'git-foo' exists, because 'git-foo' might be a shell
script and the Cygwin wish process cannot execute shell scripts.

Worse it cannot pass down environment variables to git commands.
So it may be a little hard to tell in the git wrapper we are being
run from within gitk (or git-gui)...

-- 

Re: What's in git.git (stable)

[Andreas Ericsson]

Nicolas Pitre wrote:
> On Fri, 15 Dec 2006, Andreas Ericsson wrote:
> 
>> Nicolas Pitre wrote:
>>> On Fri, 15 Dec 2006, Jakub Narebski wrote:
>>>
>>>> It would be nice to have some generic place in git config to specify
>>>> default options to git commands (at least for interactive shell). It
>>>> cannot be done using aliases. Perhaps defaults.<command> config variable?
>>> I would say the alias facility has to be fixed then.
>>>
>>> In bash you can alias "ls" to "ls -l" and it just works.
>>>
>> I think this is because git scripts that need a certain git command to work a
>> certain way don't want some alias to kick in and destroy things for them.
>> Shell-scripts would have the same problem if you alias "awk" to "grep" f.e.,
>> which is why prudent shell-scripters use the "unalias -a" thing.
> 
> Wouldn't it be possible for aliases to be effective only when issued 
> from an interactive shell?  It is certainly true that aliases just make 
> no sense in a script.
> 

Yes, but then aliases wouldn't work in one-liners, which would be a bit 
of a shame and pretty likely to cause some "interesting" bugreports. 
Perhaps an environment variable GIT_IGNORE_ALIAS=yes that git-scripts 
can set at the beginning of execution?

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Fri, 15 Dec 2006, Nicolas Pitre wrote:

> On Fri, 15 Dec 2006, Jakub Narebski wrote:
> 
> > It would be nice to have some generic place in git config to specify
> > default options to git commands (at least for interactive shell). It
> > cannot be done using aliases. Perhaps defaults.<command> config variable?
> 
> I would say the alias facility has to be fixed then.
> 
> In bash you can alias "ls" to "ls -l" and it just works.

So, why not use bash aliases?

Frankly, what git aliases try to achieve is a little bit different from 
bash aliases. Bash knows exactly when a command is interactive, and has a 
clear advantage there. Git _cannot_ know.

Ciao,
Dscho

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Junio C Hamano wrote:

> Andy Parkins <andyparkins@gmail.com> writes:
> 
> > $ git commit
> > Revision XXXXXXXXXXXXXXXXXX successfully added.
> >
> > I'd actually argue that git-commit is a particular problem because it's too 
> > fast.  You quit editing your commit message and bang, you're back at the 
> > command line.  Then you run git-log to make sure it really was committed.
> 
> You keep repeating that you want to know the object name of the
> newly created commit.  I would very strongly agree with you that
> it would be a fatal UI bug of git-commit if that information
> were vital for the end user after making each commit.

I think this is not the point.

Of course the name of the newly created commit isn't _that_ important.

But so is the "Committing initial tree 5220388..." message.

And in the commit case, you are left with a blank screen and just a 
shell prompt after you quit the text editor for the log message, which 
is a bit worrisome.  My initial reflex is not to think "ah it just did 
what I asked it" but rather "hmmm has it just crashed on me?"

Having a single line of feedback when a commit has completed would not 
be overly verbose and remove that impression of committing into a 
void I'd think.

Note that, as I said in another thread, I'm really not advocating for 
git-add to do the same.  The git-add is a relatively simple and 
lightweight operation that has not the same impact as a commit has 
_conceptually_.  It doesn't clear the screen for one thing so just 
returning to the shell prompt (unless -v is used) is plenty sufficient.

I'm following up with a patch to implement what I think should be done.

[PATCH] make commit message a little more consistent and conforting

[Nicolas Pitre]

It is nicer to let the user know when a commit succeeded all the time, 
not only the first time.  Also the commit sha1 is much more useful than 
the tree sha1 in this case.

This patch also introduces a -q switch to supress this message as well 
as the summary of created/deleted files.

Signed-off-by: Nicolas Pitre <nico@cam.org>

---

diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index 47505aa..1c31159 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -336,17 +336,9 @@ $ commit=$(echo 'Initial commit' | git-commit-tree $tree)
 $ git-update-ref HEAD $commit
 ------------------------------------------------
 
-which will say:
-
-----------------
-Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
-----------------
-
-just to warn you about the fact that it created a totally new commit
-that is not related to anything else. Normally you do this only *once*
-for a project ever, and all later commits will be parented on top of an
-earlier commit, and you'll never see this "Committing initial tree"
-message ever again.
+In this case this creates a totally new commit that is not related to
+anything else. Normally you do this only *once* for a project ever, and
+all later commits will be parented on top of an earlier commit.
 
 Again, normally you'd never actually do this by hand. There is a
 helpful script called `git commit` that will do all of this for you. So
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 97d66ef..0b74cd7 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -113,6 +113,9 @@ but can be used to amend a merge commit.
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
+-q|--quiet::
+	Supress commit summary message.
+
 \--::
 	Do not interpret any more arguments as options.
 
diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt
index 6389de5..8606381 100644
--- a/Documentation/tutorial-2.txt
+++ b/Documentation/tutorial-2.txt
@@ -22,14 +22,14 @@ defaulting to local storage area
 $ echo 'hello world' > file.txt
 $ git add .
 $ git commit -a -m "initial commit"
-Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe
+Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
  create mode 100644 file.txt
 $ echo 'hello world!' >file.txt
 $ git commit -a -m "add emphasis"
+Created commit c4d59f390b9cfd4318117afde11d601c1085f241
 ------------------------------------------------
 
-What are the 40 digits of hex that git responded to the first commit
-with?
+What are the 40 digits of hex that git responded to the commit with?
 
 We saw in part one of the tutorial that commits have names like this.
 It turns out that every object in the git history is stored under
@@ -39,13 +39,25 @@ the same data twice (since identical data is given an identical SHA1
 name), and that the contents of a git object will never change (since
 that would change the object's name as well).
 
+It is expected that the content of the commit object you created while
+following the example above generates a different SHA1 hash than
+the one shown above because the commit object records the time when
+it was created and the name of the person performing the commit.
+
 We can ask git about this particular object with the cat-file
-command--just cut-and-paste from the reply to the initial commit, to
-save yourself typing all 40 hex digits:
+command. Don't copy the 40 hex digits from this example but use those
+from your own version. Note that you can shorten it to only a few
+characters to save yourself typing all 40 hex digits:
 
 ------------------------------------------------
-$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe
-tree
+$ git-cat-file -t 54196cc2
+commit
+$ git-cat-file commit 54196cc2
+tree 92b8b694ffb1675e5975148e1121810081dbdffe
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+
+initial commit
 ------------------------------------------------
 
 A tree can refer to one or more "blob" objects, each corresponding to
@@ -102,8 +114,7 @@ $ find .git/objects/
 
 and the contents of these files is just the compressed data plus a
 header identifying their length and their type.  The type is either a
-blob, a tree, a commit, or a tag.  We've seen a blob and a tree now,
-so next we should look at a commit.
+blob, a tree, a commit, or a tag.
 
 The simplest commit to find is the HEAD commit, which we can find
 from .git/HEAD:
diff --git a/builtin-commit-tree.c b/builtin-commit-tree.c
index e2e690a..856f3cd 100644
--- a/builtin-commit-tree.c
+++ b/builtin-commit-tree.c
@@ -107,8 +107,6 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix)
 		if (new_parent(parents))
 			parents++;
 	}
-	if (!parents)
-		fprintf(stderr, "Committing initial tree %s\n", argv[1]);
 
 	init_buffer(&buffer, &size);
 	add_buffer(&buffer, &size, "tree %s\n", sha1_to_hex(tree_sha1));
diff --git a/git-commit.sh b/git-commit.sh
index 05828bb..395bcd2 100755
--- a/git-commit.sh
+++ b/git-commit.sh
@@ -80,6 +80,7 @@ no_edit=
 log_given=
 log_message=
 verify=t
+quiet=
 verbose=
 signoff=
 force_author=
@@ -241,6 +242,10 @@ $1"
 		signoff=t
 		shift
 		;;
+	-q|--q|--qu|--qui|--quie|--quiet)
+		quiet=t
+		shift
+		;;
 	-v|--v|--ve|--ver|--verb|--verbo|--verbos|--verbose)
 		verbose=t
 		shift
@@ -615,11 +620,17 @@ then
 	git-rerere
 fi
 
-if test -x "$GIT_DIR"/hooks/post-commit && test "$ret" = 0
+if test "$ret" = 0
 then
-	"$GIT_DIR"/hooks/post-commit
+	if test -x "$GIT_DIR"/hooks/post-commit 
+	then
+		"$GIT_DIR"/hooks/post-commit
+	fi
+	if test -z "$quiet"
+	then
+		echo "Created${initial_commit:+ initial} commit $commit"
+		git-diff-tree --summary --root --no-commit-id HEAD
+	fi
 fi
 
-test "$ret" = 0 && git-diff-tree --summary --root --no-commit-id HEAD
-

Re: [PATCH] make commit message a little more consistent and conforting

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> It is nicer to let the user know when a commit succeeded all the time, 
> not only the first time.  Also the commit sha1 is much more useful than 
> the tree sha1 in this case.

I agree the commit sha1 is more useful than the tree sha1, but I'm
not really sure its useful to show the commit sha1 post commit.
If you want to show something the diffstat like what git merge does
is better.

For one thing it confirms that git accepted the changes.  For another
it shows you *which* changes it accepted.  Plus it responds just
like git-merge or git-pull does.

Of course the meaning of the diffstat is entirely different in both
cases; in the commit case its what has been recorded while in the
merge case its not only what has been recorded into your current
branch history but also what has been done to your working directory.

-- 

Re: [PATCH] make commit message a little more consistent and conforting

[Andreas Ericsson]

Shawn Pearce wrote:
> Nicolas Pitre <nico@cam.org> wrote:
>> It is nicer to let the user know when a commit succeeded all the time, 
>> not only the first time.  Also the commit sha1 is much more useful than 
>> the tree sha1 in this case.
> 
> I agree the commit sha1 is more useful than the tree sha1, but I'm
> not really sure its useful to show the commit sha1 post commit.
> If you want to show something the diffstat like what git merge does
> is better.
> 

diffstats can be huge though. I'd rather have those only with -v option.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: [PATCH] make commit message a little more consistent and conforting

[Shawn Pearce]

Andreas Ericsson <ae@op5.se> wrote:
> Shawn Pearce wrote:
> >Nicolas Pitre <nico@cam.org> wrote:
> >>It is nicer to let the user know when a commit succeeded all the time, 
> >>not only the first time.  Also the commit sha1 is much more useful than 
> >>the tree sha1 in this case.
> >
> >I agree the commit sha1 is more useful than the tree sha1, but I'm
> >not really sure its useful to show the commit sha1 post commit.
> >If you want to show something the diffstat like what git merge does
> >is better.
> >
> 
> diffstats can be huge though. I'd rather have those only with -v option.

But they are on by default for pull/merge, and disabled by -n.

They are on to tell you what you just got during the pull/merge.
If we want commit to confirm it did something successfully, I think
having it confirm what it committed by way of diffstat makes a lot
of sense.

Unfortunately -n is taken to mean --no-verify by git-commit, so
we probably cannot repurpose it to mean --no-summary, like it is
for merge/pull.

-- 

Re: [PATCH] make commit message a little more consistent and conforting

[Andreas Ericsson]

Shawn Pearce wrote:
> Andreas Ericsson <ae@op5.se> wrote:
>> Shawn Pearce wrote:
>>> Nicolas Pitre <nico@cam.org> wrote:
>>>> It is nicer to let the user know when a commit succeeded all the time, 
>>>> not only the first time.  Also the commit sha1 is much more useful than 
>>>> the tree sha1 in this case.
>>> I agree the commit sha1 is more useful than the tree sha1, but I'm
>>> not really sure its useful to show the commit sha1 post commit.
>>> If you want to show something the diffstat like what git merge does
>>> is better.
>>>
>> diffstats can be huge though. I'd rather have those only with -v option.
> 
> But they are on by default for pull/merge, and disabled by -n.
> 

Yes, but it makes sense for merges where you generally pull someone 
elses work or one of your topic branches because it gives a general feel 
for the amount of modifications and are a sort of conclusion. Commits 
are a different thing, because you should know what kind of changes 
you've just done. If you don't you have other problems. I for one run 
git diff quite frequently when I'm getting close to a commit to make 
sure I don't get only the changes I want. I imagine others do too, so 
getting a diffstat when issuing the actual commit would just be noisy 
and irritating.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: [PATCH] make commit message a little more consistent and conforting

[Shawn Pearce]

Andreas Ericsson <ae@op5.se> wrote:
> Yes, but it makes sense for merges where you generally pull someone 
> elses work or one of your topic branches because it gives a general feel 
> for the amount of modifications and are a sort of conclusion. Commits 
> are a different thing, because you should know what kind of changes 
> you've just done. If you don't you have other problems. I for one run 
> git diff quite frequently when I'm getting close to a commit to make 
> sure I don't get only the changes I want. I imagine others do too, so 
> getting a diffstat when issuing the actual commit would just be noisy 
> and irritating.

I do the same (diff a lot before commit) and thus find commit
outputting anything at all to be noisy and irritating.  Frankly
the new

  git-diff-tree --summary --root --no-commit-id HEAD

that Junio put on the end is already irritating.

But it was added to help users verify that commit did what they
thought it would (see 61f5cb7f).  By the same token sometimes users
accidentally commit files they didn't mean to, or forget to include
files they meant to include.  Showing a diffstat would also be a
final sanity check for them.

-- 

Re: [PATCH] make commit message a little more consistent and conforting

[Andreas Ericsson]

Shawn Pearce wrote:
> Andreas Ericsson <ae@op5.se> wrote:
>> Yes, but it makes sense for merges where you generally pull someone 
>> elses work or one of your topic branches because it gives a general feel 
>> for the amount of modifications and are a sort of conclusion. Commits 
>> are a different thing, because you should know what kind of changes 
>> you've just done. If you don't you have other problems. I for one run 
>> git diff quite frequently when I'm getting close to a commit to make 
>> sure I don't get only the changes I want. I imagine others do too, so 
>> getting a diffstat when issuing the actual commit would just be noisy 
>> and irritating.
> 
> I do the same (diff a lot before commit) and thus find commit
> outputting anything at all to be noisy and irritating.  Frankly
> the new
> 

I could live with one line (Committed revision %d), but a diffstat is 
always 3 lines minimum, which might well turn out to be 2 lines more 
than I changed. That's way too noisy.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: [PATCH] make commit message a little more consistent and conforting

[Nicolas Pitre]

On Fri, 15 Dec 2006, Shawn Pearce wrote:

> I do the same (diff a lot before commit) and thus find commit
> outputting anything at all to be noisy and irritating.  Frankly
> the new
> 
>   git-diff-tree --summary --root --no-commit-id HEAD
> 
> that Junio put on the end is already irritating.
> 
> But it was added to help users verify that commit did what they
> thought it would (see 61f5cb7f).  By the same token sometimes users
> accidentally commit files they didn't mean to, or forget to include
> files they meant to include.  Showing a diffstat would also be a
> final sanity check for them.

Make it with -v.

If the --summary is already irritating to you, imagine how a diffstat 
could be.

Re: [PATCH] make commit message a little more consistent and conforting

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> I do the same (diff a lot before commit) and thus find commit
> outputting anything at all to be noisy and irritating.  Frankly
> the new
>
>   git-diff-tree --summary --root --no-commit-id HEAD
>
> that Junio put on the end is already irritating.
>
> But it was added to help users verify that commit did what they
> thought it would (see 61f5cb7f).

The credit should go Pasky's way.  Add/delete/mode are rarer
events and reminding them is sensible.

We do not show the 'summary' when we are concluding a merge that
conflicted.  Otherwise you will be seeing other people's huge
changes that was just brought in.

Re: [PATCH] make commit message a little more consistent and conforting

[Nicolas Pitre]

On Thu, 14 Dec 2006, Shawn Pearce wrote:

> Nicolas Pitre <nico@cam.org> wrote:
> > It is nicer to let the user know when a commit succeeded all the time, 
> > not only the first time.  Also the commit sha1 is much more useful than 
> > the tree sha1 in this case.
> 
> I agree the commit sha1 is more useful than the tree sha1, but I'm
> not really sure its useful to show the commit sha1 post commit.

It is useful, even if it is not essential.

Since I believe it is a good thing to display _something_ by default 
(and not only with -v as suggested -- please see the reasoning I posted 
yesterday as to what should have some output and what shouldn't), it 
doesn't hurt to display the commit sha1 as well.

First it has the very desirable side effect of making the user slightly 
aware of how git identifies things.  From the first commit a new user 
will notice that git doesn't use any incremental version number but a 
unique identifier that has nothing to do with sequence.  It is not 
expected that people will start _using_ the information printed, but it 
will at least give a feel of how git works.  And it is not like if the 
whole thing took multiple lines to be displayed.

Next it _might_ be used by people.  The fact that it is there might turn 
to be useful.  It is useful in the context of Documentation/tutorial-2.txt
for one where the notion of objects and their relationship is explained 
based on the least amount of steps possible.

So in short I do think there should be something shown after a 
successful commit, and including the commit sha1 doesn't hurt.

> If you want to show something the diffstat like what git merge does
> is better.
> 
> For one thing it confirms that git accepted the changes.  For another
> it shows you *which* changes it accepted.  Plus it responds just
> like git-merge or git-pull does.

I disagree.  My patch does confirm that git accepted the change with 
only one line.  As to which changes were accepted I think that when you 
do the commit you certainly have a pretty good idea already of what is 
going to be committed (you modified/added/removed files yourself, and by 
default git-commit provides you with a summary in the text editor for 
the commit message).

On Fri, 15 Dec 2006, Shawn Pearce wrote:

> Andreas Ericsson <ae@op5.se> wrote:
> > diffstats can be huge though. I'd rather have those only with -v option.
> 
> But they are on by default for pull/merge, and disabled by -n.
> 
> They are on to tell you what you just got during the pull/merge.

The pull/merge case is different.  You are most likely to not know in 
advance what the overall changes will be.  Of course you're supposed to 
know what you're pulling, but unlikely to know about the detail since 
what you merge is remote to your current working tree by definition, and 
even if you happen to be the one who did the changes in the other 
branch/repo, it is certainly not as fresh in your mind than the changes 
you did prior a commit.

And it is true that diffstat can be quite large.  I wouldn't mind the 
diffstat to be added to the commit message summary in the text editor 
though.  And displaying it when -v is used makes also a lot of sense.  
But not by default please.

Re: [PATCH] make commit message a little more consistent and conforting

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> On Fri, 15 Dec 2006, Shawn Pearce wrote:
> > Andreas Ericsson <ae@op5.se> wrote:
> > > diffstats can be huge though. I'd rather have those only with -v option.
> > 
> > But they are on by default for pull/merge, and disabled by -n.
> 
> And it is true that diffstat can be quite large.  I wouldn't mind the 
> diffstat to be added to the commit message summary in the text editor 
> though.  And displaying it when -v is used makes also a lot of sense.  
> But not by default please.

OK, two votes against diffstats by default in commit.  Since I
haven't written a patch for it yet consider it dropped.  ;-)

-- 

Re: [PATCH] make commit message a little more consistent and conforting

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> So in short I do think there should be something shown after a 
> successful commit, and including the commit sha1 doesn't hurt.
> ...
> And it is true that diffstat can be quite large.  I wouldn't mind the 
> diffstat to be added to the commit message summary in the text editor 
> though.  And displaying it when -v is used makes also a lot of sense.  
> But not by default please.

I agree with everything you said in your message, including that
commit object name might help as a learning aid.

We could give something like this, though, if we wanted to:

	$ git commit
        4 files changed, 17 insertions(+), 10 deletions(-)
        mode change 100755 => 100644 test.sh

Re: [PATCH] make commit message a little more consistent and conforting

[Nicolas Pitre]

On Fri, 15 Dec 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > So in short I do think there should be something shown after a 
> > successful commit, and including the commit sha1 doesn't hurt.
> > ...
> > And it is true that diffstat can be quite large.  I wouldn't mind the 
> > diffstat to be added to the commit message summary in the text editor 
> > though.  And displaying it when -v is used makes also a lot of sense.  
> > But not by default please.
> 
> I agree with everything you said in your message, including that
> commit object name might help as a learning aid.
> 
> We could give something like this, though, if we wanted to:
> 
> 	$ git commit
>         4 files changed, 17 insertions(+), 10 deletions(-)
>         mode change 100755 => 100644 test.sh

Actually that would really be nice to have all the time for the
diff --summary output whenever --stat is not provided.  Or maybe a 
--shortstat option.

What about this (on top of my previous patch):

Signed-off-by: Nicolas Pitre <nico@cam.org>

---

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 9cdd171..f12082e 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -21,6 +21,11 @@
 	deleted lines in decimal notation and pathname without
 	abbreviation, to make it more machine friendly.
 
+--shortstat::
+	Output only the last line of the --stat format containing total
+	number of modified files, as well as number of added and deleted
+	lines.
+
 --summary::
 	Output a condensed summary of extended header information
 	such as creations, renames and mode changes.
diff --git a/diff.c b/diff.c
index 0b284b3..d754280 100644
--- a/diff.c
+++ b/diff.c
@@ -809,6 +809,35 @@ static void show_stats(struct diffstat_t* data, struct diff_options *options)
 	       set, total_files, adds, dels, reset);
 }
 
+static void show_shortstats(struct diffstat_t* data)
+{
+	int i, adds = 0, dels = 0, total_files = data->nr;
+
+	if (data->nr == 0)
+		return;
+
+	for (i = 0; i < data->nr; i++) {
+		if (!data->files[i]->is_binary &&
+		    !data->files[i]->is_unmerged) {
+			int added = data->files[i]->added;
+			int deleted= data->files[i]->deleted;
+			if (!data->files[i]->is_renamed &&
+			    (added + deleted == 0)) {
+				total_files--;
+			} else {
+				adds += added;
+				dels += deleted;
+			}
+		}
+		free(data->files[i]->name);
+		free(data->files[i]);
+	}
+	free(data->files);
+
+	printf(" %d files changed, %d insertions(+), %d deletions(-)\n",
+	       total_files, adds, dels);
+}
+
 static void show_numstat(struct diffstat_t* data, struct diff_options *options)
 {
 	int i;
@@ -1767,6 +1796,7 @@ int diff_setup_done(struct diff_options *options)
 		options->output_format &= ~(DIFF_FORMAT_RAW |
 					    DIFF_FORMAT_NUMSTAT |
 					    DIFF_FORMAT_DIFFSTAT |
+					    DIFF_FORMAT_SHORTSTAT |
 					    DIFF_FORMAT_SUMMARY |
 					    DIFF_FORMAT_PATCH);
 
@@ -1777,6 +1807,7 @@ int diff_setup_done(struct diff_options *options)
 	if (options->output_format & (DIFF_FORMAT_PATCH |
 				      DIFF_FORMAT_NUMSTAT |
 				      DIFF_FORMAT_DIFFSTAT |
+				      DIFF_FORMAT_SHORTSTAT |
 				      DIFF_FORMAT_SUMMARY |
 				      DIFF_FORMAT_CHECKDIFF))
 		options->recursive = 1;
@@ -1868,6 +1899,9 @@ int diff_opt_parse(struct diff_options *options, const char **av, int ac)
 	else if (!strcmp(arg, "--numstat")) {
 		options->output_format |= DIFF_FORMAT_NUMSTAT;
 	}
+	else if (!strcmp(arg, "--shortstat")) {
+		options->output_format |= DIFF_FORMAT_SHORTSTAT;
+	}
 	else if (!strncmp(arg, "--stat", 6)) {
 		char *end;
 		int width = options->stat_width;
@@ -2642,7 +2676,7 @@ void diff_flush(struct diff_options *options)
 		separator++;
 	}
 
-	if (output_format & (DIFF_FORMAT_DIFFSTAT|DIFF_FORMAT_NUMSTAT)) {
+	if (output_format & (DIFF_FORMAT_DIFFSTAT|DIFF_FORMAT_SHORTSTAT|DIFF_FORMAT_NUMSTAT)) {
 		struct diffstat_t diffstat;
 
 		memset(&diffstat, 0, sizeof(struct diffstat_t));
@@ -2656,6 +2690,8 @@ void diff_flush(struct diff_options *options)
 			show_numstat(&diffstat, options);
 		if (output_format & DIFF_FORMAT_DIFFSTAT)
 			show_stats(&diffstat, options);
+		else if (output_format & DIFF_FORMAT_SHORTSTAT)
+			show_shortstats(&diffstat);
 		separator++;
 	}
 
diff --git a/diff.h b/diff.h
index 101b2b5..eff4455 100644
--- a/diff.h
+++ b/diff.h
@@ -29,6 +29,7 @@ typedef void (*diff_format_fn_t)(struct diff_queue_struct *q,
 #define DIFF_FORMAT_NUMSTAT	0x0004
 #define DIFF_FORMAT_SUMMARY	0x0008
 #define DIFF_FORMAT_PATCH	0x0010
+#define DIFF_FORMAT_SHORTSTAT	0x0020
 
 /* These override all above */
 #define DIFF_FORMAT_NAME	0x0100
diff --git a/git-commit.sh b/git-commit.sh
index 395bcd2..b9e49ea 100755
--- a/git-commit.sh
+++ b/git-commit.sh
@@ -629,7 +629,7 @@ then
 	if test -z "$quiet"
 	then
 		echo "Created${initial_commit:+ initial} commit $commit"
-		git-diff-tree --summary --root --no-commit-id HEAD
+		git-diff-tree --shortstat --summary --root --no-commit-id HEAD
 	fi
 fi

Re: [PATCH] make commit message a little more consistent and conforting

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> What about this (on top of my previous patch):

Looks good.

Re: What's in git.git (stable)

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

>> >  Tell them if they
>> >  made a branch as well, which branch they are now on.
>>
>> I think you are talking about "checkout -b" not commit here;
>> this might be a borderline (branch creation is less often done
>> and it might warrant assuring feedback), but I think it still
>> falls into the "doing exactly what it was told to do" category.
>
> You're right, I was.  The reason I think feedback is useful is
> because of the two ways of making a new branch:
>
>  - git-branch XYZ
>    This makes a new branch but DOESN'T leave me on XYZ
>  - git-commit -b XYZ
>    This makes a new branch and switches to XYZ
>
> I can't tell you the number of times I get this wrong.  It's not because I 
> don't know if I stop to think, it's because I'm thinking about the project, 
> not the VCS.

This is interesting.  You said "commit -b", were pointed out
that you were talking about "checkout -b", and just after saying
"yup, that is right, I was", you again say "commit -b".

Maybe the users often need this sequence (I personally don't,
but others might):

	$ git checkout ;# or the previous day ended with a clean state
	$ edit edit hack
        $ git checkout -b XYZ ;# the changes are about different stuff
        $ git commit ;# commit the changes there
        $ git checkout master ;# or whatever branch you usually are on

and "git commit -b <newbranch>" might be a handy shortcut for
the last three commands.  I dunno.

And if we had such a variant of commit, then it is doing
something unusual, so I would not oppose (actually I would
probably favor) if the transcript went something like this:

	$ git commit -b XYZ -m "implement 'foo' subcommand" -a
	committed changes to newly created branch XYZ, back on 'master'.
	$ git show-branch master XYZ
        * [master] finishing touches to 'hello world'
         ! [XYZ] implement foo subcommand
        --
         + [XYZ] implement foo subcommand
        -- [master] finishing touches to 'hello world'
	$ exit

Earlier I said that the command should be silent if it did
exactly what it was told to do with some 'unless'es.

 * If the command fails, we should report (no question).

 * If the command succeeds the usual way, staying silent is
   preferable, at least to me.

 * If the command can have more than one mode of successful
   outcome, stating success in which way is not a useless
   verbosity.  E.g. 'git merge' should probably tell you if it
   did a usual three-way or a fast-forward (if the difference
   matters).  Especially reporting an unusual case a bit more
   verbosely than usual is a good thing.

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006, December 14 21:22, Junio C Hamano wrote:

> This is interesting.  You said "commit -b", were pointed out
> that you were talking about "checkout -b", and just after saying
> "yup, that is right, I was", you again say "commit -b".

There truly is something wrong with me.  Is there some sort of record for 
number of mistakes made in one thread?  Have I won yet?

I'm not sure about your "commit -b"; is it wise to have /another/ way of 
making a branch?  I mean - I'm clearly confused enough, have a heart :-)


Andy

-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: What's in git.git (stable)

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> On Thursday 2006, December 14 21:22, Junio C Hamano wrote:
>
>> This is interesting.  You said "commit -b", were pointed out
>> that you were talking about "checkout -b", and just after saying
>> "yup, that is right, I was", you again say "commit -b".
>
> There truly is something wrong with me.

I did not mean it that way.  I only took it as a sign that maybe
"first create and switch to a branch and then work and commit
there, in separate steps", which is how git encourages things to
be done, does not match people's mental model so well.

> I'm not sure about your "commit -b"; is it wise to have /another/ way of 
> making a branch?  I mean - I'm clearly confused enough, have a heart :-)

I said "commit -b <newbranch>" and deliberately avoided saying
"commit -b <anybranch>", because I did not want to open another
can of worms while we are discussing so many good things
already, and my head can hold only a handful topics at once.

But people on the list (and #git channel) sometimes wished an
easy way to help the following workflow.

 * I am in the middle of working on a new feature.  As a good
   git user, I am on a topic branch dedicated for that purpose.

 * While working on it, I find an obvious bug that I would not
   want to fix on the branch (the topic branch I am currently on
   is not about fixing that bug).

 * But I fix it in the working tree anyway, because otherwise I
   would forget.  It happens to be in an isolated file that my
   current topic does not need to modify (say, I was looking at
   a function in that file that my new feature needs to call and
   I wanted to study its calling convention. And I found a typo in
   the comment near the function).

 * The fix does not belong to the current topic, but can go to
   the 'master' branch straight.  It's a fix in the comment that
   cannot possibly break things, and I can/will test it later
   anyway.

 * So with the existing set of tools, I would go there, commit
   and then come back:

	$ git checkout [-m] master
        $ git commit -m 'fix typo in that-file' that-file
        $ git checkout [-m] topic

   But it might be faster to say:

   	$ git commit -b master -m 'fix typo in that-file' that-file

   to make a commit on the other branch and come back
   immediately afterwards.

 * In the same situation, when the 'master' is closed for some
   administrative reason (e.g. "deep freeze before a release and
   strict bugfixes and nothing else are allowed"), I would create
   a new 'typofix' branch and do the same.  I can rebase it
   later on 'master' when it reopens.

	$ git commit -b typofix -m 'fix typo in that-file' that-file

	... much later when master reopens ...
        $ git rebase --onto master topic typofix

It's just a possible typesaver, but I am likely not using it
myself (my fingers are already trained to do the three command
sequence dance).

I do agree that it adds one more way to do the same thing and
would make the documentation noisier, potentially adding more to
the confusion.  So let's not go there.

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 23:46, Junio C Hamano wrote:

> > There truly is something wrong with me.
>
> I did not mean it that way.  I only took it as a sign that maybe

Don't worry; I've got thicker skin than that.  I was simply amazed at my lack 
of comprehension ability. :-)

> > I'm not sure about your "commit -b"; is it wise to have /another/ way of
> > making a branch?  I mean - I'm clearly confused enough, have a heart :-)
>
> I said "commit -b <newbranch>" and deliberately avoided saying
> "commit -b <anybranch>", because I did not want to open another
> can of worms while we are discussing so many good things
> already, and my head can hold only a handful topics at once.

Absolutely.  I'd agree that only <newbranch> is worth even considering.

>  * While working on it, I find an obvious bug that I would not
>    want to fix on the branch (the topic branch I am currently on
>    is not about fixing that bug).

I find myself swayed by this.  This is indeed something that happens to me a 
lot.  In certain circumstances I've been defeated by git because I couldn't 
switch to the other branch to make that quick commit because my local changes 
conflicted with that other branch.  The solution I use is to commit the bug 
fix in the wrong branch, finish my current on-topic commit then 
rebase/reset/etc to put everything where it should be.

> I do agree that it adds one more way to do the same thing and
> would make the documentation noisier, potentially adding more to
> the confusion.  So let's not go there.

Yep.  Although you've persuaded me with the above example, I think this is the 
correct path.  It's not wise to add every bell and whistle just because we 
can.  As long as there is /a/ way to achieve every task, that's good enough, 
we don't need every way to achieve every task.  We might even argue that 
git's flexibility is what makes it harder to learn.  It's similar to UNIX in 
that respect - hard to learn, easy to use.


Andy

-- 
Dr Andy Parkins, M Eng (hons), MIEE

RE: What's in git.git (stable)

[Raimund Bauer]

> Yep.  Although you've persuaded me with the above example, I 
> think this is the 
> correct path.  It's not wise to add every bell and whistle 
> just because we 
> can.  As long as there is /a/ way to achieve every task, 
> that's good enough, 
> we don't need every way to achieve every task.  We might even 
> argue that 
> git's flexibility is what makes it harder to learn.  It's 
> similar to UNIX in 
> that respect - hard to learn, easy to use.

So we prefer to tell users "You can do what you want with these 3 commands,
since we don't want to confuse use with another option to do it with just
1"?

> Andy

-- 
best regards

  Ray

Re: What's in git.git (stable)

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> On Thursday 2006 December 14 23:46, Junio C Hamano wrote:
> ...
>> I said "commit -b <newbranch>" and deliberately avoided saying
>> "commit -b <anybranch>", because I did not want to open another
>> can of worms while we are discussing so many good things
>> already, and my head can hold only a handful topics at once.
>
> Absolutely.  I'd agree that only <newbranch> is worth even considering.

Just for the record, I do not necessarily agree.  Committing a
small and obvious change out of context to an existing branch
makes just as much sense.

After all, with the example workflow in my message you responded
to, after running the "commit -b typofix" (which creates a new
branch) to record the first typo fix, I am sure that I would
want to record the second typofix I would find while on my topic
to go to the same typofix branch I previously created.

The 'can of worms' is that switching to an existing branch could
fail with conflicts.  Although "git checkout -m" can help
sometimes, that is not something we would want to do in the
middle of doing something else on a topic.  That's why I do not
think "commit -b <anybranch>" is a good idea.

Allowing the form for only a new branch makes an inconsistency
that is hard to explain to new people, and that is why I am not
in favor of having "commit -b <newbranch>" either.

Re: What's in git.git (stable)

[Carl Worth]

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

> The 'can of worms' is that switching to an existing branch could
> fail with conflicts.

One fix for this would be the idea I've proposed to have a new flag
for "git checkout" to 'stash' the dirty state in the current branch
before switching.

Then, there wouldn't be a problem to implement "commit -b <anybranch>"
on top of the stashing checkout.

I think the only real problem with the idea of having dirty changes
stashed in a branch is that git already allows dirty changes to be
carried while switching to a branch, (with or without -m). And doing
both of those at once would lead to an ugly new conflict situation,
(where _neither_ of the conflicted states exist as exposed tree
objects). Even if there were no conflict, it would mingle two
different sets of local modifications, and that could be unkind as it
might be hard for the user to separate them if they didn't want them
mingled.

If someone were to pursue this idea, I think it would be reasonable to
just make that case an error, "Cannot carry local modifications when
checking out a branch with stashed modifications." That message could
even suggest the user use the stash option to leave the local
modifications behind when doing the checkout.

-Carl

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

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Andy Parkins wrote:

> On Thursday 2006, December 14 21:22, Junio C Hamano wrote:
> 
> > This is interesting.  You said "commit -b", were pointed out
> > that you were talking about "checkout -b", and just after saying
> > "yup, that is right, I was", you again say "commit -b".
> 
> There truly is something wrong with me.  Is there some sort of record 
> for number of mistakes made in one thread?  Have I won yet?

Honestly, I do not see anything you have done wrong. After all, a good 
idea came from it.

> I'm not sure about your "commit -b"; is it wise to have /another/ way of 
> making a branch?  I mean - I'm clearly confused enough, have a heart :-)

I actually would _love_ that feature. Yeah, it's possible with existing 
git commands, but it would be _convenient_.

Ciao,
Dscho

Re: What's in git.git (stable)

[Horst H. von Brand]

Junio C Hamano <junkio@cox.net> wrote:

[...]

> In general the principle ought to be not to say anything if the
> command does exactly what it was told to do successfully, unless
> the operation is expected to take longer than other normal
> commands in the git suite, or something that is rarely used.

Nodz. Just hoary Unix tradition.

> Perhaps under "[user] expert" control.

Nope. You'd be surprised what kind of people consider themselves
"experts"... I'd prefer adding -v/--verbose flags to all commands (if
nothing else, for symmetry's sake), have a '[default] --verbose' controlling
this across the board (perhaps also '[default "command"] --verbose'), with
'[default]' setting default switches.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Re: What's in git.git (stable)

[Jakub Narebski]

Horst H. von Brand wrote:

>> Perhaps under "[user] expert" control.
> 
> Nope. You'd be surprised what kind of people consider themselves
> "experts"... I'd prefer adding -v/--verbose flags to all commands (if
> nothing else, for symmetry's sake), have a '[default] --verbose' controlling
> this across the board (perhaps also '[default "command"] --verbose'), with
> '[default]' setting default switches.

Nice idea... but configuration variables have to have name.
So it would be 

  $ git repo-config defaults.command --verbose

resulting in

  [defaults]
        command = --verbose
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Wed, 13 Dec 2006, Andy Parkins wrote:

> On Wednesday 2006, December 13 21:35, Junio C Hamano wrote:
>
>  * git-revert should be called git-invert.  It doesn't remove a change
>    from history, it simply applies another commit that does the
>    opposite of whatever commit you are "revert"ing.  That's an inversion.

No. An inversion is the _opposite_. Not an undo.

Besides, The fact that revert _adds_ to history is a nice way to 
document that you reverted that change. And you can even explain in the 
commit message, why you did it.

>  * git-fetch output is confusing:
>     remote: Generating pack...
>     remote: Done counting 189146 objects.
>     remote: Result has 186566 objects.
>     remote: Deltifying 186566 objects.
>     remote:  100% (186566/186566) done
>     Unpacking 186566 objects
>     24% (44792/186566) done
>    Some questions from the point of view of a newbie: what is a pack?  what is 
>    an object? Why is the remote counting them?  Which remote am I reading 
>    from?  What am I fetching?  What is "Deltifying"?  How much data do I have 
>    to download (number of objects doesn't tell me).  How long has this taken?  
>    How long is left to go?

IMHO it is better for a newbie to see that _something_ is happening. A 
newbie cannot, and does not want to, understand exactly what is going on.

So, think of it as our response to Windows' non-progress-bar: when you 
start up Windows, there is a progress-bar, except that it does not show 
progress, but a Knight Rider like movement, only indicating that it does 
something.

Ciao,
Dscho

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 00:22, Johannes Schindelin wrote:

> >  * git-revert should be called git-invert.  It doesn't remove a change
> >    from history, it simply applies another commit that does the
> >    opposite of whatever commit you are "revert"ing.  That's an inversion.
>
> No. An inversion is the _opposite_. Not an undo.

That's what I'm saying, we are applying the opposite of the given commit - 
that commit is being inverted and applied again.  It most certainly isn't an 
undo, because the original commit still exists.  It's not a reversion 
because "reversion" is to regress to a previous time or state.  In that sense 
git-revert is not doing what it says on the tin.  A revert would be to remove 
all the revisions from now until the specified commit - i.e. what git-reset 
now does.

(Note: I don't think git-reset should be renamed, as it's possible to use 
git-reset to move a branch forward as well as backward).

> Besides, The fact that revert _adds_ to history is a nice way to
> document that you reverted that change. And you can even explain in the
> commit message, why you did it.

I'm not disputing that the /operation/ is useful, I'm arguing that it is 
incorrectly named.

> IMHO it is better for a newbie to see that _something_ is happening. A

I'm not arguing that we should show nothing; I'm arguing that the something we 
do show should be more clear than what is now shown.  The choice is 
therefore "show something confusing" or "show something clear".

> newbie cannot, and does not want to, understand exactly what is going on.

"newbie" doesn't mean "idiot".  Everybody wants to understand what is going 
on.

> So, think of it as our response to Windows' non-progress-bar: when you
> start up Windows, there is a progress-bar, except that it does not show
> progress, but a Knight Rider like movement, only indicating that it does
> something.

Given the choice between nothing and a non-progress "doing something" bar, I 
would of course pick the "doing something" bar.  However, given the choice 
between a "doing something" bar and a progress bar, I'd rather have the 
progress bar.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Andy Parkins wrote:

> On Thursday 2006 December 14 00:22, Johannes Schindelin wrote:
> 
> > >  * git-revert should be called git-invert.  It doesn't remove a change
> > >    from history, it simply applies another commit that does the
> > >    opposite of whatever commit you are "revert"ing.  That's an inversion.
> >
> > No. An inversion is the _opposite_. Not an undo.
> 
> That's what I'm saying, we are applying the opposite of the given commit 
> - that commit is being inverted and applied again.

Ahh! I get what you are thinking. I was talking about reverting a change 
from the _content's viewpoint_. I _never_ want to revert history (I am no 
politician, you know?)

> > newbie cannot, and does not want to, understand exactly what is going 
> > on.
> 
> "newbie" doesn't mean "idiot".  Everybody wants to understand what is 
> going on.

I heartly disagree. I saw so many faces _begging_ me to just say _what_ to 
do, not _why_, and quickly, please.

> > So, think of it as our response to Windows' non-progress-bar: when you 
> > start up Windows, there is a progress-bar, except that it does not 
> > show progress, but a Knight Rider like movement, only indicating that 
> > it does something.
> 
> Given the choice between nothing and a non-progress "doing something" 
> bar, I would of course pick the "doing something" bar.  However, given 
> the choice between a "doing something" bar and a progress bar, I'd 
> rather have the progress bar.

If I have the choice between a "doing something" bar and a Windows 
Explorer "14 seconds left" bar showing the same message for two minutes, 
I'd rather have a Mars bar ;-)

Ciao,
Dscho

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 10:51, Johannes Schindelin wrote:

> If I have the choice between a "doing something" bar and a Windows
> Explorer "14 seconds left" bar showing the same message for two minutes,
> I'd rather have a Mars bar ;-)

Gahhhhhhhhh!  Oh how I hate that window.

On this we can wholeheartedly agree.  Unfortunately it's not just windows; 
most applications that have a progress bar go like this:

0%, ..., 0%,..., 0%,.., 1 , 2, 3, 4, 5, 6, 33%, ..., 33%, ..., 33%, 35, 36, 
85%, ..., 85%, ..., 85%, ..., 99%, 100%, ..., 100%, ... (yes, I'm completely 
finished, but still working), ... 100%.

I reckon, unless the window with a progress bar in it has an ETA, then the 
progress should be an ETA itself.  If it's not going to monotonically 
increase, then the "percentage" is meaningless.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Andy Parkins wrote:

> On Thursday 2006 December 14 10:51, Johannes Schindelin wrote:
> 
> > If I have the choice between a "doing something" bar and a Windows
> > Explorer "14 seconds left" bar showing the same message for two minutes,
> > I'd rather have a Mars bar ;-)
> 
> Gahhhhhhhhh!  Oh how I hate that window.
> 
> On this we can wholeheartedly agree.  Unfortunately it's not just windows; 
> most applications that have a progress bar go like this:
> 
> 0%, ..., 0%,..., 0%,.., 1 , 2, 3, 4, 5, 6, 33%, ..., 33%, ..., 33%, 35, 36, 
> 85%, ..., 85%, ..., 85%, ..., 99%, 100%, ..., 100%, ... (yes, I'm completely 
> finished, but still working), ... 100%.
> 
> I reckon, unless the window with a progress bar in it has an ETA, then the 
> progress should be an ETA itself.  If it's not going to monotonically 
> increase, then the "percentage" is meaningless.

And now you know one of the reasons we have no true progress bar.

Another reason is that it would be relatively expensive to calculate, 
since the total _size_ is not known beforehand (remember, the pack is 
calculated on the fly).

Yet another reason is that all estimates there are unstable by nature: the 
load of the server, the net load, the load of the client, the speed of 
packing and unpacking, and the luck if deltas can be reused, are all 
contributors to this unstability.

Ciao,
Dscho

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 11:27, Johannes Schindelin wrote:

> And now you know one of the reasons we have no true progress bar.
>
> Another reason is that it would be relatively expensive to calculate,
> since the total _size_ is not known beforehand (remember, the pack is
> calculated on the fly).

Hmmm; just thinking out loud now... I used to calculate ETA's for simulations 
I ran that had similar problems - i.e. you don't know how long it takes until 
its done (it was with genetic programming function trees, and of course you 
don't know what operations will be in the next generations tree, so you can't 
estimate a time).  I just showed "something" by doing a standard: how long 
did n/N take therefore N will take... then I plotted the error in the ETA 
after the simulation completed.  Interestingly it was always a -exp(-x) 
shape.  In other words it got more accurate towards the end (of course); 
which is exactly the sort of accuracy you would want.  At the beginning you 
just want a broad "this will take a few hours" measure.  Towards the end, you 
want to know "there is 1m50s remaining".

I wonder if the number of objects is a reasonable measure of progress.  Let's 
say we're transferring 100,000 objects.  Let's also say that the average size 
of objects is 100 bytes.  Let's finally say that the object sizes are evenly 
distributed throughout the 100,000 objects.  This would mean that the first 
1,000 objects are just as representative as the last 1,000 objects; or any 
other randomly chosen 1,000 objects.  In which case, the size of the first 
thousand objects would be approximately one hundredth the size of the total 
transfer.  Volia: an estimate of the total size of the transfer.

Obviously this estimate would be continuously updated, and would become more 
accurate as more objects are transferred.  The data rate would of course be 
based on only the previous X objects rather than the total transferred to 
take account of changing server conditions.  From these ETA could be 
estimated.

Obviously the ETA is unstable, but it's only for giving users an idea of how 
long is left; not for strict accounting.




Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Shawn Pearce]

Andy Parkins <andyparkins@gmail.com> wrote:
> I wonder if the number of objects is a reasonable measure of progress.  Let's 
> say we're transferring 100,000 objects.  Let's also say that the average size 
> of objects is 100 bytes.  Let's finally say that the object sizes are evenly 
> distributed throughout the 100,000 objects.  This would mean that the first 
> 1,000 objects are just as representative as the last 1,000 objects; or any 
> other randomly chosen 1,000 objects.  In which case, the size of the first 
> thousand objects would be approximately one hundredth the size of the total 
> transfer.  Volia: an estimate of the total size of the transfer.

Ah, but much like those stock scam emails, "prior performance does
not predict future results"...  The size of objects in the pack
tends to be small up front (commits/trees) and larger in the back
(blobs).  The size distribution probably also gets more erratic
near the back as the blob sizes may not follow a nice distribution.

E.g. I have a repository with a blob that is 23 MiB.  But I also
have some 5 MiB blobs, and then a very large number of relatively
small blobs.  That 23 MiB blob really gums up any estimate.

But as you state, its easy to refine it over time, and the closer we
get to the end the more likely it is to be correct.  Unless its that
23 MiB blob.  As it takes up about 85% of that repository's pack.

-- 

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006 December 14 12:10, Shawn Pearce wrote:

> not predict future results"...  The size of objects in the pack
> tends to be small up front (commits/trees) and larger in the back
> (blobs).  The size distribution probably also gets more erratic
> near the back as the blob sizes may not follow a nice distribution.

Oh well; that pretty much settles it then.

> But as you state, its easy to refine it over time, and the closer we
> get to the end the more likely it is to be correct.  Unless its that
> 23 MiB blob.  As it takes up about 85% of that repository's pack.

I had imagined (foolishly), that most objects would be diffs, and would be 
similarly sized.

Scratch that.

Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: What's in git.git (stable)

[Horst H. von Brand]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> On Thu, 14 Dec 2006, Andy Parkins wrote:

[...]

> > "newbie" doesn't mean "idiot".  Everybody wants to understand what is 
> > going on.

> I heartly disagree. I saw so many faces _begging_ me to just say _what_ to 
> do, not _why_, and quickly, please.

So? This is meant to be a /tool/. Not wanting to know how it works doesn't
make one an idiot, it is just economy.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Thu, 14 Dec 2006, Horst H. von Brand wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> > On Thu, 14 Dec 2006, Andy Parkins wrote:
> 
> [...]
> 
> > > "newbie" doesn't mean "idiot".  Everybody wants to understand what is 
> > > going on.
> 
> > I heartly disagree. I saw so many faces _begging_ me to just say _what_ to 
> > do, not _why_, and quickly, please.
> 
> So? This is meant to be a /tool/. Not wanting to know how it works doesn't
> make one an idiot, it is just economy.

My thoughts exactly.

And I did not want to force understanding onto the users. Heck, I even 
know people who use git and do not know about the index! They don't need 
to, either.

Ciao,
Dscho

Re: What's in git.git (stable)

[Nicolas Pitre]

On Thu, 14 Dec 2006, Andy Parkins wrote:

> > Besides, The fact that revert _adds_ to history is a nice way to
> > document that you reverted that change. And you can even explain in the
> > commit message, why you did it.
> 
> I'm not disputing that the /operation/ is useful, I'm arguing that it is 
> incorrectly named.

Well, people are used to say they've "reverted" a change.  Although the 
command might appear slightly misnamed wrt its operation, it still does 
what most people are expecting from such a name.

Re: What's in git.git (stable)

[Andy Parkins]

On Thursday 2006, December 14 17:23, Nicolas Pitre wrote:

> Well, people are used to say they've "reverted" a change.  Although the
> command might appear slightly misnamed wrt its operation, it still does
> what most people are expecting from such a name.

Actually , not only is git-revert misnamed, it doesn't match up with most 
other SCMs.

"svn revert" is git-reset.
"bzr revert" is git-reset.
"darcs revert" is git-reset.
"hg revert" is git-reset.
"svk revert" is git-reset.
"monotone revert" is git-reset.

Most people must surely be expecting it to do what it does in every other SCM; 
as it doesn't my argument is that we should just drop the name "revert" and 
call it git-invert instead, which is more accurately named and doesn't 
conflict with the standard meaning.


Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: What's in git.git (stable)

[Shawn Pearce]

Andy Parkins <andyparkins@gmail.com> wrote:
>  * git-show-branch output is cryptic.

Agreed.  I still don't know how to read its output.  So I just
don't use it.  Ever.  :-)

-- 

Re: What's in git.git (stable)

[Jakub Narebski]

Shawn Pearce wrote:

> Andy Parkins <andyparkins@gmail.com> wrote:
>>  * git-show-branch output is cryptic.
> 
> Agreed.  I still don't know how to read its output.  So I just
> don't use it.  Ever.  :-)

And the way it uses it's options is even more cryptic, and differs from
other similar commands. So I'd rather use qgit (or gitk, if gitk would
correct the error with remembering wrong window size).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Shawn Pearce wrote:
>
>> Andy Parkins <andyparkins@gmail.com> wrote:
>>>  * git-show-branch output is cryptic.
>> 
>> Agreed.  I still don't know how to read its output.  So I just
>> don't use it.  Ever.  :-)
>
> And the way it uses it's options is even more cryptic, and differs from
> other similar commands.

(Jakub, please do not drop people from cc: list; you were asked
more than once).

Ok, so what's the action you guys are proposing?

 (1) show-branch output is cryptic and it does not do anything
     useful.  Drop it.

 (2) show-branch output is cryptic and I do not understand what
     it is trying to do.  Document it better.

 (3) While I agree what show-branch is trying to do is useful,
     its output is useless.  Instead of showing an example
     situation like this:

	[ picture here ]

     It should show the same situation like this:

	[ improved picture here ]

 (4) None of the above.

The same question goes for its input branch specification.

Personally, I find its input branch globbing very handy, and
often wish that 'git branch' had a '--list' option that lists
branches that match the glob pattern given on the command line,
not just listing everything when no parameter is given.

Re: What's in git.git (stable)

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> Shawn Pearce wrote:
>>
>>> Andy Parkins <andyparkins@gmail.com> wrote:
>>>>  * git-show-branch output is cryptic.
>>> 
>>> Agreed.  I still don't know how to read its output.  So I just
>>> don't use it.  Ever.  :-)
>>
>> And the way it uses it's options is even more cryptic, and differs from
>> other similar commands.
> 
> (Jakub, please do not drop people from cc: list; you were asked
> more than once).

The problem is that I'm not subscribed to git mailing list; I usually
read it via GMane news<->mail interface, at
  nntp://news.gmane.org/gmane.comp.version-control.git
First, in this interface I have only the last author and not the full
Cc: list. Second, when I reply _both_ via email (adding authors if
necessary) and to news, people receiving my reply don't have (I guess)
git@vger.kernel.org in Cc: list, so sometimes the discussion drops off
the list. Third, if I add git mailing list address when replying via
mail, vger server blocks email from gmane stating

  Technical details of permanent failure:
  PERM_FAILURE: SMTP Error (state 9): 501 5.1.3 Path data: Had characters unsuitable for an rfc821-string

When email is sent _directly_ to me (i.e. I'm on Cc: list) I try
to preserve Cc: list.

> Ok, so what's the action you guys are proposing?
> 
>  (1) show-branch input is cryptic and it does not do anything
>      useful.  Drop it.
> 
>  (2) show-branch input is cryptic and I do not understand what
>      it is trying to do.  Document it better.
[...]

I'm just used to the way revisions are specified to other history
viewers: git-log (via git-rev-list), gitk, qgit. git-show-branch
is a bit odd man out here. "git-show-branch ref1 ref2 ref3"
is (without --more=n) like 

  git rev-list ref1 ref2 ref3 --not $(git merge-base ref1 ref2 ref3)

Which is handy for git-show-branch, but odd. Perhaps we should add
--xor option to git rev list for the above, i.e.

  git rev-list A...B        == 
    == git rev-list A B --not $(git merge-base A B)
  git rev-list --xor A B C  ==
    == git rev-list A B C --not $(git merge-base A B C)   
 
> Personally, I find its input branch globbing very handy, and
> often wish that 'git branch' had a '--list' option that lists
> branches that match the glob pattern given on the command line,
> not just listing everything when no parameter is given.
 
It is odd (git branch not having --list with globbing) also because
'git tag' has globbing support.

-- 
Jakub Narebski

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Fri, 15 Dec 2006, Jakub Narebski wrote:

> Junio C Hamano wrote:
>
> > (Jakub, please do not drop people from cc: list; you were asked
> > more than once).
> 
> The problem is that I'm not subscribed to git mailing list;

So subscribe. I am sure I lost quite some of your responses to my emails, 
_just_ because you happen to kill me from the Cc: list.

IOW if you expect answers, _please_ adher to net standards.

Ciao,
Dscho

Re: What's in git.git (stable)

[Junio C Hamano]

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

> On Fri, 15 Dec 2006, Jakub Narebski wrote:
>
>> Junio C Hamano wrote:
>>
>> > (Jakub, please do not drop people from cc: list; you were asked
>> > more than once).
>> 
>> The problem is that I'm not subscribed to git mailing list;
>
> So subscribe. I am sure I lost quite some of your responses to my emails, 
> _just_ because you happen to kill me from the Cc: list.
>
> IOW if you expect answers, _please_ adher to net standards.

FWIW, I also read the list traffic through gmane news gateway.

I am subscribed and my mail filter drops the mails from the list
into a dedicated mailbox, but that is purely for my own backup
and I usually do not look at it otherwise.

Re: What's in git.git (stable)

[Johannes Schindelin]

Hi,

On Fri, 15 Dec 2006, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > On Fri, 15 Dec 2006, Jakub Narebski wrote:
> >
> >> Junio C Hamano wrote:
> >>
> >> > (Jakub, please do not drop people from cc: list; you were asked
> >> > more than once).
> >> 
> >> The problem is that I'm not subscribed to git mailing list;
> >
> > So subscribe. I am sure I lost quite some of your responses to my emails, 
> > _just_ because you happen to kill me from the Cc: list.
> >
> > IOW if you expect answers, _please_ adher to net standards.
> 
> FWIW, I also read the list traffic through gmane news gateway.

So, how do you tackle the problem Jakub evidently has, namely to reply to 
all the people who your reply refers to?

Ciao,
Dscho

Re: What's in git.git (stable)

[Junio C Hamano]

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

>> FWIW, I also read the list traffic through gmane news gateway.
>
> So, how do you tackle the problem Jakub evidently has, namely to reply to 
> all the people who your reply refers to?

I do not "tackle".

I just tell Gnus to follow-up, which does not always do the
right thing [*1*], and I just try to be careful and fix up To:
and Cc: fields by hand as necessary.  The time spent on that on
my part is _worth_ spending than inconveniencing others.

It's just a common courtesy, not "tackling".


[Footnote]

*1* ... most likely because I haven't configured it to do the
right thing, and/or the sender or the gateway puts a wrong
Reply-To: or Mail-Followup-To: header and it ends up honoring
them.

Re: What's in git.git (stable)

[Steven Grimm]

Junio C Hamano wrote:
> It's just a common courtesy, not "tackling".
>   

Interesting. I'd actually prefer people *remove* me from the CC list -- 
I find it annoying to get two copies of every message in threads I reply 
to. I'm already subscribed to the mailing list, so there's no point 
having me on the Cc line too. (Mind you, as annoyances go it's a pretty 
insignificant one.)

I can understand the case of people who aren't on the list wanting to 
get replies, but why does someone who *is* on the list want to be CCed? 
Is it just that there's no good way to tell in advance which category a 
given person falls into, so best to be on the safe side?

Re: What's in git.git (stable)

[Junio C Hamano]

Steven Grimm <koreth@midwinter.com> writes:

> Interesting. I'd actually prefer people *remove* me from the CC list -- 
> I find it annoying to get two copies of every message in threads I
> reply to. I'm already subscribed to the mailing list, so there's no
> point having me on the Cc line too. (Mind you, as annoyances go it's a
> pretty insignificant one.)
>
> I can understand the case of people who aren't on the list wanting to
> get replies, but why does someone who *is* on the list want to be
> CCed? Is it just that there's no good way to tell in advance which
> category a given person falls into, so best to be on the safe side?

There is no cheap and mechanical way to tell that for the
sender, and even when the sender can tell, it is not polite to
do so (see next paragraph), unless the recipient specifically
ask for it.  On the other hand, filtering duplicates at the
recipient's end could be mechanically done without wasting the
human time.  And people's time tend to be a lot more expensive
than machine time and the cost to send extra bits over the wire.

Some people (including me) prioritize e-mails and respond to
messages that are addressed To: them first, then Cc: next, and
finally the rest of the messages that came only through the
mailng list.  Dropping a recipient from the Cc: list, even when
the sender knows that recipient is on the list, breaks this.

People can safely remove *themselves* from the CC: list when the
mailing list they subscribe to are on the CC: list as well.
This would interact with the prioritizing I mentioned above, but
that is done as a choice by them as the recipient of the
replies, so there is no problem in doing so.

Re: What's in git.git (stable)

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> I'm just used to the way revisions are specified to other history
> viewers: git-log (via git-rev-list), gitk, qgit. git-show-branch
> is a bit odd man out here. "git-show-branch ref1 ref2 ref3"
> is (without --more=n) like 
>
>   git rev-list ref1 ref2 ref3 --not $(git merge-base ref1 ref2 ref3)
>
> Which is handy for git-show-branch, but odd.

I hate to sound harsh, but...

Then you do not understand show-branch at all.  Not having to
say the "--not merge-base" part is NOT about being handy, but is
the central part of what show-branch does.  The command is about
showing the commits that are on only some of the branches but
not on others.

Other commands you listed above are all based on rev-list logic
of painting commits in two colors (either UNINTERESTING or
~UNINTERESTING) and being able to combine the set using "A..B",
"^A B", and "A B --not C" notations all make sense.  All
combinations work as set operation -- start from union of
commits reachable from positive (i.e. not prefixed with ^) refs,
and subtract set of commits reachable from any negative ref.

What show-branch does cannot be expressed with that two-color
logic; it needs to use N colors for N input refs.  After digging
from the tips deep enough, you would find the common merge-base
and after that point it is not interesting to show anything
anymore, and that is how it stops output.

[PATCH] git-clone: use wildcard specification for tracking branches

[Junio C Hamano]

This stops enumerating the set of branches found on the remote
side when a clone was made in the configuration file.  Instead,
a single entry that maps each remote branch to the local
tracking branch for the remote under the same name is created.

Doing it this way not only shortens the configuration file, but
automatically adjusts to a new branch added on the remote side
after the clone is made.

Unfortunately this cannot be done for the traditional layout,
where we always need to special case the 'master' to 'origin'
mapping within the local branch namespace.  But that is Ok; it
will be going away before v1.5.0.

We could also lose the "primary branch" mapping at the
beginning, but that has to wait until we implement the "forbid
'git pull' when we do not have branch.$current.merge for the
current branch" policy we earlier discussed.  That should also
be in v1.5.0

Signed-off-by: Junio C Hamano <junkio@cox.net>

---
Junio C Hamano <junkio@cox.net> writes:

> Things that need to be done to complete what have been merged to
> 'master' are:
> ...
>  - 'git-clone' probably should be updated to use wild-card in
>    remote.origin.fetch, instead of listing all the branches it
>    found when the clone was made.

 git-clone.sh |   47 ++++++++++++++++++++++++++++++-----------------
 1 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/git-clone.sh b/git-clone.sh
index 1f5d07a..422499a 100755
--- a/git-clone.sh
+++ b/git-clone.sh
@@ -366,41 +366,54 @@ then
 		)
 	)
 
-	# Write out remotes/$origin file, and update our "$head_points_at".
+	# Write out remote.$origin config, and update our "$head_points_at".
 	case "$head_points_at" in
 	?*)
-		mkdir -p "$GIT_DIR/remotes" &&
+		# Local default branch
 		git-symbolic-ref HEAD "refs/heads/$head_points_at" &&
+
+		# Tracking branch for the primary branch at the remote.
 		case "$use_separate_remote" in
 		t)	origin_track="$remote_top/$head_points_at"
 			git-update-ref HEAD "$head_sha1" ;;
 		*)	origin_track="$remote_top/$origin"
 			git-update-ref "refs/heads/$origin" "$head_sha1" ;;
 		esac &&
+
+		# Upstream URL and the primary branch tracking
 		git-repo-config remote."$origin".url "$repo" &&
 		git-repo-config remote."$origin".fetch \
 			"refs/heads/$head_points_at:$origin_track" &&
-		(cd "$GIT_DIR/$remote_top" && find . -type f -print) |
-		while read dotslref
-		do
-			name=`expr "$dotslref" : './\(.*\)'`
-			if test "z$head_points_at" = "z$name"
-			then
-				continue
-			fi
-			if test "$use_separate_remote" = '' &&
-			   test "z$origin" = "z$name"
-			then
-				continue
-			fi
-			git-repo-config remote."$origin".fetch "refs/heads/${name}:$remote_top/${name}" '^$'
-		done &&
+
+		# Set up the mappings to track the remaining branches.
+		case "$use_separate_remote" in
+		t)
+			git-repo-config remote."$origin".fetch \
+				"refs/heads/*:$remote_top/*" '^$'
+			;;
+		*)
+			(cd "$GIT_DIR/$remote_top" && find . -type f -print) |
+			while read dotslref
+			do
+				name=`expr "$dotslref" : './\(.*\)'`
+				if test "z$head_points_at" = "z$name" ||
+					test "z$origin" = "z$name"
+				then
+					continue
+				fi
+				git-repo-config remote."$origin".fetch \
+				"refs/heads/${name}:$remote_top/${name}" '^$'
+			done
+			;;
+		esac &&
+
 		case "$use_separate_remote" in
 		t)
 			rm -f "refs/remotes/$origin/HEAD"
 			git-symbolic-ref "refs/remotes/$origin/HEAD" \
 				"refs/remotes/$origin/$head_points_at"
 		esac &&
+
 		git-repo-config branch."$head_points_at".remote "$origin" &&
 		git-repo-config branch."$head_points_at".merge "refs/heads/$head_points_at"
 	esac

[PATCH] git-pull: refuse default merge without branch.*.merge

[Junio C Hamano]

Everybody hated the pull behaviour of merging the first branch
listed on remotes/* file (or remote.*.fetch config) into the
current branch.  This finally corrects that UI wart by
forbidding "git pull" without an explicit branch name on the
command line or branch.$current.merge for the current branch.

The matching change to git-clone was made to prepare the default
branch.*.merge entry for the primary branch some time ago.

Signed-off-by: Junio C Hamano <junkio@cox.net>

---
Junio C Hamano <junkio@cox.net> writes:

> We could also lose the "primary branch" mapping at the
> beginning, but that has to wait until we implement the "forbid
> 'git pull' when we do not have branch.$current.merge for the
> current branch" policy we earlier discussed.  That should also
> be in v1.5.0

  And this does exactly that.

 git-parse-remote.sh |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/git-parse-remote.sh b/git-parse-remote.sh
index 6ae534b..7cd79c2 100755
--- a/git-parse-remote.sh
+++ b/git-parse-remote.sh
@@ -144,7 +144,8 @@ canon_refs_list_for_fetch () {
 			curr_branch=$(git-symbolic-ref HEAD | \
 			    sed -e 's|^refs/heads/||')
 			merge_branches=$(git-repo-config \
-			    --get-all "branch.${curr_branch}.merge")
+			    --get-all "branch.${curr_branch}.merge") ||
+			merge_branches=.this.would.never.match.any.ref.
 		fi
 		set x $(expand_refs_wildcard "$@")
 		shift

[PATCH] git-clone: lose the artificial "first" fetch refspec

[Junio C Hamano]

Now we lost the "first refspec is the one that is merged by default"
rule, there is no reason for clone to list the remote primary branch
in the config file explicitly anymore.

We still need it for the traditional layout for other reasons,
though.

Signed-off-by: Junio C Hamano <junkio@cox.net>

---
> Junio C Hamano <junkio@cox.net> writes:
>
>> We could also lose the "primary branch" mapping at the
>> beginning, but that has to wait until we implement the "forbid
>> 'git pull' when we do not have branch.$current.merge for the
>> current branch" policy we earlier discussed.  That should also
>> be in v1.5.0
>
>   And this does exactly that.

 Next step will be to remove the traditional layout altogether.
 With the recent flurry of UI updates, I think it is sane to do
 that before v1.5.0; opinions?

 git-clone.sh |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/git-clone.sh b/git-clone.sh
index 422499a..68dc4f2 100755
--- a/git-clone.sh
+++ b/git-clone.sh
@@ -380,18 +380,18 @@ then
 			git-update-ref "refs/heads/$origin" "$head_sha1" ;;
 		esac &&
 
-		# Upstream URL and the primary branch tracking
+		# Upstream URL
 		git-repo-config remote."$origin".url "$repo" &&
-		git-repo-config remote."$origin".fetch \
-			"refs/heads/$head_points_at:$origin_track" &&
 
-		# Set up the mappings to track the remaining branches.
+		# Set up the mappings to track the remote branches.
 		case "$use_separate_remote" in
 		t)
 			git-repo-config remote."$origin".fetch \
 				"refs/heads/*:$remote_top/*" '^$'
 			;;
 		*)
+			git-repo-config remote."$origin".fetch \
+				"refs/heads/$head_points_at:$origin_track" &&
 			(cd "$GIT_DIR/$remote_top" && find . -type f -print) |
 			while read dotslref
 			do

[PATCH] git-clone: lose the traditional 'no-separate-remote' layout

[Junio C Hamano]

Finally.

The separate-remote layout is so much more organized than
traditional and easier to work with especially when you need to
deal with remote repositories with multiple branches and/or you
need to deal with more than one remote repositories, and using
traditional layout for new repositories simply does not make
much sense.

Internally we still have code for 1:1 mappings to create a bare
clone; that is a good thing and will not go away.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Junio C Hamano <junkio@cox.net> writes:

>  Next step will be to remove the traditional layout altogether.
>  With the recent flurry of UI updates, I think it is sane to do
>  that before v1.5.0; opinions?

 And this drops it; modulo bugs, I think this is about it for
 v1.5.0 around this area.

 Documentation/git-clone.txt |   15 +----------
 git-clone.sh                |   58 +++++++++----------------------------------
 2 files changed, 13 insertions(+), 60 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index bfddb21..874934a 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -11,8 +11,7 @@ SYNOPSIS
 [verse]
 'git-clone' [--template=<template_directory>] [-l [-s]] [-q] [-n] [--bare]
 	  [-o <name>] [-u <upload-pack>] [--reference <repository>]
-	  [--use-separate-remote | --no-separate-remote] <repository>
-	  [<directory>]
+	  <repository> [<directory>]
 
 DESCRIPTION
 -----------
@@ -99,18 +98,6 @@ OPTIONS
 	if unset the templates are taken from the installation
 	defined default, typically `/usr/share/git-core/templates`.
 
---use-separate-remote::
-	Save remotes heads under `$GIT_DIR/refs/remotes/origin/` instead
-	of `$GIT_DIR/refs/heads/`.  Only the local master branch is
-	saved in the latter. This is the default.
-
---no-separate-remote::
-	Save remotes heads in the same namespace as the local
-	heads, `$GIT_DIR/refs/heads/'.  In regular repositories,
-	this is a legacy setup git-clone created by default in
-	older Git versions, and will be removed before the next
-	major release.
-
 <repository>::
 	The (possibly remote) repository to clone from.  It can
 	be any URL git-fetch supports.
diff --git a/git-clone.sh b/git-clone.sh
index 68dc4f2..490f3e4 100755
--- a/git-clone.sh
+++ b/git-clone.sh
@@ -14,7 +14,7 @@ die() {
 }
 
 usage() {
-	die "Usage: $0 [--template=<template_directory>] [--no-separate-remote] [--reference <reference-repo>] [--bare] [-l [-s]] [-q] [-u <upload-pack>] [--origin <name>] [-n] <repo> [<dir>]"
+	die "Usage: $0 [--template=<template_directory>] [--reference <reference-repo>] [--bare] [-l [-s]] [-q] [-u <upload-pack>] [--origin <name>] [-n] <repo> [<dir>]"
 }
 
 get_repo_base() {
@@ -137,11 +137,9 @@ while
 	*,--template=*)
 	  template="$1" ;;
 	*,-q|*,--quiet) quiet=-q ;;
-	*,--use-separate-remote)
-		# default
-		use_separate_remote=t ;;
+	*,--use-separate-remote) ;;
 	*,--no-separate-remote)
-		use_separate_remote= ;;
+		die "clones are always made with separate-remote layout" ;;
 	1,--reference) usage ;;
 	*,--reference)
 		shift; reference="$1" ;;
@@ -327,12 +325,8 @@ cd "$D" || exit
 
 if test -z "$bare" && test -f "$GIT_DIR/REMOTE_HEAD"
 then
-	# Figure out which remote branch HEAD points at.
-	case "$use_separate_remote" in
-	'')	remote_top=refs/heads ;;
-	*)	remote_top="refs/remotes/$origin" ;;
-	esac
-
+	# a non-bare repository is always in separate-remote layout
+	remote_top="refs/remotes/$origin"
 	head_sha1=`cat "$GIT_DIR/REMOTE_HEAD"`
 	case "$head_sha1" in
 	'ref: refs/'*)
@@ -373,46 +367,18 @@ then
 		git-symbolic-ref HEAD "refs/heads/$head_points_at" &&
 
 		# Tracking branch for the primary branch at the remote.
-		case "$use_separate_remote" in
-		t)	origin_track="$remote_top/$head_points_at"
-			git-update-ref HEAD "$head_sha1" ;;
-		*)	origin_track="$remote_top/$origin"
-			git-update-ref "refs/heads/$origin" "$head_sha1" ;;
-		esac &&
+		origin_track="$remote_top/$head_points_at" &&
+		git-update-ref HEAD "$head_sha1" &&
 
 		# Upstream URL
 		git-repo-config remote."$origin".url "$repo" &&
 
 		# Set up the mappings to track the remote branches.
-		case "$use_separate_remote" in
-		t)
-			git-repo-config remote."$origin".fetch \
-				"refs/heads/*:$remote_top/*" '^$'
-			;;
-		*)
-			git-repo-config remote."$origin".fetch \
-				"refs/heads/$head_points_at:$origin_track" &&
-			(cd "$GIT_DIR/$remote_top" && find . -type f -print) |
-			while read dotslref
-			do
-				name=`expr "$dotslref" : './\(.*\)'`
-				if test "z$head_points_at" = "z$name" ||
-					test "z$origin" = "z$name"
-				then
-					continue
-				fi
-				git-repo-config remote."$origin".fetch \
-				"refs/heads/${name}:$remote_top/${name}" '^$'
-			done
-			;;
-		esac &&
-
-		case "$use_separate_remote" in
-		t)
-			rm -f "refs/remotes/$origin/HEAD"
-			git-symbolic-ref "refs/remotes/$origin/HEAD" \
-				"refs/remotes/$origin/$head_points_at"
-		esac &&
+		git-repo-config remote."$origin".fetch \
+			"refs/heads/*:$remote_top/*" '^$' &&
+		rm -f "refs/remotes/$origin/HEAD"
+		git-symbolic-ref "refs/remotes/$origin/HEAD" \
+			"refs/remotes/$origin/$head_points_at" &&
 
 		git-repo-config branch."$head_points_at".remote "$origin" &&
 		git-repo-config branch."$head_points_at".merge "refs/heads/$head_points_at"

Re: [PATCH] git-clone: lose the traditional 'no-separate-remote' layout

[Linus Torvalds]

On Sat, 16 Dec 2006, Junio C Hamano wrote:
> 
>  And this drops it; modulo bugs, I think this is about it for
>  v1.5.0 around this area.

Ahh, you said that yourself, and I hadn't even noticed that you already 
merged xdl_merge into master too.

So here's an "AOL high five": <me too>.

Re: [PATCH] git-clone: lose the artificial "first" fetch refspec

[Johannes Schindelin]

Hi,

On Sat, 16 Dec 2006, Junio C Hamano wrote:

>  With the recent flurry of UI updates, I think it is sane to do
>  that before v1.5.0; opinions?

Answering to all of your recent patches in this direction: I like it.

Originally, I thought that this would require more from me: I often 
synchronize my git repository (including topic branches) between different 
machines back and forth, via usb stick, and two different central 
machines. I use the script I sent in this mail:

http://article.gmane.org/gmane.comp.version-control.git/6956/

However, I just realized that I will not need the script anymore, what 
with the recent addition of wildcards to remote.<branch>.fetch. Good job!

Ciao,
Dscho

Re: [PATCH] git-pull: refuse default merge without branch.*.merge

[Linus Torvalds]

On Sat, 16 Dec 2006, Junio C Hamano wrote:
>
> Everybody hated the pull behaviour of merging the first branch
> listed on remotes/* file (or remote.*.fetch config) into the
> current branch.  This finally corrects that UI wart by
> forbidding "git pull" without an explicit branch name on the
> command line or branch.$current.merge for the current branch.

Yay!

May I suggest also just merging the built-in 3-way merge, and just calling 
the resulting version 1.5.0?

With all the "git add" and documentation cleanups, and these kinds of 
fundamental changes in behaviour (not that anybody will hopefully 
_notice_, and if they do they'll hopefully just be grateful, but it's 
still conceptually a big step), I think it's definitely worth a new 
version number.

Maybe even "2.0", although since we're still backwards compatible in all 
ways that really matter, a major number might be too big a step.

Re: [PATCH] git-clone: use wildcard specification for tracking branches

[Jakub Narebski]

Junio C Hamano wrote:

> This stops enumerating the set of branches found on the remote
> side when a clone was made in the configuration file.  Instead,
> a single entry that maps each remote branch to the local
> tracking branch for the remote under the same name is created.
> 
> Doing it this way not only shortens the configuration file, but
> automatically adjusts to a new branch added on the remote side
> after the clone is made.
[...]

Does this deal with non-fast-forward branches like 'pu'? Does
it add $head_points_at at the beginning, before glob... wait,
this is not needed if there is branch.$head_points_at.merge.
But perhaps it still would be better to have:

  [remote "origin"]
        url   = git://git.kernel.org/pub/scm/git/git.git
        fetch = refs/heads/master:refs/remotes/origin/master
        fetch = refs/heads/*:refs/remotes/origin/*
        fetch =+refs/heads/pu:refs/remotes/origin/pu

  [branch "master"]
        remote = origin
        merge  = refs/heads/master ;# full spec of remote branch

But this is very nice. Thanks.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Junio C Hamano]

>> I am hoping that we can start a stabilization cycle for v1.5.0
>> based on what we have in 'master'.  The theme is "usability and
>> teachability".
>> 
>> Things that need to be done to complete what have been merged to
>> 'master' are:
>> 
>>  - 'git-rm' needs to be fixed up as Linus outlined; remove
>>    working tree file and index entry but have a sanity check to
>>    make sure the working tree file match the index and HEAD.
>> 
>>  - 'git-branch' may need to be taught about renaming the
>>    matching per-branch configuration at the same time.
>> 
>>  - 'git-merge-file' needs to be documented and linked from
>>    git.txt.
>> 
>>  - 'git-clone' probably should be updated to use wild-card in
>>    remote.origin.fetch, instead of listing all the branches it
>>    found when the clone was made.
>> 
>>  - tutorials and other Porcelain documentation pages need to be
>>    updated to match the updated 'git-add' and 'git-rm' (to be
>>    updated), and their description should be made much less
>>    about implementation; they should talk in terms of end-user
>>    workflows.  I will send a draft for 'git diff' out later, but
>>    somebody needs a full sweep on Porcelain-ish documentation.
>> 
>>  - 'git diff --index' patch should be reverted (already done in
>>    'next'), although we may have to come up with a better
>>    wording for --cached.

I'm done with 2 out of the above six ("diff --index", and
"clone") and a bit of the "documentation" item so far, and will
go to bed now.  Any takers for the remaining tasks while I'll be
sleeping ;-)?

[PATCH] Document git-merge-file

[Johannes Schindelin]

Most of this is derived from the documentation of RCS merge.

Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
---

	On Sat, 16 Dec 2006, Junio C Hamano wrote:

	> >>  - 'git-merge-file' needs to be documented and linked from
	> >>    git.txt.

 Documentation/git-merge-file.txt |   92 ++++++++++++++++++++++++++++++++++++++
 Documentation/git.txt            |    3 +
 2 files changed, 95 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt
new file mode 100644
index 0000000..0b41d66
--- /dev/null
+++ b/Documentation/git-merge-file.txt
@@ -0,0 +1,92 @@
+git-merge-file(1)
+============
+
+NAME
+----
+git-merge-file - threeway file merge
+
+
+SYNOPSIS
+--------
+[verse]
+'git-merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]]
+	[-p|--stdout] [-q|--quiet] <current-file> <base-file> <other-file>
+
+
+DESCRIPTION
+-----------
+git-file-merge incorporates all changes that lead from the `<base-file>`
+to `<other-file>` into `<current-file>`. The result ordinarily goes into
+`<current-file>`. git-merge-file is useful for combining separate changes
+to an original. Suppose `<base-file>` is the original, and both
+`<current-file>` and `<other-file>` are modifications of `<base-file>`.
+Then git-merge-file combines both changes.
+
+A conflict occurs if both `<current-file>` and `<other-file>` have changes
+in a common segment of lines. If a conflict is found, git-merge-file
+normally outputs a warning and brackets the conflict with <<<<<<< and
+>>>>>>> lines. A typical conflict will look like this:
+
+	<<<<<<< A
+	lines in file A
+	=======
+	lines in file B
+	>>>>>>> B
+
+If there are conflicts, the user should edit the result and delete one of
+the alternatives.
+
+The exit value of this program is negative on error, and the number of
+conflicts otherwise. If the merge was clean, the exit value is 0.
+
+git-merge-file is designed to be a minimal clone of RCS merge, that is, it
+implements all of RCS merge's functionality which is needed by
+gitlink:git[1].
+
+
+OPTIONS
+-------
+
+-L <label>::
+	This option may be given up to three times, and
+	specifies labels to be used in place of the
+	corresponding file names in conflict reports. That is,
+	`git-merge-file -L x -L y -L z a b c` generates output that
+	looks like it came from files x, y and z instead of
+	from files a, b and c.
+
+-p::
+	Send results to standard output instead of overwriting
+	`<current-file>`.
+
+-q::
+	Quiet;  do  not  warn about conflicts.
+
+
+EXAMPLES
+--------
+
+git merge-file README.my README README.upstream::
+
+	combines the changes of README.my and README.upstream since README,
+	tries to merge them and writes the result into README.my.
+
+git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345::
+
+	merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels
+	`a` and `c` instead of `tmp/a123` and `tmp/c345`.
+
+
+Author
+------
+Written by Johannes Schindelin <johannes.schindelin@gmx.de>
+
+
+Documentation
+--------------
+Documentation by Johannes Schindelin and the git-list <git@vger.kernel.org>,
+with parts copied from the original documentation of RCS merge.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b9b1e63..b9fc9ae 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -359,6 +359,9 @@ gitlink:git-init-db[1]::
 	Creates an empty git object database, or reinitialize an
 	existing one.
 
+gitlink:git-merge-file[1]::
+	Runs a threeway merge.
+
 gitlink:git-merge-index[1]::
 	Runs a merge for files needing merging.
 
-- 
1.4.4.2.g5dc03

Re: What's in git.git (stable)

[Jakub Narebski]

Junio C Hamano wrote:

> Things that need to be done to complete what have been merged to
> 'master' are:

What about discussed but not implemented moving restriction on non-head refs
from git-checkout (forbidding to checkout tags, remotes, and arbitrary
commits like HEAD~n) to git-commit (allowing commiting only to heads refs)?
Probably non-heads refs should be saved in HEAD as explicit sha1 of a
commit; this way we wont run into situation where HEAD changed under us
(because it was for example to remote branch, and we fetched since).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Jakub Narebski]

Junio C Hamano wrote:

> Things that need to be done to complete what have been merged to
> 'master' are:

What about discussed but not implemented moving restriction on non-head refs
from git-checkout (forbidding to checkout tags, remotes, and arbitrary
commits like HEAD~n) to git-commit (allowing commiting only to heads refs)?
Probably non-heads refs should be saved in HEAD as explicit sha1 of a
commit; this way we wont run into situation where HEAD changed under us
(because it was for example to remote branch, and we fetched since).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: What's in git.git (stable)

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Junio C Hamano wrote:
>
>> Things that need to be done to complete what have been merged to
>> 'master' are:
>
> What about discussed but not implemented moving restriction on non-head refs
> from git-checkout (forbidding to checkout tags, remotes, and arbitrary
> commits like HEAD~n) to git-commit (allowing commiting only to heads refs)?

Did I miss a patch? ;-)

I've taken a look at it once, and it is usually easy to decide
if we should allow or disallow manipulation of the HEAD at
individual places that tries to look at it or modify it, but
there are many places and giving reasonable error messages to
all of the places we would want to disallow would be quite a lot
of work.  In other words, it is rather a wide-and-shallow change
all over manipulators section of Porcelain.  So from my point of
view it is backburnered, but that does not mean I would object
to a patch that does it cleanly ;-).

[RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

This is still rough, but I think we have a pretty good idea what
will and what won't be in v1.5.0 by now, and end-of-year is a
good slow time to summarize what we have done.

One thing I am wondering is if delta from v1.4.4.3 is good
enough for the intended audience of this release notes.  I am
reasonably sure that the name v1.5.0 will attract more people
than usual and there will be many people upgrading directly from
ancient versions such as v1.1.6 or v1.2.0, and there are a
handful "one-way-street upgrades" and quite a few user visible
changes that already have happened before v1.4.4.  Namely:

 - Pack-compatible loose object headers, introduced between
   v1.4.1 and v1.4.2; repository cannot be read with ancient
   version of git anymore -- this is a one-way street but
   core.legacyheaders is still not enabled by default);

 - delta-base-offset pack encoding, introduced between v1.4.2
   and v1.4.3; this is also a one-way street.

 - 'git -p' to paginate anything -- many commands do pagination
   by default on a tty.  Introduced between v1.4.1 and v1.4.2;
   this may surprise old timer users.

 - 'git archive' superseded 'git tar' in v1.4.3;

 - 'git pack-refs' appeared in v1.4.4;

 - 'git cvsserver' was new invention in v1.3.0;

 - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were
   seriously enhanced during v1.4.0 timeperiod.

 - 'gitweb' became part of git.git during v1.4.0 timeperiod and
   seriously modified since then.

 - reflog is v1.4.0 invention.

In the following, I am assuming that jc/utf8 and jc/fsck-reflog
topics currently in 'next' will be part of v1.5.0.


-- >8 --

Updates in v1.5.0 since v1.4.4 series
-------------------------------------

* Index manipulation

 - git-add is to add contents to the index (aka "staging area"
   for the next commit), whether the file the contents happen to
   be is an existing one or a newly created one.

 - git-add without any argument does not add everything
   anymore.  Say "git add ." if you want to.

 - git-add tries to be more friendly to users by offering an
   interactive mode.

 - git-commit <path> used to refuse to commit if <path> was
   different between HEAD and the index (i.e. update-index was
   used on it earlier).  This check was removed.

 - git-rm is much saner and safer.  It is used to remove paths
   from both the index file and the working tree, and makes sure
   you are not losing any local modification before doing so.

 - git-reset <tree> <paths>... can be used to revert index
   entries for selected paths.

 - git-update-index is much less visible.


* Repository layout

 - The data for origin repository is stored in the configuration
   file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly
   created clones (the latter is still supported).

 - git-clone always uses what is known as "separate remote"
   layout for a newly created repository with a working tree;
   i.e. tracking branches in $GIT_DIR/refs/remotes/origin/ are
   used to track branches from the origin.  New branches that
   appear on the origin side after a clone is made are also
   tracked automatically.

 - git-clone used to be buggy and copied refs outside refs/heads
   and refs/tags; it doesn't anymore.

 - git-branch and git-show-branch know remote tracking branches.

 - git-push can now be used to delete a remote branch or a tag.


* Reflog

 - Reflog records the history of where the tip of each branch
   was at each moment.  This facility is enabled by default for
   repositories with working trees, and can be accessed with the
   "branch@{time}" and "branch@{Nth}" notation.

 - "git show-branch" learned showing the reflog data with the
   new --reflog option.

 - The commits referred to by reflog entries are now protected
   against pruning.  The new command "git reflog expire" can be
   used to truncate older reflog entries and entries that refer
   to commits that have been pruned away previously.

   Existing repositories that have been using reflog may get
   complaints from fsck-objects; please run "git reflog expire
   --all" first to remove reflog entries that refer to commits
   that are no longer in the repository before attempting to
   repack it.

 - git-branch knows how to rename branches and moves existing
   reflog data from the old branch to the new one.


* Packed refs

 - Repositories with hundreds of tags have been paying large
   overhead, both in storage and in runtime.  A new command,
   git-pack-refs, can be used to "pack" them in more efficient
   representation.

 - Clones and fetches over dumb transports are now aware of
   packed refs and can download from repositories that use
   them.


* Configuration

 - configuration related to colorize setting are consolidated
   under color.* namespace (older diff.color.*, status.color.*
   are still supported).


* Less external dependency

 - We have been depended on "merge" program from RCS suite for
   the file-level 3-way merge, but now we lost this dependency.

 - The original implementation of git-merge-recursive which was
   in Python has been removed; we have C implementation of it
   now.

 - git-shortlog is not in Perl anymore, and more importantly it
   does not have to be piped output from git-log.  It can
   traverse the commit ancestry itself.


* I18n

 - We have always encouraged the commit message to be encoded in
   UTF-8, but the users are allowed to use legacy encoding as
   appropriate for their projects (which will never change).
   A non UTF-8 commit encoding however _must_ be explicitly set
   with i18n.commitencoding in the repository configuration;
   otherwise git-commit-tree will complain if the log message does
   not look like a valid UTF-8 string.

 - A commit object recorded in non UTF-8 encoding records the
   encoding i18n.commitencoding specified in the originating
   repository in a new "encoding" header.  This information is
   used by git-log and friends to reencode the message to UTF-8
   when displaying.


* User support

 - Quite a lot of documentation updates.

 - Bash completion scripts have been updated heavily.

 - Better error messages for often used Porcelainish commands.


----------------------------------------------------------------
(shortlog since v1.4.4.3 here)

Re: [RFH] An early draft of v1.5.0 release notes

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> This is still rough, but I think we have a pretty good idea what
> will and what won't be in v1.5.0 by now, and end-of-year is a
> good slow time to summarize what we have done.

This is certainly a good idea.  And your summary was pretty good
too, I enjoyed the read.  This group has certainly accomplished
quite a bit lately!

Just a few comments:
 
>  - Pack-compatible loose object headers, introduced between
>    v1.4.1 and v1.4.2; repository cannot be read with ancient
>    version of git anymore -- this is a one-way street but
>    core.legacyheaders is still not enabled by default);
> 
>  - delta-base-offset pack encoding, introduced between v1.4.2
>    and v1.4.3; this is also a one-way street.

Perhaps you can clarify that using these means the repository
cannot be used with an earlier version of Git?  You may also want
to highlight why these features are good, answering the question
"Why should I enable them if it breaks backwards compatibility?".

Isn't the new packed-refs format also a one-way street?  If you
use them for tags on a web server and the client is using a very
old http commit walker, what happens?
 
>  - git-clone used to be buggy and copied refs outside refs/heads
>    and refs/tags; it doesn't anymore.

I mentioned to you on #git this morning that I don't think this
is noteworthy for this release.

You missed talking about the mess of pack files created by git-push
now, especially with pushes over 100 objects.  ;-)
 
>  - git-push can now be used to delete a remote branch or a tag.

You should mention this requires server side support too.  I read
that and assumed I could just upgrade my client and push to delete
- which isn't the case, and I know its not...  but I still read it
that way.
 
>  - "git show-branch" learned showing the reflog data with the
>    new --reflog option.

I had hoped we could get 'git reflog show' into 1.5.0 but the
current discussion with Johannes seems like that's unlikely.
 
>  - We have been depended on "merge" program from RCS suite for
>    the file-level 3-way merge, but now we lost this dependency.

Perhaps just reword as:

	We no longer require the "merge" program from the RCS suite.
	All 3-way file-level merges are now done internally.
 
>  - git-shortlog is not in Perl anymore, and more importantly it
>    does not have to be piped output from git-log.  It can
>    traverse the commit ancestry itself.

The "traverse the commit ancestry itself" part is not very
readable for the average user.  How about instead:

	git-shortlog is no longer a Perl script.  git-shortlog also
	no longer requires output piped from git-log; it can accept
	revision parameters directly on the command line.

-- 
Shawn.

Re: [RFH] An early draft of v1.5.0 release notes

[Jakub Narebski]

Junio C Hamano wrote:

> This is still rough, but I think we have a pretty good idea what
> will and what won't be in v1.5.0 by now, and end-of-year is a
> good slow time to summarize what we have done.

Very nice idea! Perhaps those release notes can find it's way into
either v1.5.0 commit, or v1.5.0 tag comment?

Just a few comments:

>  - git-add without any argument does not add everything
>    anymore.  Say "git add ." if you want to.
> 
>  - git-add tries to be more friendly to users by offering an
>    interactive mode.

Perhaps information that git-add can be used to add ignored files
with -f option should be added? Or is it not important enough?
 
>  - The commits referred to by reflog entries are now protected
>    against pruning.  The new command "git reflog expire" can be
>    used to truncate older reflog entries and entries that refer
>    to commits that have been pruned away previously.
> 
>    Existing repositories that have been using reflog may get
>    complaints from fsck-objects; please run "git reflog expire
>    --all" first to remove reflog entries that refer to commits
>    that are no longer in the repository before attempting to
>    repack it.

That's a bit bad, as it forces to lose some info... but that
info was not that useful anyway.
 
>  - A commit object recorded in non UTF-8 encoding records the
>    encoding i18n.commitencoding specified in the originating
>    repository in a new "encoding" header.  This information is
>    used by git-log and friends to reencode the message to UTF-8
>    when displaying.

I don't quite like it. Why if someone uses different encoding
that utf-8 because his terminal is not set to utf-8? Having suddenly
what looks like garbage on output, while input was in local encoding
(and specified in i18n.commitencoding) is a bit suprising...
 
> ----------------------------------------------------------------
> (shortlog since v1.4.4.3 here)

I'd rather have description a la "what's cooking" here... 

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> That's a bit bad, as it forces to lose some info... but that
> info was not that useful anyway.

I am tired of listening to this useless FUD of yours.  You lost
the information when you pruned away the underlying objects; you
are not losing information when you expire the reflog entries
that became useless long time ago.

> I don't quite like it. Why if someone uses different encoding
> that utf-8 because his terminal is not set to utf-8? Having suddenly
> what looks like garbage on output, while input was in local encoding
> (and specified in i18n.commitencoding) is a bit suprising...

If Luben wants UTF-8 in his project, but somebody he pulled from
was mistakenly used latin-1, then the commit pulled record
latin-1 while Luben has i18n.commitencoding in his repository
set to UTF-8.  Output will be done in UTF-8 for Luben.  For the
originator of that latin-1 commit, i18n.commitencoding says
latin-1 (and that was the only reason he managed to create such
a commit) and git show of that commit would not involve
recoding.

At least that is the idea.  Have you spotted a bug, perhaps?

>> (shortlog since v1.4.4.3 here)
>
> I'd rather have description a la "what's cooking" here... 

Send the summary to the list and I'll append it to the release
notes.

Re: [RFH] An early draft of v1.5.0 release notes

[Johannes Schindelin]

Hi,

On Wed, 27 Dec 2006, Junio C Hamano wrote:

> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > I don't quite like it. Why if someone uses different encoding
> > that utf-8 because his terminal is not set to utf-8? Having suddenly
> > what looks like garbage on output, while input was in local encoding
> > (and specified in i18n.commitencoding) is a bit suprising...
> 
> If Luben wants UTF-8 in his project, but somebody he pulled from was 
> mistakenly used latin-1, then the commit pulled record latin-1 while 
> Luben has i18n.commitencoding in his repository set to UTF-8.  Output 
> will be done in UTF-8 for Luben.  For the originator of that latin-1 
> commit, i18n.commitencoding says latin-1 (and that was the only reason 
> he managed to create such a commit) and git show of that commit would 
> not involve recoding.

I think that this is a misunderstanding. Maybe the config variable is 
misnamed. As is clearly visible from the commit messages, this whole stuff 
is meant to reencode to whatever encoding the caller of git-log likes, not 
just UTF-8. And it defaults to UTF-8, overridable by i18n.commitEncoding.

BTW I think that latin-1 is not a valid encoding name (at least in my 
setup it isn't), so we should rather talk about iso-8859-1.

Ciao,
Dscho

Re: [RFH] An early draft of v1.5.0 release notes

[Jakub Narebski]

Johannes Schindelin wrote:

> BTW I think that latin-1 is not a valid encoding name (at least in my 
> setup it isn't), so we should rather talk about iso-8859-1.

"iconv --list" include l1 and latin1 as aliases to the proper name
of encoding, i.e. iso-8859-1; but not latin-2.
-- 
Jakub Narebski
Poland

Re: [RFH] An early draft of v1.5.0 release notes

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>> Junio C Hamano wrote:
>>>
>>>  - The commits referred to by reflog entries are now protected
>>>    against pruning.  The new command "git reflog expire" can be
>>>    used to truncate older reflog entries and entries that refer
>>>    to commits that have been pruned away previously.
>>>
>>>    Existing repositories that have been using reflog may get
>>>    complaints from fsck-objects; please run "git reflog expire
>>>    --all" first to remove reflog entries that refer to commits
>>>    that are no longer in the repository before attempting to
>>>    repack it.
>>
>> That's a bit bad, as it forces to lose some info... but that
>> info was not that useful anyway.
> 
> I am tired of listening to this useless FUD of yours.  You lost
> the information when you pruned away the underlying objects; you
> are not losing information when you expire the reflog entries
> that became useless long time ago.

Sorry, this is a bit of my inner packrat ;-) showing thru.

I'd rather use "git reflog expire --pruned" to remove reflog entries
which refer to commits which are no longer in the repository; I don't
know, perhaps "git reflog expire --all" does that: but there is no
Documentation/git-reflog.txt (and I'm not running 'next' nor 'master'
but 1.4.4.3). So most probably it is just the case of adding an alias
to reflog expire option.

>>>  - A commit object recorded in non UTF-8 encoding records the
>>>    encoding i18n.commitencoding specified in the originating
>>>    repository in a new "encoding" header.  This information is
>>>    used by git-log and friends to reencode the message to UTF-8
>>>    when displaying.
>>
>> I don't quite like it. Why if someone uses different encoding
>> that utf-8 because his terminal is not set to utf-8? Having suddenly
>> what looks like garbage on output, while input was in local encoding
>> (and specified in i18n.commitencoding) is a bit suprising...
> 
> If Luben wants UTF-8 in his project, but somebody he pulled from
> was mistakenly used latin-1, then the commit pulled record
> latin-1 while Luben has i18n.commitencoding in his repository
> set to UTF-8.  Output will be done in UTF-8 for Luben.  For the
> originator of that latin-1 commit, i18n.commitencoding says
> latin-1 (and that was the only reason he managed to create such
> a commit) and git show of that commit would not involve
> recoding.
> 
> At least that is the idea.  Have you spotted a bug, perhaps?

Perhaps that is the idea, but that idea is not described in above
new feature announcement. "... to reencode the message to UTF-8 
when displaying, if needed." would cover it, but perhaps better
would be to cover this in more detail: "reencode message to UTF-8
if i18n.commitencoding is not set to something other than UTF-8",
or "reencode ... to i18n.commitencoding ... if needed".

BTW. what happens for NO_ICONV? Just curious...

-- 
Jakub Narebski
Poland

Re: [RFH] An early draft of v1.5.0 release notes

[Horst H. von Brand]

Jakub Narebski <jnareb@gmail.com> wrote:

[...]

> Perhaps that is the idea, but that idea is not described in above
> new feature announcement. "... to reencode the message to UTF-8 
> when displaying, if needed." would cover it, but perhaps better
> would be to cover this in more detail: "reencode message to UTF-8
> if i18n.commitencoding is not set to something other than UTF-8",
> or "reencode ... to i18n.commitencoding ... if needed".

And what happens to the people who can't/won't display UTF-8? This is a
both a project wide configuration (how does stuff get saved) + a user/local
configuration (how to display stuff).
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

"Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:

> Jakub Narebski <jnareb@gmail.com> wrote:
>
> [...]
>
>> Perhaps that is the idea, but that idea is not described in above
>> new feature announcement. "... to reencode the message to UTF-8 
>> when displaying, if needed." would cover it, but perhaps better
>> would be to cover this in more detail: "reencode message to UTF-8
>> if i18n.commitencoding is not set to something other than UTF-8",
>> or "reencode ... to i18n.commitencoding ... if needed".
>
> And what happens to the people who can't/won't display UTF-8? This is a
> both a project wide configuration (how does stuff get saved) + a user/local
> configuration (how to display stuff).

Presumably you would do something like:

	git log | tcs -f utf -t latin1 | less

The point being that the input to tcs will be uniformly UTF-8
even the committers used Latin-1 and UTF-8, either carelessly or
deliberately [*1*].

Maybe i18n.displayencoding set to latin1 is what you are after?
I think it might make sense...

In any case, as Jakub and others pointed out, the description
was not nice nor clear.  How about this as an update?

* I18n

 - We have always encouraged the commit message to be encoded in
   UTF-8, but the users are allowed to use legacy encoding as
   appropriate for their projects.  This will continue to be the
   case.  However, a non UTF-8 commit encoding _must_ be
   explicitly set with i18n.commitencoding in the repository
   where a commit is made; otherwise git-commit-tree will
   complain if the log message does not look like a valid UTF-8
   string.

[Side note: in v1.5.0 preview, it only warns about this
 situation; I have a feeling that it might be better to promote
 this to an error and refuse to commit until the user sets
 i18n.commitencoding to the name of the legacy encoding used for
 the project -- this will be a one-time inconvenience but will
 be much better in the long run.]

 - The value of i18n.commitencoding in the originating
   repository is recorded in the commit object on the "encoding"
   header, if it is not UTF-8.  git-log and friends notice this,
   and reencodes the message to the encoding specified with
   i18n.commitencoding when displaying, if they are different.


[Footnote]

*1* For encoding as simple as Latin I do not think it is an
issue, but we do not want to encode everything to UTF-8 at
commit time, because non-reversible conversion can lose
information.  I do not want to rule out a situation where a
particular commit log entry needs to be in an encoding different
from the project norm, which hopefully is UTF-8, because it
needs to describe something in a character that cannot be
reversibly converted to UTF-8 (maybe the project is about iconv
enhancement, the commit fixes something related to irreversible
conversion and the log message wants to give an example).

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> "Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:
> ...
>> And what happens to the people who can't/won't display UTF-8? This is a
>> both a project wide configuration (how does stuff get saved) + a user/local
>> configuration (how to display stuff).
> ...
> Maybe i18n.displayencoding set to latin1 is what you are after?
> I think it might make sense...

I've done this and will be pushing the result out in 'next'
shortly, with a new test.  I find the result mostly sensible.

Re: [RFH] An early draft of v1.5.0 release notes

[Nicolas Pitre]

On Wed, 27 Dec 2006, Junio C Hamano wrote:

> Junio C Hamano <junkio@cox.net> writes:
> 
> > "Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:
> > ...
> >> And what happens to the people who can't/won't display UTF-8? This is a
> >> both a project wide configuration (how does stuff get saved) + a user/local
> >> configuration (how to display stuff).
> > ...
> > Maybe i18n.displayencoding set to latin1 is what you are after?
> > I think it might make sense...
> 
> I've done this and will be pushing the result out in 'next'
> shortly, with a new test.  I find the result mostly sensible.

Shouldn't the LANG environment variable be used for this purpose 
instead?


Nicolas

Re: [RFH] An early draft of v1.5.0 release notes

[David Kågedal]

Nicolas Pitre <nico@cam.org> writes:

> On Wed, 27 Dec 2006, Junio C Hamano wrote:
>
>> Junio C Hamano <junkio@cox.net> writes:
>> 
>> > "Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:
>> > ...
>> >> And what happens to the people who can't/won't display UTF-8? This is a
>> >> both a project wide configuration (how does stuff get saved) + a user/local
>> >> configuration (how to display stuff).
>> > ...
>> > Maybe i18n.displayencoding set to latin1 is what you are after?
>> > I think it might make sense...
>> 
>> I've done this and will be pushing the result out in 'next'
>> shortly, with a new test.  I find the result mostly sensible.
>
> Shouldn't the LANG environment variable be used for this purpose 
> instead?

You mean LC_CTYPE, no?

-- 
David Kågedal

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> ... I don't
> know, perhaps "git reflog expire --all" does that: but there is no
> Documentation/git-reflog.txt (and I'm not running 'next' nor 'master'
> but 1.4.4.3)...

If that is the case, may I ask you to at least please make it a
habit to read what are relevant to the topic under discussion
before jumping in?  The list traffic is already high enough that
I am spending a lot of time just to skim all the messages posted
here -- I think that time is better spent on development and
improvements.

Re: [RFH] An early draft of v1.5.0 release notes

[Jakub Narebski]

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

Jakub Narebski wrote:
> Junio C Hamano wrote:
>> Jakub Narebski <jnareb@gmail.com> writes:
>>> Junio C Hamano wrote:
>>>>
>>>>  - The commits referred to by reflog entries are now protected
>>>>    against pruning.  The new command "git reflog expire" can be
>>>>    used to truncate older reflog entries and entries that refer
>>>>    to commits that have been pruned away previously.
>>>>
>>>>    Existing repositories that have been using reflog may get
>>>>    complaints from fsck-objects; please run "git reflog expire
>>>>    --all" first to remove reflog entries that refer to commits
>>>>    that are no longer in the repository before attempting to
>>>>    repack it.
[...]

> I'd rather use "git reflog expire --pruned" to remove reflog entries
> which refer to commits which are no longer in the repository; I don't
> know, perhaps "git reflog expire --all" does that: but there is no
> Documentation/git-reflog.txt (and I'm not running 'next' nor 'master'
> but 1.4.4.3). So most probably it is just the case of adding an alias
> to reflog expire option.

Thanks for adding Documentation/git-reflog.txt. Nevertheless it didn't
add the information that "git reflog expire" removes reflog entries that
refer to commits that are no longer in the repository (see attached patch).

I'm not sure if such technical information should be in git-reflog(1),
but does only second, current sha1 in reflog line matters for prune?
And does expiring rewrite reflog (previous sha1, making always previous
sha1 (first sha1 in reflog line) always to refer some commit in earlier
reflog line, or before first reflog line), or only delete lines?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

[-- Attachment #2: [PATCH] Add information in git-reflog(1) that "expire" removes pruned entries --]
[-- Type: text/plain, Size: 1327 bytes --]

>From c39e864dec5fc5542e9dd14235a48fa2bb77ed6a Mon Sep 17 00:00:00 2001
From: Jakub Narebski <jnareb@gmail.com>
Date: Thu, 28 Dec 2006 01:30:05 +0100
Subject: [PATCH] Add information in git-reflog(1) that "expire" removes pruned entries

Add information to Documentation/git-reflog.txt that "expire" subcommand
also removes entries which refer to commits that are no longer in
repository.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/git-reflog.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 55a24d3..04ea51a 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -22,11 +22,12 @@ updated.  This command is to manage the information recorded in it.
 The subcommand "expire" is used to prune older reflog entries.
 Entries older than `expire` time, or entries older than
 `expire-unreachable` time and are not reachable from the current
-tip, are removed from the reflog.  This is typically not used
+tip, are removed from the reflog.  Entries which refer to
+commits that are no longer in the repository are pruned
+regardless of their age.  This command is typically not used
 directly by the end users -- instead, see gitlink:git-gc[1].
 
 
-
 OPTIONS
 -------
 
-- 
1.4.4.3

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Just a few comments:
>
>>  - git-add without any argument does not add everything
>>    anymore.  Say "git add ." if you want to.
>
> Perhaps information that git-add can be used to add ignored files
> with -f option should be added? Or is it not important enough?

Thanks.  Will change the above bullet to this:

 - git-add without any argument does not add everything
   anymore.  Use 'git-add .' instead.  Also you can add
   otherwise ignored files with an -f option.

Re: [RFH] An early draft of v1.5.0 release notes

[Horst H. von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> This is still rough, but I think we have a pretty good idea what
> will and what won't be in v1.5.0 by now, and end-of-year is a
> good slow time to summarize what we have done.

Could somebody please summarize how to "upgrade" a repository to the new
layout?  This has got my head spinning... and I'm /not/ cloning the
various repos I've got here just to take advantage of the changes.

Thanks!
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

"Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> This is still rough, but I think we have a pretty good idea what
>> will and what won't be in v1.5.0 by now, and end-of-year is a
>> good slow time to summarize what we have done.
>
> Could somebody please summarize how to "upgrade" a repository to the new
> layout?  This has got my head spinning... and I'm /not/ cloning the
> various repos I've got here just to take advantage of the changes.

The old layout was to map remote branch $B to local tracking
branch .git/refs/heads/$B, unless $B == 'master' in which case
it was mapped to .git/refs/heads/origin (and I think we
discarded 'origin' at remote).

Each remote branch $B is tracked with .git/refs/remote/origin/$B
in the new layout.

And you will get something like this in your .git/config:

    [remote "origin"]
            url = git://git.kernel.org/pub/scm/.../torvalds/linux-2.6.git/
            fetch = refs/heads/*:refs/remotes/origin/*
    [branch "master"]
            remote = origin
            merge = refs/heads/master

The first section defines what the token 'origin' means when you
say "git pull origin" or "git fetch origin".  remote.origin.url
defines the URL to fetch/pull from, and remote.origin.fetch
supplies the refspecs you omitted from the command line (fetch
everything from refs/heads/ hierarchy of remote and store them
in my refs/remotes/origin/ hierarchy).

The second section defines what happens when you say "git pull"
or "git fetch" while on your "master" branch.  It tells that you
meant to say "git pull origin" or "git fetch origin" when you
omitted the URL argument from the command line.  And because you
are also omitting the refspecs, remote.origin.fetch kicks in and
slurps all the branches from the remote side and stores them in
your refs/remotes/origin/ hierarchy.  When the command was "git
pull", it also says the merge that follows the fetch is to merge
the 'master' branch at the remote side (which happens to be
copied to your remotes/origin/master only because you have
remote.origin.fetch) into your current branch (which is
"master", because this section is about what happens while you
are on your "master" branch).

So for an existing repository that does not use the separate
remotes layout, you can easily convert that by hand if you
wanted to by:

 - Move tracking branches from refs/heads/* to
   refs/remotes/origin/*,

 - create the config section like the above in .git/config, and

 - remove .git/remotes/origin when you are done.

Re: [RFH] An early draft of v1.5.0 release notes

[Jakub Narebski]

[Cc: git@vger.kernel.org, Junio C Hamano <junkio@cox.net>,
 "Horst H. von Brand" <vonbrand@inf.utfsm.cl>]

Junio C Hamano wrote:

> "Horst H. von Brand" <vonbrand@inf.utfsm.cl> writes:
> 
>> Junio C Hamano <junkio@cox.net> wrote:
>>> This is still rough, but I think we have a pretty good idea what
>>> will and what won't be in v1.5.0 by now, and end-of-year is a
>>> good slow time to summarize what we have done.
>>
>> Could somebody please summarize how to "upgrade" a repository to the new
>> layout?  This has got my head spinning... and I'm /not/ cloning the
>> various repos I've got here just to take advantage of the changes.
> 
> The old layout was to map remote branch $B to local tracking
> branch .git/refs/heads/$B, unless $B == 'master' in which case
> it was mapped to .git/refs/heads/origin (and I think we
> discarded 'origin' at remote).

How to discard 'origin' in the new wildcard / globbing remote config?
IIRC there was proposal to use '-' or '!' to exclude branch from
fetching, but no code...

[...]
>  - create the config section like the above in .git/config, and

You can use contrib/remotes2config.sh script...

>  - remove .git/remotes/origin when you are done.
 
...which saves remotes/ under remotes.old/
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

An early draft of v1.5.0 release notes (2nd ed)

[Junio C Hamano]

This incorporates comments from the list (thanks).  Maybe I
should park this in 'todo' branch so that people can review the
updates more easily.

-- >8 --

Major changes that are not news
-------------------------------

There were a handful big changes that happened before this major
release.

This section is for people who are upgrading from ancient
versions.  Some of them are one-way street upgrades -- once you
use the feature your repository cannot be used with ancient git.

 - There is a new configuration variable core.legacyheaders that
   changes the format of loose objects to more efficient to pack
   and send out of the repository over git native protocol.
   However, this format cannot be read by git older than v1.4.2;
   people fetching from your repository using older clients over
   dumb transports (e.g. http) will also be affected.  This is
   not enabled by default.

 - Another configuration repack.usedeltabaseoffset further
   allows packfile to be created in more space efficient format,
   which cannot be read  by git older than v1.4.3.  This is not
   enabled by default.

 - 'git pack-refs' appeared in v1.4.4; this command allows tags
   to be accessed much more efficiently than the traditional
   'one-file-per-tag' format.  Older git-native client can fetch
   from a repository that packed its tags, but older dumb
   transports cannot.  This is done by an explicit user action,
   either by use of "git pack-refs --prune" command or by use of
   "git gc" command.

 - 'git -p' to paginate anything -- many commands do pagination
   by default on a tty.  Introduced between v1.4.1 and v1.4.2;
   this may surprise old timer users.

 - 'git archive' superseded 'git tar' in v1.4.3;

 - 'git cvsserver' was new invention in v1.3.0;

 - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were
   seriously enhanced during v1.4.0 timeperiod.

 - 'gitweb' became part of git.git during v1.4.0 timeperiod and
   seriously modified since then.

 - reflog is an v1.4.0 invention.


Updates in v1.5.0 since v1.4.4 series
-------------------------------------

* Index manipulation

 - git-add is to add contents to the index (aka "staging area"
   for the next commit), whether the file the contents happen to
   be is an existing one or a newly created one.

 - git-add without any argument does not add everything
   anymore.  Use 'git-add .' instead.  Also you can add
   otherwise ignored files with an -f option.

 - git-add tries to be more friendly to users by offering an
   interactive mode.

 - git-commit <path> used to refuse to commit if <path> was
   different between HEAD and the index (i.e. update-index was
   used on it earlier).  This check was removed.

 - git-rm is much saner and safer.  It is used to remove paths
   from both the index file and the working tree, and makes sure
   you are not losing any local modification before doing so.

 - git-reset <tree> <paths>... can be used to revert index
   entries for selected paths.

 - git-update-index is much less visible.


* Repository layout and objects transfer

 - The data for origin repository is stored in the configuration
   file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly
   created clones (the latter is still supported).

 - git-clone always uses what is known as "separate remote"
   layout for a newly created repository with a working tree;
   i.e. tracking branches in $GIT_DIR/refs/remotes/origin/ are
   used to track branches from the origin.  New branches that
   appear on the origin side after a clone is made are also
   tracked automatically.

 - git-branch and git-show-branch know remote tracking branches.

 - git-push can now be used to delete a remote branch or a tag.
   This requires the updated git on the remote side.

 - git-push more agressively keeps the transferred objects
   packed.  Earlier we recommended to monitor amount of loose
   objects and repack regularly, but you should repack when you
   accumulated too many small packs this way as well.  Updated
   git-count-objects helps you with this.


* Reflog

 - Reflog records the history of where the tip of each branch
   was at each moment.  This facility is enabled by default for
   repositories with working trees, and can be accessed with the
   "branch@{time}" and "branch@{Nth}" notation.

 - "git show-branch" learned showing the reflog data with the
   new --reflog option.

 - The commits referred to by reflog entries are now protected
   against pruning.  The new command "git reflog expire" can be
   used to truncate older reflog entries and entries that refer
   to commits that have been pruned away previously with older
   versions of git.

   Existing repositories that have been using reflog may get
   complaints from fsck-objects; please run "git reflog expire
   --all" first to remove reflog entries that refer to commits
   that are no longer in the repository before attempting to
   repack it.

 - git-branch knows how to rename branches and moves existing
   reflog data from the old branch to the new one.


* Packed refs

 - Repositories with hundreds of tags have been paying large
   overhead, both in storage and in runtime.  A new command,
   git-pack-refs, can be used to "pack" them in more efficient
   representation.

 - Clones and fetches over dumb transports are now aware of
   packed refs and can download from repositories that use
   them.


* Configuration

 - configuration related to colorize setting are consolidated
   under color.* namespace (older diff.color.*, status.color.*
   are still supported).


* Less external dependency

 - We no longer require the "merge" program from the RCS suite.
   All 3-way file-level merges are now done internally.

 - The original implementation of git-merge-recursive which was
   in Python has been removed; we have C implementation of it
   now.

 - git-shortlog is no longer a Perl script.  It no longer
   requires output piped from git-log; it can accept revision
   parameters directly on the command line.


* I18n

 - We have always encouraged the commit message to be encoded in
   UTF-8, but the users are allowed to use legacy encoding as
   appropriate for their projects.  This will continue to be the
   case.  However, a non UTF-8 commit encoding _must_ be
   explicitly set with i18n.commitencoding in the repository
   where a commit is made; otherwise git-commit-tree will
   complain if the log message does not look like a valid UTF-8
   string.

 - The value of i18n.commitencoding in the originating
   repository is recorded in the commit object on the "encoding"
   header, if it is not UTF-8.  git-log and friends notice this,
   and reencodes the message to the log output encoding when
   displaying, if they are different.  The log output encoding
   is determined by "git log --encoding=<encoding>",
   i18n.logoutputencoding configuration, or i18n.commitencoding
   configuration, in the decreasing order of preference, and
   defaults to UTF-8. 


* User support

 - Quite a lot of documentation updates.

 - Bash completion scripts have been updated heavily.

 - Better error messages for often used Porcelainish commands.

Re: An early draft of v1.5.0 release notes (2nd ed)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> 
> -- >8 --
> 
> Major changes that are not news
> -------------------------------

If these major changes aren't news, what are they?  Chopped liver?
I'm highly confused by the section header.

-- 
Shawn.

Re: An early draft of v1.5.0 release notes (2nd ed)

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> 
>> -- >8 --
>> 
>> Major changes that are not news
>> -------------------------------
>
> If these major changes aren't news, what are they?

Exactly as described in the part you did not quote:

        There were a handful big changes that happened before this major
        release.

        This section is for people who are upgrading from ancient
        versions.

In other words, they are only to help people who were not paying
enough attention to earlier releases.

Re: An early draft of v1.5.0 release notes (2nd ed)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Shawn Pearce <spearce@spearce.org> writes:
> 
> > Junio C Hamano <junkio@cox.net> wrote:
> >> 
> >> -- >8 --
> >> 
> >> Major changes that are not news
> >> -------------------------------
> >
> > If these major changes aren't news, what are they?
> 
> Exactly as described in the part you did not quote:
> 
>         There were a handful big changes that happened before this major
>         release.
> 
>         This section is for people who are upgrading from ancient
>         versions.
> 
> In other words, they are only to help people who were not paying
> enough attention to earlier releases.

OK, yet again I don't quite quote enough.  Or read enough.  ;-)
 
But maybe you can title the section

	Major changes since 1.2.x

?  Or whatever version preceeded when we started to add that stuff?

The section is really for those who are upgrading from ancient
versions, but the title of the section implies (at least to me)
that these changes aren't something important.

Just my (nearly worthless against the Euro) two US pennies...

-- 
Shawn.

Re: An early draft of v1.5.0 release notes (2nd ed)

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> The section is really for those who are upgrading from ancient
> versions, but the title of the section implies (at least to me)
> that these changes aren't something important.

True.  How about "Something important you should already know
but just in case" ;-)?

Re: An early draft of v1.5.0 release notes (2nd ed)

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Shawn Pearce <spearce@spearce.org> writes:
> 
> > The section is really for those who are upgrading from ancient
> > versions, but the title of the section implies (at least to me)
> > that these changes aren't something important.
> 
> True.  How about "Something important you should already know
> but just in case" ;-)?

Sure, that's more fun then my proposed text and does summarize the
section better.  Plus it reminds Git users that maybe they should
track our releases a little bit more often than only on "major"
version number increments.  :-)

-- 
Shawn.

Re: An early draft of v1.5.0 release notes (2nd ed)

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> Shawn Pearce <spearce@spearce.org> writes:
>> 
>> > The section is really for those who are upgrading from ancient
>> > versions, but the title of the section implies (at least to me)
>> > that these changes aren't something important.
>> 
>> True.  How about "Something important you should already know
>> but just in case" ;-)?
>
> Sure, that's more fun then my proposed text and does summarize the
> section better.  Plus it reminds Git users that maybe they should
> track our releases a little bit more often than only on "major"
> version number increments.  :-)

That was a tongue-in-cheek comment.

I consider git is still young and I have the right to gripe at
the list if something that has been cooking in 'next' without
anybody complaining causes a real breakage immediately after it
gets pushed out to 'master'.  But for the rest of the world, git
has already matured enough that there is much less need to be on
the bleeding edge for the lack of something crucial in the last
released version.

And let's face it.  Nobody has enough time to keep track of the
changes to all tools he uses, it is not unusual to skip a
handful of minor versions, and it is a norm to get surprised
after an upgrade of any tool because there was a major change in
a couple of releases back that he skipped.  I do not have the
right to complain if the end users do not follow every minor
release or every issue of "What's in git.git" messages.  Not
anymore.

So I'd like the introductory section to have more positive
spin.  I tried rewording it and pushed it out to 'todo' branch.

Re: An early draft of v1.5.0 release notes (3rd ed)

[Junio C Hamano]

Instead of sending the full text, I'll send out the diff against
the one I sent out on the 27th last month.

 Highlights:

 * Introductory notes have been reworded heavily;

 * I intend to merge bare repository support and detached HEAD
   before v1.5.0, so a section each for them has been added;

 * Sliding mmap and shallow clone are also mentioned.

The full text is available as v1.5.0.txt in 'todo' branch.

--
 v1.5.0.txt |  180 +++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 149 insertions(+), 31 deletions(-)

diff --git a/v1.5.0.txt b/v1.5.0.txt
index 671c14b..9bbe825 100644
--- a/v1.5.0.txt
+++ b/v1.5.0.txt
@@ -1,37 +1,54 @@
-Major changes that are not news
--------------------------------
+GIT v1.5.0 Release Notes
+========================
 
-There were a handful big changes that happened before this major
-release.
+Old news
+--------
 
 This section is for people who are upgrading from ancient
-versions.  Some of them are one-way street upgrades -- once you
-use the feature your repository cannot be used with ancient git.
-
- - There is a new configuration variable core.legacyheaders that
-   changes the format of loose objects to more efficient to pack
-   and send out of the repository over git native protocol.
-   However, this format cannot be read by git older than v1.4.2;
-   people fetching from your repository using older clients over
-   dumb transports (e.g. http) will also be affected.  This is
-   not enabled by default.
-
- - Another configuration repack.usedeltabaseoffset further
-   allows packfile to be created in more space efficient format,
-   which cannot be read  by git older than v1.4.3.  This is not
-   enabled by default.
+versions of git.  Although all of the changes in this section
+happened before the current v1.4.4 release, they are summarized
+here in the v1.5.0 release notes for people who skipped earlier
+versions.
+
+In general, you should not have to worry about incompatibility,
+and there is no need to perform "repository conversion" if you
+are updating to v1.5.0.  However, some of the changes are
+one-way street upgrades; once you use them your repository
+can no longer be used with ancient git.
+
+ - There is a configuration variable core.legacyheaders that
+   changes the format of loose objects so that they are more
+   efficient to pack and to send out of the repository over git
+   native protocol, since v1.4.2.  However, loose objects
+   written in the new format cannot be read by git older than
+   that version; people fetching from your repository using
+   older clients over dumb transports (e.g. http) using older
+   versions of git will also be affected.
+
+ - Since v1.4.3, configuration repack.usedeltabaseoffset allows
+   packfile to be created in more space efficient format, which
+   cannot be read by git older than that version.
+
+The above two are not enabled by default and you explicitly have
+to ask for them, because these two features make repositories
+unreadable by older versions of git, and in v1.5.0 we still do
+not enable them by default for the same reason.  We will change
+this default probably 1 year after 1.4.2's release, when it is
+reasonable to expect everybody to have new enough version of
+git.
 
  - 'git pack-refs' appeared in v1.4.4; this command allows tags
    to be accessed much more efficiently than the traditional
-   'one-file-per-tag' format.  Older git-native client can fetch
-   from a repository that packed its tags, but older dumb
-   transports cannot.  This is done by an explicit user action,
-   either by use of "git pack-refs --prune" command or by use of
-   "git gc" command.
+   'one-file-per-tag' format.  Older git-native clients can
+   still fetch from a repository that packed and pruned refs
+   (the server side needs to run the up-to-date version of git),
+   but older dumb transports cannot.  Packing of refs is done by
+   an explicit user action, either by use of "git pack-refs
+   --prune" command or by use of "git gc" command.
 
  - 'git -p' to paginate anything -- many commands do pagination
    by default on a tty.  Introduced between v1.4.1 and v1.4.2;
-   this may surprise old timer users.
+   this may surprise old timers.
 
  - 'git archive' superseded 'git tar' in v1.4.3;
 
@@ -43,7 +60,10 @@ use the feature your repository cannot be used with ancient git.
  - 'gitweb' became part of git.git during v1.4.0 timeperiod and
    seriously modified since then.
 
- - reflog is an v1.4.0 invention.
+ - reflog is an v1.4.0 invention.  This allows you to name a
+   revision that a branch used to be at (e.g. "git diff
+   master@{yesterday} master" allows you to see changes since
+   yesterday's tip of the branch).
 
 
 Updates in v1.5.0 since v1.4.4 series
@@ -80,7 +100,9 @@ Updates in v1.5.0 since v1.4.4 series
 
  - The data for origin repository is stored in the configuration
    file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly
-   created clones (the latter is still supported).
+   created clones.  The latter is still supported and there is
+   no need to convert your existing repository if you are
+   already comfortable with your workflow with the layout.
 
  - git-clone always uses what is known as "separate remote"
    layout for a newly created repository with a working tree;
@@ -100,6 +122,26 @@ Updates in v1.5.0 since v1.4.4 series
    accumulated too many small packs this way as well.  Updated
    git-count-objects helps you with this.
 
+ - A new command, git-remote, can help you manage your remote
+   tracking branch definitions.
+
+
+* Bare repositories
+
+ - Certain commands change their behaviour in a bare repository
+   (i.e. a repository without associated working tree).  We use
+   a fairly conservative heuristic (if $GIT_DIR is ".git", or
+   ends with "/.git", the repository is not bare) to decide if a
+   repository is bare, but "core.bare" configuration variable
+   can be used to override the heuristic when it misidentifies
+   your repository.
+
+ - git-fetch used to complain updating the current branch but
+   this is now allowed for a bare repository.
+
+ - NEEDSWORK: We should disable Porcelain-ish commands that
+   require a working tree in a bare repository.
+
 
 * Reflog
 
@@ -118,15 +160,42 @@ Updates in v1.5.0 since v1.4.4 series
    versions of git.
 
    Existing repositories that have been using reflog may get
-   complaints from fsck-objects; please run "git reflog expire
-   --all" first to remove reflog entries that refer to commits
-   that are no longer in the repository before attempting to
-   repack it.
+   complaints from fsck-objects and may not be able to run
+   git-repack; please run "git reflog expire --all" first to
+   remove reflog entries that refer to commits that are no
+   longer in the repository when that happens.
 
  - git-branch knows how to rename branches and moves existing
    reflog data from the old branch to the new one.
 
 
+* Detached HEAD
+
+ - You can give non-branch to "git checkout" now.  This will
+   dissociate your HEAD from any of your branches.  A typical
+   use of this feature is to "look around".  E.g.
+
+	$ git checkout v2.6.16
+	... compile, test, etc.
+	$ git checkout v2.6.17
+	... compile, test, etc.
+
+ - After detaching your HEAD, you can go back to an existing
+   branch with usual "git checkout $branch".  Also you can
+   start a new branch using "git checkout -b $newbranch".
+
+ - You can even pull from other repositories, make merges and
+   commits while your HEAD is detached.  Also you can use "git
+   reset" to jump to arbitrary commit.
+
+   Going back to undetached state by "git checkout $branch" can
+   lose the current stat you arrived in these ways, and "git
+   checkout" refuses when the detached HEAD is not pointed by
+   any existing ref (an existing branch, a remote tracking
+   branch or a tag).  This safety can be overriden with "git
+   checout -f".
+
+
 * Packed refs
 
  - Repositories with hundreds of tags have been paying large
@@ -181,6 +250,24 @@ Updates in v1.5.0 since v1.4.4 series
    configuration, in the decreasing order of preference, and
    defaults to UTF-8. 
 
+ - Tools for e-mailed patch application now default to -u
+   behaviour; i.e. it always re-codes from the e-mailed encoding
+   to the encoding specified with i18n.commitencoding.  This
+   unfortunately forces projects that have happily using a
+   legacy encoding without setting i18n.commitencoding, but
+   taken with other improvement, please excuse us for this very
+   minor one-time inconvenience.
+
+
+* Foreign SCM interfaces
+
+  - git-svn now requires the Perl SVN:: libraries, the
+    command-line backend was too slow and limited.
+
+  - the 'commit' subcommand of git-svn has been renamed to
+    'set-tree', and 'dcommit' is the recommended replacement for
+    day-to-day work.
+
 
 * User support
 
@@ -191,4 +278,35 @@ Updates in v1.5.0 since v1.4.4 series
  - Better error messages for often used Porcelainish commands.
 
 
+* Sliding mmap
+
+ - We used to assume that we can mmap the whole packfile while
+   in use, but with a large project this consumes huge virtual
+   memory space and truly huge ones would not fit in the
+   userland address space on 32-bit platforms.  We now mmap huge
+   packfile in pieces to avoid this problem.
+
+
+* Shallow clones
+
+ - There is a partial support for 'shallow' repositories that
+   keeps only recent history now.  A 'shallow clone' is created
+   by specifying how deep that truncated history should be.
+
+   Currently a shallow repository has number of limitations:
+
+   - Cloning and fetching _from_ a shallow clone are not
+     supported (nor tested -- so they might work by accident but
+     they are not expected to).
+
+   - Pushing from nor into a shallow clone are not expected to
+     work.
+
+   - Merging inside a shallow repository would work as long as a
+     merge base is found in the recent history, but otherwise it
+     will be like merging unrelated histories and may result in
+     huge conflicts.
 
+   but this would be more than adequate for people who want to
+   look at near the tip of a big project with a deep history and
+   send patches in e-mail format.

Re: [RFH] An early draft of v1.5.0 release notes

[Eric Wong]

Junio C Hamano <junkio@cox.net> wrote:
> ancient versions such as v1.1.6 or v1.2.0, and there are a
> handful "one-way-street upgrades" and quite a few user visible
> changes that already have happened before v1.4.4.  Namely:

Addendum:

git-svn related changes:

  - git-svn now requires the Perl SVN:: libraries, the
    command-line backend was too slow and limited.

  - the 'commit' command has been renamed to 'set-tree', and
    'dcommit' is the recommended replacement for day-to-day
    work.

-- 
Eric Wong

Re: [RFH] An early draft of v1.5.0 release notes

[Junio C Hamano]

Eric Wong <normalperson@yhbt.net> writes:

> Addendum:
>
> git-svn related changes:

Thanks.

[PATCH] commit: Steer new users toward "git commit -a" rather than update-index

[Carl Worth]

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

As has been discussed recently, update-index isn't intended as a
"porcelain" command so the mention of it in the output of git-commit
does lead to some user confusion.
---
 wt-status.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/wt-status.c b/wt-status.c
index 7dd6857..4edabcd 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -126,7 +126,7 @@ static void wt_status_print_changed_cb(s
 	int i;
 	if (q->nr)
 		wt_status_print_header("Changed but not updated",
-				"use git-update-index to mark for commit");
+				"use \"git commit <files>\" to commit or \"git commit -a\" for all");
 	for (i = 0; i < q->nr; i++)
 		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
 	if (q->nr)
--
1.4.3.3.gf040


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

Re: [PATCH] commit: Steer new users toward "git commit -a" rather than update-index

[Andy Whitcroft]

Carl Worth wrote:
> As has been discussed recently, update-index isn't intended as a
> "porcelain" command so the mention of it in the output of git-commit
> does lead to some user confusion.
> ---
>  wt-status.c |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 7dd6857..4edabcd 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -126,7 +126,7 @@ static void wt_status_print_changed_cb(s
>  	int i;
>  	if (q->nr)
>  		wt_status_print_header("Changed but not updated",
> -				"use git-update-index to mark for commit");
> +				"use \"git commit <files>\" to commit or \"git commit -a\" for all");
>  	for (i = 0; i < q->nr; i++)
>  		wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
>  	if (q->nr)
> --
> 1.4.3.3.gf040

Are we sure this isn't porcelain-ish?  We need to use it in merge
conflict correction and the like?  You can't use git-commit there as a
replacement.  I'd expect it to be 'git update-index' rather than
'git-update-index' of course.

Cleaning up git user-interface warts

[Carl Worth]

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

On Tue, 14 Nov 2006 18:55:51 +0000, Andy Whitcroft wrote:
> Carl Worth wrote:
> > As has been discussed recently, update-index isn't intended as a
> > "porcelain" command so the mention of it in the output of git-commit
> > does lead to some user confusion.
>
> Are we sure this isn't porcelain-ish?  We need to use it in merge
> conflict correction and the like?  You can't use git-commit there as a
> replacement.  I'd expect it to be 'git update-index' rather than
> 'git-update-index' of course.

It was Junio that recently said update-index is plumbing, not
porcelain.

So, the fact that conflict resolution still requires the use of
update-index would just be the next thing to fix. A name for a
replacement to use there could be "git resolve <paths>", (since the
old git-resolve is now officially deprecated). That's a name that
matches what hg uses in this situation, (another option is "resolved"
which is what stg uses, but I think verbs for commands work better in
general).

It would be really nice if none of the "common" commands had a hyphen
in them, for example.

And then, the next phase of my evil plan would be to introduce a -i
option for git-commit making it commit the state in the index. Then
git-commit with no options could work like "git-commit -a" does now,
(with the additional protection of not committing any unmerged
files---that is the new "git resolve" would be required before "git
commit" would work after a conflict). Users who really, really like
the current behavior of git-commit could use the new alias support to
pass the new -i option in order to maintain compatible behavior.

Then, the last thing I'd really like to fix is to allow a usage of
"git merge <branch>" instead of the awkward "git pull . <branch>".

With that, most of the user-interface warts that I regularly run into
with git would be solved. Oh, except it would also be nice to
eliminate the "plumbing" commands in a couple of places:

 1) From the "man git" man page

 2) From git-<TAB>, (maybe the solution for this is to make
    "git <TAB>" work and only do tab-completion for the commands
    blessed enough to appear in "git --help"? Also push the tab
    completion stuff out as a standard part of packages.

Anyway, now I've just gone and blown all my secret plans for changing
git in ways to make it less intimidating for new users.

For reference, the latest potential batch of new users that I'm
dealing with is the set of Fedora package maintainers who are looking
at replacing CVS for their tree of package-building scripts. They are
currently evaluating systems and liking the interface of hg. Here's
the top of the current thread:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00030.html

Here's the report about "git commit -a" confusion that led to my patch
above:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00141.html

And here's my reply where I suggest that git UI might still be
improved in these areas:

https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00149.html

-Carl

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

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
>  2) From git-<TAB>, (maybe the solution for this is to make
>     "git <TAB>" work and only do tab-completion for the commands
>     blessed enough to appear in "git --help"? Also push the tab
>     completion stuff out as a standard part of packages.

Uh, see contrib/completion/git-completion.bash.

"git <TAB>" completes commands.  It offers too many completions
for your taste it sounds like, as it also offers plumbing... but
that's fixable.  :-)

-- 

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Tue, 14 Nov 2006 14:29:14 -0500, Shawn Pearce wrote:
> Uh, see contrib/completion/git-completion.bash.

Oops. I had seen this and thought I had installed it properly a while
ago, (copied it to /etc/bash_completion.d/git), but I hadn't realized
it wasn't active in the shell I used to test while composing that
email.

> "git <TAB>" completes commands.  It offers too many completions
> for your taste it sounds like, as it also offers plumbing... but
> that's fixable.  :-)

Yes, I think we'd all be better off if we could designate some subset
of the current git commands as not being intended for users to type on
the command line and pulled them out of the completion scripts.

It is tough though. Looking through what's available in the short list
from "git --help" I notice that update-index isn't there, and that's
currently still required, (as we've been discussing here). But even
things as "core plumbing" as git rev-list I find extremely useful on
the command like with simple pipelines.

On the other hand, there are definitely some commands I've never
typed, and are not intended to be typed by the user. Here are a few I
see as fairly obvious just from skimming the list:

	merge-*
	http-*
	ssh-*
	upload-*
	mktag
	mktree
	check-ref-format
	...

There are a bunch of others as well. Maybe it would be easier to start
with the list in git --help and see what should be added to that.

The documentation for some of the above commands have phrases such as
"Invoked by <other command>" and "usually not invoked by the end user"
which does make the distinction quite clear. So it would be nice if
git could keep these away from the user more.

-Carl

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

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Tue, Nov 14, 2006 at 08:22:39PM CET, Carl Worth wrote:
> For reference, the latest potential batch of new users that I'm
> dealing with is the set of Fedora package maintainers who are looking
> at replacing CVS for their tree of package-building scripts. They are
> currently evaluating systems and liking the interface of hg. Here's
> the top of the current thread:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00030.html
> 
> Here's the report about "git commit -a" confusion that led to my patch
> above:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00141.html
> 
> And here's my reply where I suggest that git UI might still be
> improved in these areas:
> 
> https://www.redhat.com/archives/fedora-maintainers/2006-November/msg00149.html

Hmm, did they (not) consider Cogito? They wouldn't have those issues.
;-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
> Hmm, did they (not) consider Cogito? They wouldn't have those issues.

I didn't ask.

Frankly, I don't see a lot of value in the git/cogito split right now.

When I first learned git and cogito (January 2006) and switched cairo
from cvs to git (the repository storage), I recommended cogito to
cairo programmers as a "more cvs-like" way to work with the new
repository.

Since then, having worked with git (the command-line program)
exclusively for my own work, and having introduced it to dozens of new
users, I don't bother recommending cogito anymore. It's just not that
hard to learn git itself, so there's not that much value in learning
cogito instead.

And this is particularly true since there's quite a large cost to
having to learn cogito _in addition to_ git. And I think that's what
most people would have to do anyway. For example, cogito doesn't wrap
all git commands. So users have to dip down into git for things like
git-bisect or else miss out an important functionality.

And for something like the Fedora transition, where I'm working with
the people who will be training the community in the new tools, the
trainers would have to learn both if they want to support a community
using both git and cogito. These trainers are already complaining
about the ~140 git commands, so adding 40 more cogito commands as well
doesn't make the story better.

It's great that git is written in a script-friendly way so that new
interfaces can be built on top of it. And I think the benefits of new
user interfaces are clear when they work in fundamentally different
ways, (say, being operated through a GUI). But where git and cogito
are both command-line utilities and have the same basic functionality,
I don't see how its helpful to maintain both tools. (Certainly some of
my attitude here is due to the timing of my introduction to git
contrasted with the timing of the inception of cogito. I'm sure git
improved a lot between those two events.)

There are some things that cogito does that git does not that I would
like to have in git. One is having a "commit" command that commits
everything by default without an extra command-line option. Another
(that I _think_ cogito has) is a way to switch away from a branch with
dirty changes to a clean branch, do work there, and come back to the
original branch with the dirty stuff still there.

I don't see any defining difference that justifies cogito's
existence ("hide the index" maybe? let's just hide it a tiny bit more
in git). And I would like to help work to get the remaining good
stuff that has been proven in cogito---to get it pushed down into git
itself.

-Carl

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

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
>> Hmm, did they (not) consider Cogito? They wouldn't have those issues.
>
> I didn't ask.
>
> Frankly, I don't see a lot of value in the git/cogito split right now.
> ...
> It's great that git is written in a script-friendly way so that new
> interfaces can be built on top of it. And I think the benefits of new
> user interfaces are clear when they work in fundamentally different
> ways, (say, being operated through a GUI). But where git and cogito
> are both command-line utilities and have the same basic functionality,
> ...
> There are some things that cogito does that git does not that I would
> like to have in git.
> ...
> I don't see any defining difference that justifies cogito's
> existence ("hide the index" maybe? let's just hide it a tiny bit more
> in git). And I would like to help work to get the remaining good
> stuff that has been proven in cogito---to get it pushed down into git
> itself.

I am of two minds here.

I do not think the Porcelain-ish UI that is shipped with git
should be taken with the same degree of "authority" as git
Plumbing.  The plumbing needed to have something that worked for
one particular workflow (namely, workflow of the people in the
integrator role of kernel-style project) and that is where the
current set of Porcelain-ish originates.  Linus works primarily
as an integrator so the toolsets he did tend to be more pleasant
to use for integrators and less so for contributors.  I started
as a contributor and added some commands like format-patch and
rebase that Linus never would have felt the need for.  I think
single isolated developers, contributors and CVS style shared
repository usage could be a lot improved because neither of us
were concentrating in their workflows.  This needs somebody
motivated enough to improve things in that area.  For example,
StGIT with its 'float' command is a great improvement over what
rebase does for people in the contributor role.

By now, perhaps git may be good enough for the kernel folks,
even for those not in the integrator role, but I have no doubt
that they have many dislikes to the way some commands work.
They and X.org folks are using git primarily because Linus and
Keith forced them to ;-), and being interoperable is more
important than having to tolerate sucky UI here and there.
Everybody knows that git Porcelain-ish sucks, and making it more
usable is a worthy goal.

But making it more usable for whom is a big question.  

Quite frankly, I do not think there can be _the_ single UI that
would satisfy different types of workflows for some of the
commands.  The commands related to software archaeology, in
which my main interest and strength lie, would easily be usable
across workflows, but commands to build commits locally and
propagate them to and from other repositories would be affected
by the workflow.

For example, fetching and merging from many places without
necessarily having corresponding tracking branches is a great
thing for people in the integrator role.  On the other hand, for
people doing CVS-style centralized repository interaction, it is
often more useful to have tracking branches.  You could support
both but it has been painful.

For another example, having a commit command to commit
everything by default is disastrous for people who allow their
workflows to often be interrupted.  When I respond to a message
from the list with an example patch, my repository is often in
the middle of doing something completely unrelated, and I edit
and make diff to send the message out and I do not necessarily
revert that change afterwards immediately.  For more organized
people it may not be a problem so you either support both types
of workflows or do a specialized toolset.

It is not just command line syntax and the defaults, but
concepts as well.  People in the integrator role often need to
deal with merges and you would need to be aware of the role of
the index and need to be able to manipulate the index, a lot
more often than people in the contributor role.  To satisify
both kinds of workflows, you would either have switches, or do a
specialized toolset, like Cogito, that tries to hide the index.

A Porcelain that does a very similar thing in slightly different
way is obviously a waste, but otherwise I do not think it is a
problem to have different Porcelains.  StGIT does not compete
with the "sucky" Porcelain-ish shipped with git but makes the
user's life a lot more pleasant by complementing what the sucky
one does not do well.  It is not very useful while I am playing
the integrator role, but when I am doing my own thing it is a
great addition to my toolchest.

I am from the camp that does _not_ want to hide the index, so
obviously I do not see any value in its effort to hide the
index.  But other aspects of it, most notably being friendly to
simpler workflows, is a very good thing.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 01:31:50AM CET, Junio C Hamano wrote:
> Carl Worth <cworth@cworth.org> writes:
> 
> > On Tue, 14 Nov 2006 20:47:07 +0100, Petr Baudis wrote:
> >> Hmm, did they (not) consider Cogito? They wouldn't have those issues.
> >
> > I didn't ask.
> >
> > Frankly, I don't see a lot of value in the git/cogito split right now.
> > ...
> > It's great that git is written in a script-friendly way so that new
> > interfaces can be built on top of it. And I think the benefits of new
> > user interfaces are clear when they work in fundamentally different
> > ways, (say, being operated through a GUI). But where git and cogito
> > are both command-line utilities and have the same basic functionality,
> > ...
> > There are some things that cogito does that git does not that I would
> > like to have in git.
> > ...
> > I don't see any defining difference that justifies cogito's
> > existence ("hide the index" maybe? let's just hide it a tiny bit more
> > in git). And I would like to help work to get the remaining good
> > stuff that has been proven in cogito---to get it pushed down into git
> > itself.
> 
> I am of two minds here.
> 
> I do not think the Porcelain-ish UI that is shipped with git
> should be taken with the same degree of "authority" as git
> Plumbing.
..snip passage about workflows..

Controversy's fun, so...

<Cogito maintainer hat _off_> (But yeah, it still looks silly that I'm
saying this.)

 From the current perspective, I think it has been a mistake that the
porcelain and plumbing was not kept separate in independent packages,
and perhaps even maintained separately (and perhaps not; at least having
a single tree with plumbing/ and porcelain/ directories and separate
packages in distributions might already help something), so that "git"
would be kept as a kind of library and then there would be a separate
package providing an interface to it. Or you could select one of several
packages. Not only would that make Cogito prevail in the world and bring
me a flood of marriage proposals, but look at how would it help the
general public:

  (i) Clearly divided porcelain/plumbing interface, so that you can
really isolate the two UI-wise; endless confusion reigns there now. Is
git-update-index porcelain or plumbing? _You_ call git-merge a proper
porcelain? From my perspective, git-update-ref is as plumbing as it
gets, but it's classified as porcelain. Etc, etc. This would be by far
the most important advantage.

  (ii) The plumbing and porcelain would not share the same namespace,
leading to clearer UI. (I'm just inflating (i).)

  (iii) The documentation would not be a strange mix of porcelain and
plumbing. (More (i) inflation.)

  (iv) (i) is troublesome because I have a feeling that Junio declared
several times that he doesn't care that much about stable API for
porcelain compared to the plumbing. But with the current mix it's
desirable to use some porcelain even in other porcelains and in scripts.

  (v) Git would be properly libified by now. If you wanted to convert
bits of porcelain to C, it would be at least much higher priority.

  (vi) You wouldn't need to make the gruesome choice on what is the
canonical workflow the _the_ Git porcelain supports (see the snipped
passage). Or you would, but it would have less impact.

  (vii) The world would be a happier place.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> On Wed, Nov 15, 2006 at 01:31:50AM CET, Junio C Hamano wrote:
>> 
>> I am of two minds here.
>> 
>> I do not think the Porcelain-ish UI that is shipped with git
>> should be taken with the same degree of "authority" as git
>> Plumbing.
> ..snip passage about workflows..
>
> Controversy's fun, so...
>
> <Cogito maintainer hat _off_> (But yeah, it still looks silly that I'm
> saying this.)

It appears that you are not grumpy as you were anymore ;-).  I
mostly agree with what you said in your message.

> (i) Clearly divided porcelain/plumbing interface, so that you can
> really isolate the two UI-wise; endless confusion reigns there now. Is
> git-update-index porcelain or plumbing? _You_ call git-merge a proper
> porcelain? From my perspective, git-update-ref is as plumbing as it
> gets, but it's classified as porcelain. Etc, etc. This would be by far
> the most important advantage.

Yes.  The current "merge" started its life as Linus's porcelain
(we did not have fetch and pull infrastructure back then) but
quickly has become just a helper for pull to produce a merge
commit.  If anybody thinks its UI is good as a general end-user
level command, there is a need for "head examination".

As you say, update-ref is as plumbing as it gets and it should
not be listed as Porcelain; I am a bit surprised that it is
labelled as such myself.

No disagreement here, nor (ii) nor (iii).

>   (ii) The plumbing and porcelain would not share the same namespace,
> leading to clearer UI. (I'm just inflating (i).)
>
>   (iii) The documentation would not be a strange mix of porcelain and
> plumbing. (More (i) inflation.)
>
>   (iv) (i) is troublesome because I have a feeling that Junio declared
> several times that he doesn't care that much about stable API for
> porcelain compared to the plumbing. But with the current mix it's
> desirable to use some porcelain even in other porcelains and in scripts.

This is true and it is a problem.

While we encourage Porcelain writers to use plumbing in order to
give git Porcelain-ish more freedom to evolve to give better UI
for humans, not having a clear distinction between the two makes
it harder.

>   (v) Git would be properly libified by now. If you wanted to convert
> bits of porcelain to C, it would be at least much higher priority.

I am not sure about "libified" part and I do not know what bits
of porcelain wants to become C right now.  But I do not think
this point is important part of your list.

>   (vi) You wouldn't need to make the gruesome choice on what is the
> canonical workflow the _the_ Git porcelain supports (see the snipped
> passage). Or you would, but it would have less impact.

Yes.  This is really important.

Linus and me having done Porcelain-ish that supports integrator
role workflow better than other workflows such as contributor
role should not discourage people from working on alternative or
complementary Porcelains to help other workflows better (see the
snipped passage).

StGIT sets a great example, and efforts like it is encoraged
more.

I think both Linus and myself tried to make it clear that the
purpose of Porcelain-ish that comes with core git is 50% to make
plumbing (perhaps minimally) usable and the other 50% to serve
as an example for Porcelain writers to learn how to use the
plumbing, but we should probably have stressed the latter
better.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Yes.  The current "merge" started its life as Linus's porcelain
> (we did not have fetch and pull infrastructure back then) but
> quickly has become just a helper for pull to produce a merge
> commit.  If anybody thinks its UI is good as a general end-user
> level command, there is a need for "head examination".

If you mean "git merge" it sure needs to be brought forward.  It can't 
be clearer than:

	git-merge the_other_branch

or

	git-merge git://repo.com/time_machine.git

to instantaneously understand what is going on.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:

> On Tue, 14 Nov 2006, Junio C Hamano wrote:
> 
>> Yes.  The current "merge" started its life as Linus's porcelain
>> (we did not have fetch and pull infrastructure back then) but
>> quickly has become just a helper for pull to produce a merge
>> commit.  If anybody thinks its UI is good as a general end-user
>> level command, there is a need for "head examination".
> 
> If you mean "git merge" it sure needs to be brought forward.  It can't 
> be clearer than:
> 
>       git-merge the_other_branch
> 
> or
> 
>       git-merge git://repo.com/time_machine.git
> 
> to instantaneously understand what is going on.

You mean

      git merge git://repo.com/time_machine.git#branch

don't you (perhaps with 'master' as default branch)?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Santi Béjar]

On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:
> Nicolas Pitre wrote:
>
> > On Tue, 14 Nov 2006, Junio C Hamano wrote:
> >
> >> Yes.  The current "merge" started its life as Linus's porcelain
> >> (we did not have fetch and pull infrastructure back then) but
> >> quickly has become just a helper for pull to produce a merge
> >> commit.  If anybody thinks its UI is good as a general end-user
> >> level command, there is a need for "head examination".
> >
> > If you mean "git merge" it sure needs to be brought forward.  It can't
> > be clearer than:
> >
> >       git-merge the_other_branch
> >
> > or
> >
> >       git-merge git://repo.com/time_machine.git
> >
> > to instantaneously understand what is going on.
>
> You mean
>
>       git merge git://repo.com/time_machine.git#branch
>
> don't you (perhaps with 'master' as default branch)?

perhaps with remote 'HEAD' as default branch?

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Santi Béjar wrote:

> On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:

>> You mean
>>
>>       git merge git://repo.com/time_machine.git#branch
>>
>> don't you (perhaps with 'master' as default branch)?
> 
> perhaps with remote 'HEAD' as default branch?

No! HEAD might change without your notice, and you want to know
which branch you merge. With remotes the default could be first
branch in the pull/fetch list, but with bare URL...
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:28:27AM CET, Jakub Narebski wrote:
> Santi Béjar wrote:
> 
> > On 11/15/06, Jakub Narebski <jnareb@gmail.com> wrote:
> 
> >> You mean
> >>
> >>       git merge git://repo.com/time_machine.git#branch
> >>
> >> don't you (perhaps with 'master' as default branch)?
> > 
> > perhaps with remote 'HEAD' as default branch?
> 
> No! HEAD might change without your notice, and you want to know
> which branch you merge. With remotes the default could be first
> branch in the pull/fetch list, but with bare URL...

No! If HEAD changed without your notice, it means that the remote
repository admin _wants_ you to start fetching another branch now.
Imagine a setup of these branches:

	phooey-1.2	legacy lineage
	phooey-2.0	last stable
	phooey-3.0	current development (no releases yet)
	phooey-4.0	stash for futuristic functionality, heavily
			experimental

In this case, HEAD now points to phooey-3.0 but when it becomes stable,
it would change to phooey-4.0.

The common practice of having 'master' pointing on whatever you
currently have now and and "cutting out" the branches from it at random
times is something heavily influenced by CVS where this is the only sane
way of branching (the cutting out even hardcoded in numbering scheme).
In more advanced systems, you may want to be much more flexible wrt. this
(note that I'm not saying you necessarily _should_ be).

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> 
> > On Tue, 14 Nov 2006, Junio C Hamano wrote:
> > 
> >> Yes.  The current "merge" started its life as Linus's porcelain
> >> (we did not have fetch and pull infrastructure back then) but
> >> quickly has become just a helper for pull to produce a merge
> >> commit.  If anybody thinks its UI is good as a general end-user
> >> level command, there is a need for "head examination".
> > 
> > If you mean "git merge" it sure needs to be brought forward.  It can't 
> > be clearer than:
> > 
> >       git-merge the_other_branch
> > 
> > or
> > 
> >       git-merge git://repo.com/time_machine.git
> > 
> > to instantaneously understand what is going on.
> 
> You mean
> 
>       git merge git://repo.com/time_machine.git#branch
> 
> don't you (perhaps with 'master' as default branch)?

Something like that.  I wantee to enphasize on the "merge" command that 
should deal with, hey, merges.

I don't know if # is a good choice for branch indicator though.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 05:33:03AM CET, Junio C Hamano wrote:
> Petr Baudis <pasky@suse.cz> writes:
> >   (v) Git would be properly libified by now. If you wanted to convert
> > bits of porcelain to C, it would be at least much higher priority.
> 
> I am not sure about "libified" part and I do not know what bits
> of porcelain wants to become C right now.  But I do not think
> this point is important part of your list.

Merge strategies. Or wait, is that already plumbing?

Or git-status. git-add. Plenty more.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Petr Baudis wrote:

>   (i) Clearly divided porcelain/plumbing interface, so that you can
> really isolate the two UI-wise; endless confusion reigns there now. Is
> git-update-index porcelain or plumbing? _You_ call git-merge a proper
> porcelain? From my perspective, git-update-ref is as plumbing as it
> gets, but it's classified as porcelain. Etc, etc. This would be by far
> the most important advantage.

The problem is that one man's plumbing is another man porcelain.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 11:05:26 +0100, Jakub Narebski wrote:

> The problem is that one man's plumbing is another man porcelain.

No; that way lies insanitation.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
> I do not think the Porcelain-ish UI that is shipped with git
> should be taken with the same degree of "authority" as git
> Plumbing.

I think we should fix this. "This is great technology with a crap
interface on top" really isn't a good story. I don't actually agree
with that---I don't think the git interface is really all that bad,
it's just got a few little things that tend to trip up new users in my
experience.

And what git does really well, (history exploring, allowing for
pipeline on-liners to iterate over revisions in A..B), are things that
don't even exist in other tools, nor even in the "alternate"
porcelains for git. This stuff is where git's interface is really
fantastic, and it would be a shame to write it off.

>                                                        I think
> single isolated developers, contributors and CVS style shared
> repository usage could be a lot improved because neither of us
> were concentrating in their workflows.  This needs somebody
> motivated enough to improve things in that area.  For example,
> StGIT with its 'float' command is a great improvement over what
> rebase does for people in the contributor role.

Yes, there are some specific workflow-oriented operations that git
doesn't handle as well as it could. Things like commit --amend are
certainly improvements. One that is still totally broken is "follow
all the development in another repository" where clone followed by
repeated fetch doesn't do the job as soon as the remote adds or
deletes a branch.

> But making it more usable for whom is a big question.
>
> Quite frankly, I do not think there can be _the_ single UI that
> would satisfy different types of workflows for some of the
> commands.

I strongly disagree. Or at least, I don't think we've tried hard
enough yet that we should give up on this.

I do agree that people in different roles will have different lists of
"most used operations" and that some operations won't appear on some
users lists at all, (someone who's just "watching" development won't
commit or merge, for example---[or so they thing when they start]).

But I really don't think that for any given operation that different
roles impose a different desire on the behavior of the operation. We
have different people with different background and disagreement on
names and silly things like that, but I don't think that's related to
the roles in which they are working with the tool.

> For example, fetching and merging from many places without
> necessarily having corresponding tracking branches is a great
...

I don't think we've ever had this right in git. The new
--use-separate-remotes stuff or similar will start to help as it
becomes the default. I don't see how this won't benefit everybody.

> For another example, having a commit command to commit
> everything by default is disastrous for people who allow their
> workflows to often be interrupted.

Workflow-interruption is an important thing to support, but separating
update-index and commit really doesn't address it nearly as much as I
would like. The lack of really good workflow-interruption support has
been one of my longest-running annoyances with git, (perhaps because I
have a problem with trying to do too many things at once). Git can
create and change branches fast enough that it really should be able
to help me better with this. The only missing piece is being able to
stash the dirty stuff on the current branch, to be able to come back
to it later. I've talked a bit about what I would like in this area
before, and I really just need to code it up.

> It is not just command line syntax and the defaults, but
> concepts as well.  People in the integrator role often need to
> deal with merges and you would need to be aware of the role of
> the index and need to be able to manipulate the index, ...

Again, I think it's more that the specific operations bring in
concepts, (merge bringing in the index here). As such, someone never
doing a merge could easily get by not having to understand the index.

> A Porcelain that does a very similar thing in slightly different
> way is obviously a waste, but otherwise I do not think it is a
> problem to have different Porcelains.  StGIT does not compete
> with the "sucky" Porcelain-ish shipped with git but makes the
> user's life a lot more pleasant by complementing what the sucky
> one does not do well.  It is not very useful while I am playing
> the integrator role, but when I am doing my own thing it is a
> great addition to my toolchest.

But even here, there's a bunch of waste in StGit. For example, there
are a lot of commands in StGit whose only purpose is to translate back
and forth between the StGit and non-StGit views of the world, (init,
assimilate, commit, uncommit). Those could all be discarded if the
functionality of StGit were brought down into git itself. Then there
are a myriad of StGit commands which are basically just the same as
their git counterparts.

Now, StGit is a great tool, and I know that it works really well for
some people in the role of just maintaining a stack of changes against
some upstream, and can use StGit alone and never touch "git" the
command-line.

But for someone like me who already uses git regularly, and
occasionally just wants to pop back a few commits, amend it, and then
push again, StGit is not helpful, (the series of init, assimilate, and
uncommits just to get started is prohibitive compared to just working
out the awkward steps needed to make a temporary branch and
rebase). So I'd love to see just a couple of commands added to "git"
to support these kinds of operations more smoothly.

> I am from the camp that does _not_ want to hide the index, so
> obviously I do not see any value in its effort to hide the
> index.  But other aspects of it, most notably being friendly to
> simpler workflows, is a very good thing.

I don't think "hide or not-to-hide" is the right way to frame the
discussion about the index. I regularly use update-index to stage
partial commits, and I find that very useful. And obviously the index
is involved in resolving merge conflicts.

But I don't think the user-interface for either of those operations
(partial commit, resolve conflicts), is ideal, and the current
requirement to use either "update-index <paths>" or "commit -a" after
modifying a file for the first time is demonstrably a hangup for a lot
of new users. So I really think it's possible to address both of these
at once.

Anyone, that's enough generic rambling from me without any specific
content. I'll try to keep future messages focused on specific
desirable operations that have problematic interfaces in git right
now, along with proposals for improving them.

-Carl

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

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Carl Worth wrote:
>On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
>>
>> For another example, having a commit command to commit
>> everything by default is disastrous for people who allow their
>> workflows to often be interrupted.
> 
> Workflow-interruption is an important thing to support, but separating
> update-index and commit really doesn't address it nearly as much as I
> would like. The lack of really good workflow-interruption support has
> been one of my longest-running annoyances with git, (perhaps because I
> have a problem with trying to do too many things at once). Git can
> create and change branches fast enough that it really should be able
> to help me better with this. The only missing piece is being able to
> stash the dirty stuff on the current branch, to be able to come back
> to it later. I've talked a bit about what I would like in this area
> before, and I really just need to code it up.

There is git-stash/git-unstash floating somewhere in the archive.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Jakub Narebski <jnareb@gmail.com> wrote:
> Carl Worth wrote:
> >On Tue, 14 Nov 2006 16:31:50 -0800, Junio C Hamano wrote:
> >>
> >> For another example, having a commit command to commit
> >> everything by default is disastrous for people who allow their
> >> workflows to often be interrupted.
> > 
> > Workflow-interruption is an important thing to support, but separating
> > update-index and commit really doesn't address it nearly as much as I
> > would like. The lack of really good workflow-interruption support has
> > been one of my longest-running annoyances with git, (perhaps because I
> > have a problem with trying to do too many things at once). Git can
> > create and change branches fast enough that it really should be able
> > to help me better with this. The only missing piece is being able to
> > stash the dirty stuff on the current branch, to be able to come back
> > to it later. I've talked a bit about what I would like in this area
> > before, and I really just need to code it up.
> 
> There is git-stash/git-unstash floating somewhere in the archive.

I find that a "git commit -a -m parked; git checkout -b ..." works
well to stash my current stuff off.  Then I just amend the commit
when I come back to that branch.


The problem I just ran into today was "git checkout" doesn't double
check the file stat data against the index before switching branches.
If the file is unchanged between the two branches there's no error.
So I switched branches with dirty files that I forgot to park on
the old branch.

-- 

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 17:00:54 -0500, Shawn Pearce wrote:
> > There is git-stash/git-unstash floating somewhere in the archive.

Yes, I did write those once upon a time. ;-)

It's the manual stash/unstash that I don't want though. I want to be
able to make this happen automatically when switching branches.

> I find that a "git commit -a -m parked; git checkout -b ..." works
> well to stash my current stuff off.  Then I just amend the commit
> when I come back to that branch.

Yes, I do stuff like that as well. And often "reset HEAD~" instead of
amend, (always with a moment's pause as reset justly deserves).

> The problem I just ran into today was "git checkout" doesn't double
> check the file stat data against the index before switching branches.
> If the file is unchanged between the two branches there's no error.
> So I switched branches with dirty files that I forgot to park on
> the old branch.

Right, so that's just more evidence that this approach is a little
awkward.

Anyway, the stashing thing I want is a minor thing that should be easy
to fix in git, (as is everything we're talking about here I think).

-Carl

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

Re: Cleaning up git user-interface warts

[Steven Grimm]

Jumping into this a day late, but:

Carl Worth wrote:
> I don't see any defining difference that justifies cogito's
> existence ("hide the index" maybe? let's just hide it a tiny bit more
> in git). And I would like to help work to get the remaining good
> stuff that has been proven in cogito---to get it pushed down into git
> itself.
>   

Agreed totally on the second point. It would be great if git natively 
supported everything people use in Cogito.

I find myself using native git commands for the most part, except for 
one Cogito command: "cg-update". It is vastly more convenient than 
git-pull in large part because it automatically merges upstream changes 
with uncommitted working-copy changes. I suppose you could classify this 
as "hide the index" in some sense.

Maybe I should give an example of what I mean. Suppose I have two child 
repositories (owned by different developers, say):

cg-clone repo child1
cg-clone repo child2

Now I go into both of them and make different (hopefull non-conflicting) 
edits to the same file.

echo foo >> child1/testfile
perl -pi -e 's/tree/shrub/' child2/testfile

I push the change from child1 into the integration repo.

cd child1
git-commit -a
git-push

Now I want to incorporate the change into child2, where I'm still doing 
work. With Cogito, I go to child2 and run:

cg-update

and afterwards, the upstream changes are merged into testfile and "git 
diff" still shows my local edits. With Git native commands, updating 
child2 if I'm not ready to commit yet is more like:

git-diff --binary > /tmp/patch
git-reset --hard
git-pull
git-apply /tmp/patch

I might have gotten that slightly wrong, but I think I have the general 
idea right; in any event, it's not nearly as convenient! The alternative 
is to commit then pull, but then when I want to look at my local edits, 
I have to remember to diff my working copy against the correct revision, 
which gets increasingly annoying if I update more than once.

Like others on this list, I'm also trying to sell an existing user base 
(in this case, they're using Subversion) on Git. The lack of a built-in 
equivalent to "svn update" is actually a pretty big UI annoyance for 
people whose workflow doesn't require git's more sophisticated feature 
set at a given point in time. Even a sophisticated user doesn't need the 
full power of the tool 100% of the time, so this isn't just a novice vs. 
expert thing in my opinion.

Absent Cogito, would the lack of a simple "svn update" equivalent be a 
deal-killing "throw your hands up in disgust and give up" thing? Maybe 
not, but it's a daily "ugh, why am I having to type extra commands to do 
something that only took one command in svn?" thing. So it's nice to 
have Cogito to paper over that particular wart.

If there is a native git equivalent to cg-update including the 
working-copy automatic merges, I'll be delighted to stand corrected!

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Steven Grimm <koreth@midwinter.com> writes:

> echo foo >> child1/testfile
> perl -pi -e 's/tree/shrub/' child2/testfile
>...
> git-diff --binary > /tmp/patch
> git-reset --hard
> git-pull
> git-apply /tmp/patch
>
> I might have gotten that slightly wrong, but I think I have the
> general idea right.

stg pull would help you in such a situation as well, but I see
what you mean.

Just like we have an explicit -m option to "checkout" to allow
file-level merging of local changes, I think it is reasonable to
hav an option that allows file-level merging of local changes
when doing a pull that you _know_ will not conflict.

When there will be a conflict between your HEAD and MERGE_HEAD
even without your local changes, you somehow need to sort out
the resulting mess that come from conflicts due to the branch
diversion (i.e. log HEAD...MERGE_HEAD) and conflicts between
your local change and what the other branch did.  The resulting
merge commit obviously needs to record resolutions only to the
former and should not even record anything you did locally,
conflicted or not.  Which is a pain for the end user and giving
them a way to revert to the state before this three-and-half
way merge started also needs to be there.

Unfortunately the only way to know if there will be a file-level
conflict is to try one, and stashing away the current state just
in case it conflicted is a performance penalty, so this probably
should stay as an option just like "-m" to the "checkout".

But the basic mechanism to do this three-and-half way merge is
simple and I have no objection if somebody wanted to add such an
option to "git pull".

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Fri, Nov 17, 2006 at 10:35:04PM CET, Junio C Hamano wrote:
> Unfortunately the only way to know if there will be a file-level
> conflict is to try one, and stashing away the current state just
> in case it conflicted is a performance penalty, so this probably
> should stay as an option just like "-m" to the "checkout".

I think it would be just great if it worked at least for fast-forwarding
case; I think this is where it is actually most useful. Cogito tries to
support even the three-way case as long as the changes touch different
files, but I'm not sure if it was a good idea to begin with.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-14 11:22:39 -0800, Carl Worth wrote:

> So, the fact that conflict resolution still requires the use of
> update-index would just be the next thing to fix. A name for a
> replacement to use there could be "git resolve <paths>", (since the
> old git-resolve is now officially deprecated). That's a name that
> matches what hg uses in this situation, (another option is
> "resolved" which is what stg uses, but I think verbs for commands
> work better in general).

Yes, "resolve" sounds better than "resolved". The latter is arguably
more correct, since you're telling git that you have already resolved
the file and not asking it to resolve it for you, but I still prefer
"resolve".

> And then, the next phase of my evil plan would be to introduce a -i
> option for git-commit making it commit the state in the index. Then
> git-commit with no options could work like "git-commit -a" does now,
> (with the additional protection of not committing any unmerged
> files---that is the new "git resolve" would be required before "git
> commit" would work after a conflict). Users who really, really like
> the current behavior of git-commit could use the new alias support
> to pass the new -i option in order to maintain compatible behavior.

Seems very sane. Default to simple behavior, and provide a switch to
get more complicated behavior.

> Then, the last thing I'd really like to fix is to allow a usage of
> "git merge <branch>" instead of the awkward "git pull . <branch>".

This should reduce newbie confusion a lot.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Carl Worth wrote:

> Anyway, now I've just gone and blown all my secret plans for changing
> git in ways to make it less intimidating for new users.

I just cannot do otherwise than cheer this with applause.

Even if I have a clear preference for GIT's _technology_, I still think 
that the HG user interface is more convivial.  I even been thinking 
about writing something like an hg-like frontend to GIT from time to 
time just so that GIT could then be better compared to (and actually 
just used like) HG.

I still think that the GIT user interface sucks in many ways.  The 
confusion between pull, fetch and push is still my favorite, along with 
the locale vs remote branch issue.  Maybe we'll better handle the branch 
issue eventually, but it would be so much intuitive to split branch 
merging out of git-pull, and make git-pull be the same as git-fetch 
(maybe deprecating git-fetch in the process) so push and pull are really 
_only_ opposite of each other.

If the fetch+merge behavior (which I think should really be refered as 
pull+merge) is still desirable, then it should be called git-update and 
be no more than a single shell script line such as

	git_pull && git_merge"

This is really what most people expect from such a command name based 
on obvious historical reasons.  The lack of any branch argument to 
git-pull and git-merge could be defined as using the first defined 
remote branch by default.  But having git-pull performing merges is IMHO 
overloading the word and goes against most people's expectations.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:

> If the fetch+merge behavior (which I think should really be refered as 
> pull+merge) is still desirable, then it should be called git-update and 
> be no more than a single shell script line such as
> 
>         git_pull && git_merge"
> 
> This is really what most people expect from such a command name based 
> on obvious historical reasons.  The lack of any branch argument to 
> git-pull and git-merge could be defined as using the first defined 
> remote branch by default.  But having git-pull performing merges is IMHO 
> overloading the word and goes against most people's expectations.

By the way, is anyone doing _remote_ octopus pull (true pull, not with . as
repository)?

We can always have --merge arguments to git-pull, and --fetch argument to
git-merge.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1241 bytes --]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> 
> > If the fetch+merge behavior (which I think should really be refered as 
> > pull+merge) is still desirable, then it should be called git-update and 
> > be no more than a single shell script line such as
> > 
> >         git_pull && git_merge"
> > 
> > This is really what most people expect from such a command name based 
> > on obvious historical reasons.  The lack of any branch argument to 
> > git-pull and git-merge could be defined as using the first defined 
> > remote branch by default.  But having git-pull performing merges is IMHO 
> > overloading the word and goes against most people's expectations.
> 
> By the way, is anyone doing _remote_ octopus pull (true pull, not with . as
> repository)?
> 
> We can always have --merge arguments to git-pull, and --fetch argument to
> git-merge.

That would be a complete abomination if you want my opinion.

Please let git-pull actually pull stuff from a remote place, and 
git-merge actually merge stuff only.  Let's keep simple concepts mapped 
to simple commands please.  Nothing prevents _you_ from scripting more 
involved operations with a single command of your liking afterwards.


Nicolas

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Nicolas Pitre wrote:
> On Tue, 14 Nov 2006, Jakub Narebski wrote:

>> We can always have --merge arguments to git-pull, and --fetch argument to
>> git-merge.
> 
> That would be a complete abomination if you want my opinion.
> 
> Please let git-pull actually pull stuff from a remote place, and 
> git-merge actually merge stuff only.  Let's keep simple concepts mapped 
> to simple commands please.  Nothing prevents _you_ from scripting more 
> involved operations with a single command of your liking afterwards.

Do we want to abandon completely "single-branch" workflow, where you
don't use tracking branch, only merge directly into your working branch?
That is the cause to (unused by most) future git-merge (replacement for
git-pull .) --fetch=<remote>[#<branch>] option.

I'm not that sure about --merge option, but it could be useful, at least
to have current automatic "Merge branch '<branch>' of <URL>" commit message.
-- 
Jakub Narebski

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> Nicolas Pitre wrote:
> > On Tue, 14 Nov 2006, Jakub Narebski wrote:
> 
> >> We can always have --merge arguments to git-pull, and --fetch argument to
> >> git-merge.
> > 
> > That would be a complete abomination if you want my opinion.
> > 
> > Please let git-pull actually pull stuff from a remote place, and 
> > git-merge actually merge stuff only.  Let's keep simple concepts mapped 
> > to simple commands please.  Nothing prevents _you_ from scripting more 
> > involved operations with a single command of your liking afterwards.
> 
> Do we want to abandon completely "single-branch" workflow, where you
> don't use tracking branch, only merge directly into your working branch?

I really think we should.  Let's admit it: such a work flow has nothing 
to do with the tool.  It would certainly be much easier to teach new 
users about "this is a read-only view of the remote content that you can 
merge into your working branch" than trying to explain why the tool is 
so weird for the sake of supporting different work flows directly.

Again I think it is easier to grasp two simple commands than a single 
but complex one with multiple ramifications.

> That is the cause to (unused by most) future git-merge (replacement for
> git-pull .) --fetch=<remote>[#<branch>] option.
> 
> I'm not that sure about --merge option, but it could be useful, at least
> to have current automatic "Merge branch '<branch>' of <URL>" commit message.

A "remote" branch should obviously have a corresponding URL.  So if you 
do "git-merge remote" then you may as well prepare a commit message with 
that URL given the local name for that branch if you want.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Tue, 14 Nov 2006 15:52:47 -0500 (EST), Nicolas Pitre wrote:
> Even if I have a clear preference for GIT's _technology_, I still think
> that the HG user interface is more convivial.  I even been thinking
> about writing something like an hg-like frontend to GIT from time to
> time just so that GIT could then be better compared to (and actually
> just used like) HG.

I've actually been tempted to do the same myself. I really think that
the technology is a more important criterion than the UI so the
imagined hg-on-git interface would be an attempt to get people to look
past the interface differences and look at the technology when
deciding.

But, then, I'd be guilty of creating another cogito, and I just argued
against its existence in a separate thread. So I think we're better
off just fixing the git interface.

> I still think that the GIT user interface sucks in many ways.  The
> confusion between pull, fetch and push is still my favorite, along with
> the locale vs remote branch issue.  Maybe we'll better handle the branch
> issue eventually,

The --use-separate-remotes thing is technology in the right direction
here. But I think it's another example of very useful stuff being
improperly hidden behind another command-line option. Getting rid of
the "remote-tracking branches" as user-visible branches possible for
committing should be a priority. And that should be the default for
everyone, not just people who happen to clone with this obscure
option.

Similarly, the reflog stuff was often trumpeted in the recent git
vs. bzr debate. Why is that very useful functionality buried in a
config file option and not just stored by default?

> This is really what most people expect from such a command name based
> on obvious historical reasons.  The lack of any branch argument to
> git-pull and git-merge could be defined as using the first defined
> remote branch by default.

Once again, there's lots of useful work on "branch configuration" that
allows for commands to be able to get the "right" default repository
for push and pull. I hope that that stuff can be enabled by default
and not require --use-separate-remotes or manual configuration for
people to benefit from it.

I apologize if I sound like I'm ranting here. I love to see the many
good improvements being made to git. It's just that there seems to be
a sort of shyness about new features, (perhaps a fear of changing
existing behavior?). When it improves the user experience, let's make
the improvement the default and not add any more

	--make-this-command-do-what-it-really-should-have-always-done

options.

-Carl

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

Re: Cleaning up git user-interface warts

[Jakub Narebski]

The git interface refactoring should be I think the cause for git 2.0.0
release...

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Jakub Narebski wrote:

> The git interface refactoring should be I think the cause for git 2.0.0
> release...

Good idea indeed.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> On Tue, 14 Nov 2006, Jakub Narebski wrote:
>
>> The git interface refactoring should be I think the cause for git 2.0.0
>> release...
>
> Good idea indeed.

We need to avoid user confusion, so making a command that used
to do one thing to suddenly do something completely different is
a no-no.  However, I do not think it needs to wait for 2.0.0.
We can start with a separate namespace (or even a separate
"Improved git UI project") and introduce the "improved UI set"
in 1.5.0 timeframe.

If managed properly, the "improved git UI" can coexist with the
current set of tools and over time we can give an option not to
even install the older Porcelain-ish commands.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > On Tue, 14 Nov 2006, Jakub Narebski wrote:
> >
> >> The git interface refactoring should be I think the cause for git 2.0.0
> >> release...
> >
> > Good idea indeed.
> 
> We need to avoid user confusion, so making a command that used
> to do one thing to suddenly do something completely different is
> a no-no.  However, I do not think it needs to wait for 2.0.0.
> We can start with a separate namespace (or even a separate
> "Improved git UI project") and introduce the "improved UI set"
> in 1.5.0 timeframe.

Dunno.  I feel this is a bit overboard.  Actually the naming problem is 
rather localized to one command, namely git-pull.  In my opinion going 
with yet another namespace which would rather add to the confusion not 
clear it.

The best way to avoid user confusion is to remove the source of the 
confusion not let it live.  In other words I think we should _fix_ 
git-pull instead of replacing it.  People are already confused about it 
so simply fixing this command will have a net confusion reduction.  Yet 
we're not talking about "suddenly doing something completely different" 
either.  If git-pull doesn't merge automatically anymore it is easy to 
tell people to use git-merge after a pull.

"You pull the remote changes with 'git-pull upstream,, then you can 
merge them in your current branch with 'git-merge upstream'."

Isn't it much simpler to understand (and to teach) that way?

Also I don't think using git-upload and git-download is much better.  
This adds yet more commands that do almost the same as existing ones but 
with a different name which is yet not necessarily fully adequate.  I 
for example would think that "download" is more like git-clone than 
git-fetch or git-pull.

Let's face it: HG got it right with pull and push and newbies have much 
less difficulty grokking it.  We screwed it by not using the most 
intuitive semantic of a pull and locking the word "pull" away is not the 
better solution given all considerations. Why just not admit it and 
avoid being different than HG just for the sake of it?

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> "You pull the remote changes with 'git-pull upstream,, then you can 
> merge them in your current branch with 'git-merge upstream'."
>
> Isn't it much simpler to understand (and to teach) that way?

If it were "you download the remote changes with 'git download
upstream' and then merge with 'git merge'", then perhaps, but if
you used the word "pull" or "fetch", I do not think so.

I would be all for changing the semantics of "pull" from one
thing to another, if the new semantics were (1) what everybody
welcomed, (2) what "pull" traditionally meant everywhere else.
In that case, we have been misusing it to be confusing to
outsiders and I agree it makes a lot of sense to remove the
source of confusion.  But I do not think CVS nor SVN ever used
the term, and I was told that BK was what introduced the term,
and the word meant something different from what you are
proposing.

You have to admit both pull and fetch have been contaminated
with loaded meanings from different backgrounds. I was talking
about killing the source of confusion in the longer term by
removing fetch/pull/push, so we are still on the same page.

That's where my "you download from the upstream and merge" comes
from.

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

I would kind of like to see "git poll" -- visit all remote branches,
fetching objects and tags into the local repository, so that I can
inspect changes off-line and merge, cherry-pick, etc. to my heart's
content.  That would fit the platform integrator's workflow nicely --
"git poll" into a tracking tree, do some merges there (such as
backporting a subsystem to a "stable" base kernel), then merge this
backport branch to each platform working copy and cherry-pick other
changes as necessary.

Cheers,

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > "You pull the remote changes with 'git-pull upstream,, then you can 
> > merge them in your current branch with 'git-merge upstream'."
> >
> > Isn't it much simpler to understand (and to teach) that way?
> 
> If it were "you download the remote changes with 'git download
> upstream' and then merge with 'git merge'", then perhaps, but if
> you used the word "pull" or "fetch", I do not think so.
> 
> I would be all for changing the semantics of "pull" from one
> thing to another, if the new semantics were (1) what everybody
> welcomed, (2) what "pull" traditionally meant everywhere else.
> In that case, we have been misusing it to be confusing to
> outsiders and I agree it makes a lot of sense to remove the
> source of confusion.  But I do not think CVS nor SVN ever used
> the term, and I was told that BK was what introduced the term,
> and the word meant something different from what you are
> proposing.
> 
> You have to admit both pull and fetch have been contaminated
> with loaded meanings from different backgrounds. I was talking
> about killing the source of confusion in the longer term by
> removing fetch/pull/push, so we are still on the same page.
> 
> That's where my "you download from the upstream and merge" comes
> from.

But the fact is that HG (which has a growing crowd of happy campers, 
maybe even larger than the BK crowd now) did work with and got used to a 
sensible definition of what a "pull" is.  This means that their 
definition is becoming rather more relevant with time than what it used 
to, and because it is a saner definition than what GIT has for the same 
word which HG users really have no issue with, I think we really should 
leverage the "common wisdom" and consider aligning ourselves with them 
in this case rather than trying to go into a totally different 
direction.  We simply won't gain anything trying to teach people "a pull 
in HG is a download in GIT".  If a pull becomes the same thing for both 
then it's one less oddball in the GIT interface.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> ...  We simply won't gain anything trying to teach people "a pull 
> in HG is a download in GIT".  If a pull becomes the same thing for both 
> then it's one less oddball in the GIT interface.

I personally do not have any issue with that, as long as you
would help us convert existing users that what was known as pull
is not available and new pull means fetching only.

If I recall correctly in this thread, you also advocated to
always have tracking branches.  I am a bit worried about losing
the promiscuous pull usage, which can easily become a regression
for people like Linus in the integrator role unless done with an
escape hatch.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Tue, 14 Nov 2006, Nicolas Pitre wrote:
> 
> But the fact is that HG (which has a growing crowd of happy campers, 
> maybe even larger than the BK crowd now) did work with and got used to a 
> sensible definition of what a "pull" is.

Guys, before you start thinking this way, the fact is, there's a lot of 
happy git users. 

So the reason for using "git pull" is

 - bk did it that way, and like it or not, bk was the first usable 
   distributed system. hg is totally uninteresting.

 - git itself has now done it that way for the last 18 months, and the 
   fact is, the people _complaining_ are a small subset of the people who 
   actually use git on a daily basis and don't complain.

So don't fall for the classic "second system syndrome". The classic reason 
for getting the second system wrong is because you focus on the issues 
people complain about, and not on the issues that work well (because the 
issues that work fine are obviously not getting a lot of attention).

If you think "pull" is confusing, I can guarantee you that _changing_ the 
name is a hell of a lot more confusing. In fact, I think a lot of the 
confusion comes from cogito, not from git - the fact that cogito used 
different names and different syntax was a mistake, I think.

And that '#' for branch naming in particular was (and is) total 
braindamage. The native git branch naming convention is just fundamentally 
much better, and allows you to very naturally fetch multiple branches at 
once, in a way that cogito's syntax does not.

So when I see suggestions of using that brain-damaged cogito syntax as an 
"improvement", I know for a fact that somebody hasn't thought things 
through, and only thinks it's a better syntax beause of totally bogus 
reasons.

I do agree that we probably could/should re-use the "git merge" name. The 
current "git merge" is an esoteric internal routine, and I doubt a lot of 
people use it as-is. I don't think it would be a mistake to make "git 
merge" basically be an alias for "git pull", for example, and I doubt many 
people would really even notice.

But the fact is, git isn't really that hard to work out, and the commands 
aren't that complicated. There's no reason to rename them. We do have 
other problems:

 - default branch selection for merging is broken (it should definitely 
   take the current branch into account). When I do "git pull" with no 
   branch specification, and I happen to be on a branch that is associated 
   with something else than "master" in the remote, I shouldn't merge with 
   master.

 - I agree that having to create temporary branches to just look at a tag 
   that you don't want to actually develop on is just unnecessarily 
   bothersome.

But trying to rename "pull" (or the "git" name itself) is just going to 
cause more confusion than you fix.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Linus Torvalds wrote:

> But the fact is, git isn't really that hard to work out, and the commands 
> aren't that complicated. There's no reason to rename them. We do have 
> other problems:
> 
>  - default branch selection for merging is broken (it should definitely 
>    take the current branch into account). When I do "git pull" with no 
>    branch specification, and I happen to be on a branch that is associated 
>    with something else than "master" in the remote, I shouldn't merge with 
>    master.

This problem is _slightly_ migitated by branch.<name>.merge config variable.
Slightly because you have to specify branch to merge, instead of forbidding
merge if you are not on specific branch (and you don't override it).

>  - I agree that having to create temporary branches to just look at a tag 
>    that you don't want to actually develop on is just unnecessarily 
>    bothersome.

Agreed.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Josef Weidendorfer]

On Wednesday 15 November 2006 19:28, you wrote:
> Linus Torvalds wrote:
> 
> > But the fact is, git isn't really that hard to work out, and the commands 
> > aren't that complicated. There's no reason to rename them. We do have 
> > other problems:
> > 
> >  - default branch selection for merging is broken (it should definitely 
> >    take the current branch into account). When I do "git pull" with no 
> >    branch specification, and I happen to be on a branch that is associated 
> >    with something else than "master" in the remote, I shouldn't merge with 
> >    master.
> 
> This problem is _slightly_ migitated by branch.<name>.merge config variable.
> Slightly because you have to specify branch to merge, instead of forbidding
> merge if you are not on specific branch (and you don't override it).

We should change this.

The problem is that whatever is the first Pull line in remotes config gets
merged by default into current branch, which most often is not the right
thing to do.

Often, I find myself doing "git branch" just to make sure that I am on
"master", so that a following pull does not do a bogus merge.

Can we please disable this behavior, e.g. by allowing a fake first
Pull line like "Pull: (not-for-merge)" to prohibit any merge?

This even could be written by default in git-clone somewhere in the future,
and we suddenly get the behavior of pull being symmetric to push - at least
by default. And still, it is fully compatible to existing repositories.

To make pull do the right thing, we _have_ to configure branch.<name>.merge
whenever we create a new branch (which matters for git-clone, too).

Josef

> 
> >  - I agree that having to create temporary branches to just look at a tag 
> >    that you don't want to actually develop on is just unnecessarily 
> >    bothersome.
> 
> Agreed.

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 09:31:13PM CET, Josef Weidendorfer wrote:
> Often, I find myself doing "git branch" just to make sure that I am on
> "master", so that a following pull does not do a bogus merge.
> 
> Can we please disable this behavior, e.g. by allowing a fake first
> Pull line like "Pull: (not-for-merge)" to prohibit any merge?

Wait, if you don't want pull to merge, why do you pull and not fetch?

(Disclaimer: I'm not intimately familiar with git pull/fetch and I
didn't read the whole thread yet.)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Josef Weidendorfer]

On Wednesday 15 November 2006 21:35, Petr Baudis wrote:
> On Wed, Nov 15, 2006 at 09:31:13PM CET, Josef Weidendorfer wrote:
> > Often, I find myself doing "git branch" just to make sure that I am on
> > "master", so that a following pull does not do a bogus merge.
> > 
> > Can we please disable this behavior, e.g. by allowing a fake first
> > Pull line like "Pull: (not-for-merge)" to prohibit any merge?
> 
> Wait, if you don't want pull to merge, why do you pull and not fetch?

I am not really opposed to pull doing a merge. It only should work in
a useful way: ie. only do the merge of updated origin branch when
current branch is master (given "Pull: master:origin").

I want "git pull" being harmless if I find myself accidently on a
branch != master. I always can do "git checkout master; git pull . origin"
afterwards.

For this to work, I currently need to specify a "branch.<name>.merge"
config for _every_ branch I have, as otherwise I get this bogus pull
merge behavior. This is not needed if there was a way to configure no
merge at all as default pull behavior.

I just noted that allowing such a config option would be kind of a
working compromise for all the people which want
pull to be the opposite of push.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Josef Weidendorfer wrote:
> 
> I am not really opposed to pull doing a merge. It only should work in
> a useful way: ie. only do the merge of updated origin branch when
> current branch is master (given "Pull: master:origin").

I absolutely agree.

We should _only_ use the default head when pulling from the default head 
("master"). If we don't pull from within the default branch, we should 
either require an explicit head _or_ we should require that an explicit 
mapping has been set up in .git/config or in .git/remotes/..

So doing a "git pull" from any other branch than "master" should probably 
by default say "which branch do you want to pull from today"?

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Tue, 14 Nov 2006, Nicolas Pitre wrote:
> > 
> > But the fact is that HG (which has a growing crowd of happy campers, 
> > maybe even larger than the BK crowd now) did work with and got used to a 
> > sensible definition of what a "pull" is.
> 
> Guys, before you start thinking this way, the fact is, there's a lot of 
> happy git users. 
> 
> So the reason for using "git pull" is
> 
>  - bk did it that way, and like it or not, bk was the first usable 
>    distributed system. hg is totally uninteresting.
> 
>  - git itself has now done it that way for the last 18 months, and the 
>    fact is, the people _complaining_ are a small subset of the people who 
>    actually use git on a daily basis and don't complain.

Those arguments are somewhat flawed.  If we stick to "BK did it that way 
and it was first", then following that logic we would also carry a lot 
of CVS baggage because "CVS did it that way, and it was the most 
successful of its kind".  Still, we decided not to follow CVS nor BK in 
many ways already.

As for the fraction of people complaining being a small fraction of 
current GIT users: that is easily explainable by the fact that most 
people who would have grown the complainers group are simply not GIT 
users anymore since they were turned away by GIT's current user 
interface issues.  The only complainers remaining are those who see 
value in the GIT technology but who would like to bring more 
intuitiveness to the GIT interface instead of going for the alternative 
technology.  And those kind of people are always few.

> So don't fall for the classic "second system syndrome". The classic reason 
> for getting the second system wrong is because you focus on the issues 
> people complain about, and not on the issues that work well (because the 
> issues that work fine are obviously not getting a lot of attention).

The counter part of that is the possibility to fall for the "ivory tower 
syndrome" where seasoned GIT users feel they are well satisfied with 
what is currently available and unwilling to consider changes that would 
reduce the barrier to entry for new users... simply because they are so 
used to the way things work that they can't see why others have problems 
with it.

> If you think "pull" is confusing, I can guarantee you that _changing_ the 
> name is a hell of a lot more confusing.

Agreed.  This is why the current discussion led to a proposition that 
allows for "pull" to remain as is but to have a "get" version that would 
be the alternate (saner) version.

> In fact, I think a lot of the 
> confusion comes from cogito, not from git - the fact that cogito used 
> different names and different syntax was a mistake, I think.
> 
> And that '#' for branch naming in particular was (and is) total 
> braindamage. The native git branch naming convention is just fundamentally 
> much better, and allows you to very naturally fetch multiple branches at 
> once, in a way that cogito's syntax does not.
> 
> So when I see suggestions of using that brain-damaged cogito syntax as an 
> "improvement", I know for a fact that somebody hasn't thought things 
> through, and only thinks it's a better syntax beause of totally bogus 
> reasons.

Do you have comments on my proposed syntax (that would be implemented 
with a git-get command) which I think doesn't really look like cogito?

> I do agree that we probably could/should re-use the "git merge" name. The 
> current "git merge" is an esoteric internal routine, and I doubt a lot of 
> people use it as-is. I don't think it would be a mistake to make "git 
> merge" basically be an alias for "git pull", for example, and I doubt many 
> people would really even notice.

Agreed.

> But the fact is, git isn't really that hard to work out, and the commands 
> aren't that complicated.

I agree with you in general, except for the "pull" behavior which is 
really really odd.  Maybe it made sense in the BK context, maybe it is 
fine _once_ you get used to it, but otherwise it is really overloaded.

> But trying to rename "pull" (or the "git" name itself) is just going to 
> cause more confusion than you fix.

Agreed again.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Nicolas Pitre <nico@cam.org> wrote:
> As for the fraction of people complaining being a small fraction of 
> current GIT users: that is easily explainable by the fact that most 
> people who would have grown the complainers group are simply not GIT 
> users anymore since they were turned away by GIT's current user 
> interface issues.  The only complainers remaining are those who see 
> value in the GIT technology but who would like to bring more 
> intuitiveness to the GIT interface instead of going for the alternative 
> technology.  And those kind of people are always few.

Or they are by proxy.

*I* don't see that much of a problem with git pull; I can use it
without trouble at this point.  But I find it difficult to teach
to others.

My complaints about git pull/fetch/push are by proxy for about 10
other users who aren't on the mailing list but whom I interact with
through Git.  They don't like pull/fetch/push very much.

So count my complaints 10 times.  :)

Ok, that's still a drop in the bucket of current Git users.
But still, I'm sure there are others.  I think Carl was recently
talking about complaints from some Fedora folks...

-- 

Re: Cleaning up git user-interface warts

[Marko Macek]

Shawn Pearce wrote:
> Nicolas Pitre <nico@cam.org> wrote:
>> As for the fraction of people complaining being a small fraction of 
>> current GIT users: that is easily explainable by the fact that most 
>> people who would have grown the complainers group are simply not GIT 
>> users anymore since they were turned away by GIT's current user 
>> interface issues.  The only complainers remaining are those who see 
>> value in the GIT technology but who would like to bring more 
>> intuitiveness to the GIT interface instead of going for the alternative 
>> technology.  And those kind of people are always few.
> 
> Or they are by proxy.
> 
> *I* don't see that much of a problem with git pull; I can use it
> without trouble at this point.  But I find it difficult to teach
> to others.
> 
> My complaints about git pull/fetch/push are by proxy for about 10
> other users who aren't on the mailing list but whom I interact with
> through Git.  They don't like pull/fetch/push very much.
> 
> So count my complaints 10 times.  :)
> 
> Ok, that's still a drop in the bucket of current Git users.
> But still, I'm sure there are others.  I think Carl was recently
> talking about complaints from some Fedora folks...

Agreed. Personally, the first thing that I notice when trying to switch
 from Subversion to git is the behavior of 'index', mainly in git-diff, git-status and 
git-commit.

For people switching from CVS and SVN it would be much better if the index was hidden 
behind the scenes by using different defaults:

git-commit -a
git-status -a
git-diff HEAD

BTW, currently there's a minor bug: git-diff HEAD doesn't work before you 
make the first commit. Perhaps this should be special cased.

I could personally get used to this, but I'd surely get blank 
stares from people when teaching them the difference.

I guess this is the reason that the GIT Tutorial for CVS/SVN users is talking about _cogito_ instead.
(which is very confusing for someone coming to _git_ home page, trying to learn git).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Marko Macek <marko.macek@gmx.net> writes:

> For people switching from CVS and SVN it would be much better if the
> index was hidden behind the scenes by using different defaults:
>
> git-commit -a
> git-status -a
> git-diff HEAD
>
> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
> you make the first commit. Perhaps this should be special cased.

That's only a _bug_ in your implementation of the synonym for
"svn diff" which blindly used "git diff HEAD".

"git diff HEAD" is not a synonym for "svn diff" when HEAD does
not exist yet, because you are asking "please give me a diff
between the tree in the HEAD commit and my working tree files
through the index".  So if you are doing "git-svnish-diff"
Porcelain script, it should notice that HEAD does not exist yet
and take an appropriate action.  We do something similar in
git-status; the porcelain notices and acts differently when HEAD
is not there yet.

This "there is no HEAD yet" is not related to the index, but I
am skeptical about trying to hide the index from the end user.

You can make some things map more naturally to systems like SVN
and CVS than other things.  For example, Nico's proposal to
always use remote tracking branches and defaulting to use
refs/remotes/ would be a way to match UI of pull/push to another
existing system and that would work well (I am not agreeing to
the change to make 'pull' not to do the merge which would break
existing users -- I am just saying that the result would be self
consistent).  But things that have difference at the concept
level, I suspect no clever mapping to hide the differences would
work well.

The index is quite central to the way git works at the concept
level, and I think it is doing disservice to the end user to try
hiding it forever from them and failing to do so, rather than
being honest and teaching them the concept upfront.

But me thinking so does not necessarily mean you are forbidden
from trying.  Your efforts may result in a system where the
index is totally invisible and the end user never has to know
about it.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> The index is quite central to the way git works at the concept
> level, and I think it is doing disservice to the end user to try
> hiding it forever from them and failing to do so, rather than
> being honest and teaching them the concept upfront.
> 
> But me thinking so does not necessarily mean you are forbidden
> from trying.  Your efforts may result in a system where the
> index is totally invisible and the end user never has to know
> about it.

I agree with what you are saying about the index.

But in git-gui I found myself writing code on Monday which tries to
hide the index from the user unless he/she requested that the index
be made visible.

The reason is there are some users who I'd like to give git-gui to
who I'm not sure I trust to make sure their index is in sync with
their working directory before they commit.  In some cases I'm lucky
that the user even knows what directory their file is stored in.  :-(
Yes, there really are computer users who are afraid of directories
and command lines.

I probably could try to teach them to make sure the final file
is included in the index before committing, but I think that for
most of them they would find this to be just another couple of
mouse clicks they have to perform before every commit, meaning its
something that the #$@!*@!*@$# tool should just do for them.

-- 

Re: Cleaning up git user-interface warts

[Marko Macek]

Junio C Hamano wrote:
> Marko Macek <marko.macek@gmx.net> writes:
> 
>> For people switching from CVS and SVN it would be much better if the
>> index was hidden behind the scenes by using different defaults:
>>
>> git-commit -a
>> git-status -a
>> git-diff HEAD
>>
>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>> you make the first commit. Perhaps this should be special cased.
> 
> That's only a _bug_ in your implementation of the synonym for
> "svn diff" which blindly used "git diff HEAD".


My "implementation" is taken from git-diff man page. It seems obvious
that the situation before the first commit is just a special case if 
we consider git-diff to be Porcelain (which I do).

 
> This "there is no HEAD yet" is not related to the index, but I

I agree, this is a separate issue.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Marko Macek <marko.macek@gmx.net> writes:

>>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>>> you make the first commit. Perhaps this should be special cased.
>>
>> That's only a _bug_ in your implementation of the synonym for
>> "svn diff" which blindly used "git diff HEAD".
>
> My "implementation" is taken from git-diff man page. It seems obvious
> that the situation before the first commit is just a special case if
> we consider git-diff to be Porcelain (which I do).

Yes, "git diff" is a Porcelain.  No question about it.

I do not consider the current behaviour of "git diff HEAD" that
complains instead of giving runs of "foo is a new file and no
diff is available for it" a bug; you asked for diff from some
commit but the commit you gave was bogus (does not exist yet).
But if you feel strongly about it, it should be trivial to
special case the yet-to-be-born HEAD case and run the
equilvalent of:

	git ls-files | sed -e 's/$/ is a new file, no diff is available./'

in such a case.  Or you could even go fancier and do an
equivalent of:

	git ls-files |
        while read path
        do
		l=`wc -l <"$path"`
        	echo "diff --git a/$path b/$path"
                echo "--- a/$path"
                echo "--- b/$path"
                echo "@@ -0,0 +1,$l @@"
                sed -e 's/^/+/' <"$path"
	done

and you can claim that it makes it consistent with the case
where you already have commits.

But I happen to think that consistency is only of academic
interest.  After all, how often would one create a true "root"
commit?  We are not talking about creating a new repository that
starts its life as a clone of something else, but a truly empty
one in which the initial commit is made.  And how often would
one want to view "diff" from void while preparing for that
initial commit?  Both that low frequency _and_ general
uselessness of the output from either of the above shell
scripts, would it be worth "fixing" it?

I do not think it adds any real practical value, and does not
even have much to do with being user friendly.  I would put it
in the "when somebody is really bored and has nothing better to
do, then this _could_ be done" category.

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Junio C Hamano wrote:

> Marko Macek <marko.macek@gmx.net> writes:
> 
>>>> BTW, currently there's a minor bug: git-diff HEAD doesn't work before
>>>> you make the first commit. Perhaps this should be special cased.
>>>
>>> That's only a _bug_ in your implementation of the synonym for
>>> "svn diff" which blindly used "git diff HEAD".
>>
>> My "implementation" is taken from git-diff man page. It seems obvious
>> that the situation before the first commit is just a special case if
>> we consider git-diff to be Porcelain (which I do).
> 
> Yes, "git diff" is a Porcelain.  No question about it.
> 
> I do not consider the current behaviour of "git diff HEAD" that
> complains instead of giving runs of "foo is a new file and no
> diff is available for it" a bug; you asked for diff from some
> commit but the commit you gave was bogus (does not exist yet).

git diff --root HEAD, perhaps?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 20:05:27 +0100
Marko Macek <marko.macek@gmx.net> wrote:

> I guess this is the reason that the GIT Tutorial for CVS/SVN users is talking about _cogito_ instead.
> (which is very confusing for someone coming to _git_ home page, trying to learn git).

IMHO this is really bad.  Pasky runs the Git web site and feels
that Cogito comes hand in hand with Git.  When I asked him about
it he mentioned that Junio had approved.  But it's very confusing
to click a link that purports to show you how to use Git and get
shown a bunch of Cogito stuff.

Git is confusing enough for new users without "Git" and "Cogito"
being mixed without comment on the Git webpage.  At the very
least, the links should be changed to "Cogito for CVS/SVN users".

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:28:34PM CET, Sean wrote:
> Git is confusing enough for new users without "Git" and "Cogito"
> being mixed without comment on the Git webpage.  At the very
> least, the links should be changed to "Cogito for CVS/SVN users".

It's not being mixed without comment, in the very first paragraph I'm
trying to explain what the difference is and why is Cogito used for
introduction to Git. I've tried to clear it up even more now.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 18:03, Linus Torvalds wrote:

> Guys, before you start thinking this way, the fact is, there's a lot of
> happy git users.

I'm a happy user, doesn't mean I wouldn't like changes.  In fact, by that 
argument, that there are happy users means that there is no need to ever make 
changes.

>  - git itself has now done it that way for the last 18 months, and the
>    fact is, the people _complaining_ are a small subset of the people who
>    actually use git on a daily basis and don't complain.

That's awfully like the argument I hear off my bank whenever I complain to 
them too - "well lots of other people don't complain so we must be right".  
The people who complain are a subset of the people who have complaints.  I 
don't think never changing is a good argument - leaving aside the actual 
changes under discussion - in another 18 months lets say there are double the 
number of git users, and 18 months after that double again - in that case the 
potential new users needs outweigh the current users needs.

> If you think "pull" is confusing, I can guarantee you that _changing_ the
> name is a hell of a lot more confusing. In fact, I think a lot of the

> But the fact is, git isn't really that hard to work out, and the commands

On the one hand you're arguing that git syntax is easy to learn, and on the 
other that no one will be able to learn a new syntax just as easily.

> aren't that complicated. There's no reason to rename them. We do have
> other problems:

That there are other problems doesn't negate these problems.

> But trying to rename "pull" (or the "git" name itself) is just going to
> cause more confusion than you fix.

I don't think so.  Mainly because the proposed new git pull would be a subset 
of the existing git pull.  It's not changing function, it's just reducing in 
function.


Andy
-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Andy Parkins wrote:
>
> On the one hand you're arguing that git syntax is easy to learn, and on the 
> other that no one will be able to learn a new syntax just as easily.

I'm saying that people who are new to git will _have_ to learn new 
concepts ANYWAY.

I don't think the naming is the hard part. 

The fact is, git is one of the very few (essentially _only_) SCM's that 
make it very clear that all real operations are local and that if you want 
to work with other repositories, you have to "fetch" those into local 
branches first. The fact that "pull" exists at all is really just 
shorthand.

If people have trouble explaining this to others, and have trouble 
grasping "pull", then I will bet that the _real_ issue has nothing at all 
to do with naming at all, and the real issue is that people are being 
_taught_ the concepts in the wrong order.

Before you learn "pull", you should learn "fetch". Don't even _mention_ 
"pull" until the person got what "fetch" means. Because the fact is, 
"fetch" is really the much more fundamental operation, and once you 
really understand what "fetch" does, "pull" is obvious.

So I'll argue that the problem isn't naming, the "problem" is really that 
git has a few fundamnetal concepts that people aren't used to. The most 
fundamnetal of those is the notion of the local branch-space. EVERY other 
(broken) SCM has branches as being some kind of totally idiotic separate 
subdirectories, or doesn't really support branches at all (ie neither BK 
nor CVS really support "branches" - even if a concept of that name exists 
in CVS, it has nothing at all in common with the git model of branches).

But once you understand branches, and understand "fetch" (and it really 
isn't _that_ complicated: fetch really does exactly what the name says, so 
if you understand local branches, you will understand "fetch"), then it's 
a much smaller step to explain "pull = fetch + merge".

But I bet people don't teach it that way. They _start_ by teaching "pull". 
Right?

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
> But once you understand branches, and understand "fetch" (and it really
> isn't _that_ complicated: fetch really does exactly what the name says, so
> if you understand local branches, you will understand "fetch"), then it's
> a much smaller step to explain "pull = fetch + merge".
>
> But I bet people don't teach it that way. They _start_ by teaching "pull".
> Right?

"git fetch" is certainly the right thing for the platform integration
role, in which one is trying to maintain a series of integration
branches which track the bleeding edge of some subsystems while
keeping the core stable on each branch.  This is not as impossible as
people make it out to be, but there certainly isn't much place for
automatic merges to _persistent_ branches.

It's fundamentally a backporting and cherry-picking effort, and the
git workflow puts it where it belongs: in the local repository, where
_transient_ branches can and should be created and destroyed casually
to track exploratory efforts.  These may include automatic merges and
even cruder techniques (git diff, hack on patch, apply patch).  Once
you figure out which bits you actually want to backport, you go back
to a fresh branch and cherry-pick the same bits with the tool instead
of manually, so that there is less noise in future merges.  When
you've tested a little, you merge this branch to the persistent branch
that other repositories track.

Cheers,

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Michael K. Edwards wrote:
> > 
> > But I bet people don't teach it that way. They _start_ by teaching "pull".
> > Right?
> 
> "git fetch" is certainly the right thing for the platform integration
> role

I'm saying that even if you _never_ end up using "git fetch" ever again 
(because in practice you always want to do a "fetch + merge == pull"), 
people who teach others the concepts and usage of git should probably 
start by talking about "git fetch".

Then, when the user says (and he obviously will say this) "but I don't 
want to just fetch the other persons work into some local branch, I want 
to actually get it into _my_ branch", you say "Ahhah!" and talk about how 
"pull" is a shorthand for first fetching and then merging the result into 
the current branch.

See? Once you explain "fetch" to somebody, I can pretty much guarantee 
that they'll explain "pull" to themselves without you having to even work 
at it. And then they'll probably happily use "pull" ever after, and never 
worry about fetch, but now they'll understand the _concepts_.

It's only if you start the other way around that "pull" vs "fetch" vs 
"push" become confusing. If you _start_ by explaining branches (and you 
might use "gitk --all" on a small project as a visualization tool), 
suddenly the concepts aren't all that complicated.

Sure, then you have to remember two words ("pull" vs "fetch"), but I'm 
pretty sure that the thing that makes people confused is not the words 
themselves, but their lack of understanding of the concepts behind them.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> I'm saying that even if you _never_ end up using "git fetch" ever again 
> (because in practice you always want to do a "fetch + merge == pull"), 
> people who teach others the concepts and usage of git should probably 
> start by talking about "git fetch".
> 
> Then, when the user says (and he obviously will say this) "but I don't 
> want to just fetch the other persons work into some local branch, I want 
> to actually get it into _my_ branch", you say "Ahhah!" and talk about how 
> "pull" is a shorthand for first fetching and then merging the result into 
> the current branch.

Actually I believe it would make things even clearer if "merge" was 
taught at that point.  Only when the user is comfortable with the 
separate notions of fetching and merging might the pull shorthand 
possibly be mentioned.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> Actually I believe it would make things even clearer if "merge" was 
> taught at that point.  Only when the user is comfortable with the 
> separate notions of fetching and merging might the pull shorthand 
> possibly be mentioned.

I agree. I just expect that "merge" is such a simple concept that it 
doesn't really need a whole lot of explaining. 

People kind of expect merging to be hard, but I think it's because CVS et 
al have tought people that merging is _painful_. I don't think it's a very 
complicated concept per se, especially if you have explained branches with 
gitk already.

But yes, the order should be:

 (a) explain what "branches" mean in git (and in that situation, "fetch" 
     is very natural - I think fetching itself is probably easier to 
     explain than "branches" are).
 (b) once you've explained branches, the notion of "merge" comes next, and 
     I _think_ that is very obvious. This is where UI issues come in, 
     because "git merge" is really a totally internal program with a 
     pretty horrid UI, but I think we could fix the syntax, and even with 
     the current syntax you can really just gloss it over, because nobody 
     is really going to care.
 (c) once "fetching branches" and "merging" have been explained, "pull" is 
     really pretty damn trivial, and in fact, if you then explain that 
     it's just easier to do "git pull . branchname" than to use "git 
     merge", I think people may just even agree with you.

I think I saw that particular discussion on #git: somebody didn't expect 
"git pull . branch" to be the way to merge. And again, I think it's 
not _really_ because "pull" is hard to understand, it's because people 
haven't been walked through the thing in this way.

Once you understand local branches, fetching and merging, it's actually 
_easier_ to explain why we merge even local branches with "git pull .": 
you just tell them that this way you can use the same command regardless 
of whether you're merging something local or something remote. Again, if 
it's explained that way, I bet a lot of people react with "ahh, that's 
clever", and _like_ the fact that they only really need to learn _one_ 
command, instead of learning two.

See? Explain it that way: "pull" really is simple. By using "pull", you 
don't have to learn about "merge" syntax. You -can- use "merge" as a 
separate program if you want to, but the syntax isn't very nice, exactly 
because you're not really expected to.

But the real issue here is to explain local branches. I will happily admit 
that local branches are very VERY different from just about any other SCM, 
but I also claim that git is just much BETTER than other SCM's in this 
respect.

And yes, this is why you should NOT try to use the same naming as "hg", 
for example. Last I saw, hg still didn't even have local branches, To 
mercurial, repository == branch, and that's it. It was what I came from 
too, and I used to argue for using git that way too. I've since seen the 
error of my ways, and git is simply BETTER. 

And the concept of local branches is exactly _why_ you have to have 
separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
(because "pull ." does it for you).

If you don't understand local branches, you'll never understand git usage. 
And once you _do_ understand local branches, "fetch" vs "pull" actually is 
rather simple.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 12:40:43 -0800 (PST), Linus Torvalds wrote:
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> >
> > Actually I believe it would make things even clearer if "merge" was
> > taught at that point.  Only when the user is comfortable with the
> > separate notions of fetching and merging might the pull shorthand
> > possibly be mentioned.
>
> I agree. I just expect that "merge" is such a simple concept that it
> doesn't really need a whole lot of explaining.

Well, one of the problems is that with current git I can teach, (and I
have), that there's a conceptual:

	pull = fetch + merge

But then shortly after I have to teach an interface notion:

	merge = pull .

So there's this goofy circular notion that people end up with
mentally. If we fix it so that a local merge really is performed with
"git merge <branch>" instead of "git pull . <branch>" then teaching
pull=fetch+merge really is a lot easier.

In the meantime, pull would still be useless to me, I think. But maybe
that's just the "default branch to merge" selection being broken. If
that were fixed, maybe I would start using pull.

>  (a) explain what "branches" mean in git (and in that situation, "fetch"
>      is very natural - I think fetching itself is probably easier to
>      explain than "branches" are).

There's a piece missing here, namely the mapping between remote and
local branch names and any notion of "tracking branches". I think a
sane story for that is still being invented, (or if it exists now, I
haven't seen it yet).

>  (c) once "fetching branches" and "merging" have been explained, "pull" is
>      really pretty damn trivial, and in fact, if you then explain that
>      it's just easier to do "git pull . branchname" than to use "git
>      merge", I think people may just even agree with you.

Well, they get pretty darn confused at this point, in my experience.

> Once you understand local branches, fetching and merging, it's actually
> _easier_ to explain why we merge even local branches with "git pull .":
> you just tell them that this way you can use the same command regardless
> of whether you're merging something local or something remote. Again, if
> it's explained that way, I bet a lot of people react with "ahh, that's
> clever", and _like_ the fact that they only really need to learn _one_
> command, instead of learning two.

No. It's really, really broken to use "pull ." for local merging. Not
a feature at all. We just got done establishing that pull is a
shorthand for doing fetch+merge, so reusing it when there is _no_
fetch at all is insane.

You just established quite clearly hat git has a huge advantge over
all other systems by having a model that everything is fetched in
and then worked with locally. I agree that this is a major
selling-point of git, and I'm also baffled that systems like bzr and
hg try so hard to push every branch into a separate repository.

But I think that git's "work with everything locally" story is undercut
a bit by regular usage being to use a transfer-inducing command like
"pull" for a totally local merge.

Anyway, I think we all agree that we'd really rather have "git merge
<branch>" be usable for local merges, so let's get that in place and
users can pick whichever they like.

> But the real issue here is to explain local branches. I will happily admit
> that local branches are very VERY different from just about any other SCM,
> but I also claim that git is just much BETTER than other SCM's in this
> respect.

Totally agree.

-Carl

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

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> So there's this goofy circular notion that people end up with
> If we fix it so that a local merge really is performed with
> "git merge <branch>" instead of "git pull . <branch>" then teaching
> pull=fetch+merge really is a lot easier.

I am wondering if that could be "git merge <committish>..."
instead.  I do not care too much about the ... part (i.e. an
Octopus), but I often find myself doing:

	git checkout next
        git merge "Merge early part of branch 'foo'" HEAD foo~3

when earlier part of "foo" topic are worthy to be in 'next' but
not the later ones.

> In the meantime, pull would still be useless to me, I think. But maybe
> that's just the "default branch to merge" selection being broken.

Have you looked into per-branch configuration for default merge
source recently?  It might not be documented well enough,
though, because I do not use it myself, but you should be able
to improve on that (meaning both documentation and setting up
the defaults upon cloning and fetching).

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> I am wondering if that could be "git merge <committish>..."
> instead.  I do not care too much about the ... part (i.e. an
> Octopus), but I often find myself doing:
> 
> 	git checkout next
>         git merge "Merge early part of branch 'foo'" HEAD foo~3
> 
> when earlier part of "foo" topic are worthy to be in 'next' but
> not the later ones.

Indeed !

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> On Wed, 15 Nov 2006, Junio C Hamano wrote:
>
>> I am wondering if that could be "git merge <committish>..."
>> instead.  I do not care too much about the ... part (i.e. an
>> Octopus), but I often find myself doing:
>> 
>> 	git checkout next
>>         git merge "Merge early part of branch 'foo'" HEAD foo~3
>> 
>> when earlier part of "foo" topic are worthy to be in 'next' but
>> not the later ones.
>
> Indeed !

Indeed, what?

That means that updated "git merge" (not the current one) would
not be able to assume it's parameter is a branch name, and still
has to come up with the merge message "Merge <branch>".

Merging only within the local branch namespace already has the
problem you need to solve to come up with a nicely formatted
"Merge <branch> of <remote repository>" some way.  I am not
saying that this is unsolvable (you can look at remotes/ files
to see what remote tracking branch the branch is about), but
something you need to keep in mind when implementing the
improved "git merge".

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > On Wed, 15 Nov 2006, Junio C Hamano wrote:
> >
> >> I am wondering if that could be "git merge <committish>..."
> >> instead.  I do not care too much about the ... part (i.e. an
> >> Octopus), but I often find myself doing:
> >> 
> >> 	git checkout next
> >>         git merge "Merge early part of branch 'foo'" HEAD foo~3
> >> 
> >> when earlier part of "foo" topic are worthy to be in 'next' but
> >> not the later ones.
> >
> > Indeed !
> 
> Indeed, what?

What you propose would be excellent indeed.

> That means that updated "git merge" (not the current one) would
> not be able to assume it's parameter is a branch name, and still
> has to come up with the merge message "Merge <branch>".
> 
> Merging only within the local branch namespace already has the
> problem you need to solve to come up with a nicely formatted
> "Merge <branch> of <remote repository>" some way.  I am not
> saying that this is unsolvable (you can look at remotes/ files
> to see what remote tracking branch the branch is about), but
> something you need to keep in mind when implementing the
> improved "git merge".

Right.  But that is an _implementation_ detail, not a usability issue.

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 13:52:47 -0800, Junio C Hamano wrote:

> That means that updated "git merge" (not the current one) would not
> be able to assume it's parameter is a branch name, and still has to
> come up with the merge message "Merge <branch>".

Often, it would be a branch or a tag, so no problem there. For commits
in general, it should not be hard to compute the set of branches and
tags the commit is part of, and in the (probably) common case where
this set has exactly one element, the problem is solved. For the
remaining cases, it should not be too horrible to ask the user to
describe what is being merged.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Carl Worth wrote:
> 
> Well, one of the problems is that with current git I can teach, (and I
> have), that there's a conceptual:
> 
> 	pull = fetch + merge
> 
> But then shortly after I have to teach an interface notion:
> 
> 	merge = pull .

This is why I would suggest teaching the _concept_ of the "merge", and not 
the actual command.

I don't think you should basically ever use the "git merge" command 
itself, not in teaching, and not in real life. So after talking about 
branches and having taught people to use "git fetch", the next stage is 
not so much to teach people to use "git merge", but to explain to them the 
_concept_ of merging. 

I really think that's a fairly quick thing, partly exactly _because_ you 
shouldn't at that point need to worry about syntax or details or anything 
like that at all. You just tell them that there's a notion of "merging" 
two branches by joining them together and havign the result have the 
changes from both branches. So it's a _conceptual_ issue, and that's why I 
said I think you should just totally gloss over the whole issue of "git 
merge" syntax.

Once you've explained the _concept_ of merging, you then introduce the 
command to actually _execute_ the merge: it's "git pull".

See? No circular thinking at all. One is a _concept_ ("join two branches 
together by including both in the result") and the other is a command 
("pull will fetch the remote data if any, and merge it into the current 
branch").

If you explain it that way, then _obviously_ if you don't need to fetch 
any remote data, doing "git pull . xyzzy" will merge the local branch 
"xyzzy" into the current branch.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 13:45:58 -0800 (PST), Linus Torvalds wrote:
> On Wed, 15 Nov 2006, Carl Worth wrote:
> >
> > Well, one of the problems is that with current git I can teach, (and I
> > have), that there's a conceptual:
> >
> > 	pull = fetch + merge
> >
> > But then shortly after I have to teach an interface notion:
> >
> > 	merge = pull .
>
> This is why I would suggest teaching the _concept_ of the "merge", and not
> the actual command.
>
> I don't think you should basically ever use the "git merge" command
> itself, not in teaching, and not in real life.

I think that's just and accident of git-merge having such a bad
syntax, (requiring a merge message, not using -m for that, requiring
two heads instead of defaulting to current, etc.). So the result is
accepting another bad syntax "pull ." for an operation that really is
merge.

> Once you've explained the _concept_ of merging, you then introduce the
> command to actually _execute_ the merge: it's "git pull".

I think we'll be doing better when there is a stronger correlation
between the concepts of the operations and the command names for
carrying them out.

Plus, when I'm teaching "fetch everything first, then manipulate it
locally", (which is what I teach, since that's the only way I use
git), then the "." looks really out of place when I teach the 'merge'
command. I end up saying, "Oh, that's there because you could do the
fetch and merge all in one step if you really wanted, but I never do
that.".

And that's because I _do_ teach fetch first, as you've suggested.

> changes from both branches. So it's a _conceptual_ issue, and that's why I
> said I think you should just totally gloss over the whole issue of "git
> merge" syntax.

That doesn't work. I know I went looking at the git-merge
documentation when I started to learn git. "It can't really be this
hard, can it?" was my reaction to it. And then only after attending a
tutorial did I learn that "pull ." is the way it's really done.

That's nothing more than a user-interface trap for new users, plain
and simple.

The real fix is to stop glossing over git-merge and just give it a
usable syntax.

-Carl

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

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
> Plus, when I'm teaching "fetch everything first, then manipulate it
> locally", (which is what I teach, since that's the only way I use
> git), then the "." looks really out of place when I teach the 'merge'
> command. I end up saying, "Oh, that's there because you could do the
> fetch and merge all in one step if you really wanted, but I never do
> that.".
> 
> And that's because I _do_ teach fetch first, as you've suggested.

Ditto.  In every way.

I've taught the same fetch first, then merge strategy.  Nobody I
know in meat-space pulls from a remote URL and merges in one shot;
they always fetch locally, look at the incoming changes, decide if
its worthwhile/ok, *then* merge with "git pull . branch".

The "." looks out of place for everyone...

-- 

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Shawn Pearce wrote:
> 
> I've taught the same fetch first, then merge strategy.  Nobody I
> know in meat-space pulls from a remote URL and merges in one shot;

Actually, with different people involved it's _much_ better to do it in 
one shot.

Why? Because doing a separate "fetch to local space" + "merge from local 
space" actually loses the information on what you are merging.

It's a lot more useful to have a merge message like

	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6

than one like

	Merge branch 'for-linus'

which is what you get if you fetched it first.

Of course, in a situation like git itself, where most of the merges are 
stuff that Junio has had pending in his own tree ('maint' branch etc), 
things are different. But in a system where people actually use separate 
trees, there really is an advantage to consider the fundamental operation 
to be the "pull", not the "merge".

Again, the kernel really is more distributed than most projects, but this 
is another thing people should recognize: git has been designed for "true 
distributed development". Not the "fake" kind. Not the "I merge mainly my 
own branches" kind of thing. Truly distributed.

And in a truly distributed situation, "pull" is strictly more powerful 
than a separate "fetch" + separate "merge".

In other words, an SCM that does "pull" is _better_ than an SCM that does 
"merge". You can implement "merge" as a special case of "pull" (which we 
do), but you cannot conveniently do it the other way around without having 
to tie them together some other way (ie you could have a "remember the 
last place we fetched this branch from in order to tie the fetch and the 
merge together" - but please realize that that is exactly what "pull" 
_is_).

So I will generally do a "git pull" (possibly followed by a "git reset 
--hard ORIG_HEAD" if I decided it wasn't good) over a "git fetch" + "git 
merge". Exactly because the "pull" operation is actually more powerful.

Maybe people who aren't in my position don't always appreciate the _power_ 
of git. The reason "merge" is a second-class citizen is simply because IT 
SHOULD BE.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Shawn Pearce wrote:
> > 
> > I've taught the same fetch first, then merge strategy.  Nobody I
> > know in meat-space pulls from a remote URL and merges in one shot;
> 
> Actually, with different people involved it's _much_ better to do it in 
> one shot.
> 
> Why? Because doing a separate "fetch to local space" + "merge from local 
> space" actually loses the information on what you are merging.
> 
> It's a lot more useful to have a merge message like
> 
> 	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
> 
> than one like
> 
> 	Merge branch 'for-linus'

That is an implementation detail that should be easily overcome once the 
notion of tracking branch with URL attribute is implemented.  Then it 
will be really easy to notice whether the branch argument is a local 
branch or a tracking branch with remote reference.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> That is an implementation detail that should be easily overcome once the 
> notion of tracking branch with URL attribute is implemented.

Nope.

I simply don't _have_ those branches.

Why? Because the kernel is _distributed_. There is no central place 
(certainly not my repository) that tracks all the possible branches that 
might get merged.

In other words, I repeat: in a TRULY DISTRIBUTED ENVIRONMENT it makes more 
sense to have a "pull" that fetches and merges, over something that 
fetches separately and then merges. Because in a truly distributed 
environment, you simply DO NOT HAVE static branches that you can associate 
with particular sources.

See?

And the thing is, I think the git design should be geared towards true 
distribution. It should NOT be geared toward a fairly static set of 
branches that all have a fairly static set of other repositories 
associated with them. Can you see the difference?

I'm personally convinced that one of the reasons people tend to use git in 
a centralized manner is just a mental disease that has its roots in how 
they used _other_ SCM's. I don't want git design to be polluted by such a 
centralized notion.

So to repeat: you can always make "pull" boil down to "pull from myself" 
(aka just "merge"), but you can _not_ make "fetch + merge" boil down to 
"pull" without meking up extra state to track separately. In other words, 
"pull" really is the strictly more powerful operation.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> > 
> > That is an implementation detail that should be easily overcome once the 
> > notion of tracking branch with URL attribute is implemented.
> 
> Nope.
> 
> I simply don't _have_ those branches.
> 
> Why? Because the kernel is _distributed_. There is no central place 
> (certainly not my repository) that tracks all the possible branches that 
> might get merged.
> 
> In other words, I repeat: in a TRULY DISTRIBUTED ENVIRONMENT it makes more 
> sense to have a "pull" that fetches and merges, over something that 
> fetches separately and then merges.
[...]

OK fine.  git-pull is there to stay and let's make sure it remains the 
same.

Let's see if, for example, git-merge can be made more useful in the mean 
time for those evidently inferior people that would prefer an interface 
that maps more closely to the actual operation that is being performed.  
And although I do understand what "pull" does, I think I should qualify 
myself as one of those inferior people nevertheless since /pull . blah" 
really irritates me.  OK I must be really dumb to let myself being 
disturbed by such an insignificant detail... but apparently I'm not 
alone.

But I promise to never change the "pull" behavior if I ever attempt to 
fix the "merge" command for the inferior mortals as myself.  All power 
to those with superior minds shall never be removed.

;-)

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
> Actually, with different people involved it's _much_ better to do it in
> one shot.
>
> Why? Because doing a separate "fetch to local space" + "merge from local
> space" actually loses the information on what you are merging.
>
> It's a lot more useful to have a merge message like
>
>         Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
>
> than one like
>
>         Merge branch 'for-linus'
>
> which is what you get if you fetched it first.

Full ACK from a platform integrator's perspective.  Local merge is
great for trial runs but the history in a persistent branch should be
as self-contained and self-explanatory as possible.  It shouldn't
depend on what I name local tracking branches, which are just a
convenience so that I can still do trial runs when my connectivity is
broken.

I don't have to manually log the _mechanical_origin_ of a given delta;
git does that for me, and mostly just DTRT when the same delta arrives
via several paths.  When I use git pull from a remote branch (with or
without an entry in remotes/heads, which for this purpose is just
shorthand), I don't have to manually log what conflicts I have and
haven't resolved, either; I must have assimilated whatever I cared
about in the remote branch's history up to that point, because as long
as there are things in that remote branch that I haven't decided how
to handle, I stick to cherry-picking.

Obviously, fetch to local space is great (especially when you spend
some of your working hours behind a firewall that blocks outbound TCP
9418).  Fetch from local space is also great, when the local space you
are fetching from reflects local work (such as a sync point and
reconciliation of several upstream sources, which then needs to be
ported forward or back to the chosen core version for each platform).
Fetch from a local space that is just a tracker for remote work is not
great, because it doesn't capture the editorial decision implied by a
remote pull:  I looked at what the remote branch had to offer as of
this date, systematically decided which bits did and didn't belong in
the branch to which I was pulling, and pulled.

The record of that pull becomes a first-class object because it's
attached to an actual content delta in the target branch.  So it
propagates into branches that pull from it.  Pulling this delta into
another branch is different from cherry-picking a feature delta; it
implies acceptance of the reconciliation and editorial work associated
with the merge in the source branch.

Coming from me, this is all rather theoretical, as I haven't been
using this particular tool for the purpose long enough to have an
independent opinion.  But for what it's worth, the workflow Linus
describes isn't just for the guy at the top of the pyramid.

Cheers,

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Michael K. Edwards wrote:
> On 11/15/06, Linus Torvalds <torvalds@osdl.org> wrote:
>> Actually, with different people involved it's _much_ better to do it in
>> one shot.
>>
>> Why? Because doing a separate "fetch to local space" + "merge from local
>> space" actually loses the information on what you are merging.
>>
>> It's a lot more useful to have a merge message like
>>
>>         Merge branch 'for-linus' of 
>> git://one.firstfloor.org/home/andi/git/linux-2.6
>>
>> than one like
>>
>>         Merge branch 'for-linus'
>>
>> which is what you get if you fetched it first.
> 
> Full ACK from a platform integrator's perspective.  Local merge is
> great for trial runs but the history in a persistent branch should be
> as self-contained and self-explanatory as possible.  It shouldn't
> depend on what I name local tracking branches, which are just a
> convenience so that I can still do trial runs when my connectivity is
> broken.
> 

[...]

> 
> Coming from me, this is all rather theoretical, as I haven't been
> using this particular tool for the purpose long enough to have an
> independent opinion.  But for what it's worth, the workflow Linus
> describes isn't just for the guy at the top of the pyramid.
> 

I think it's unfortunate that git was originally written by Linus, since 
he so obviously is "the guy at the top of the pyramid" in many more 
senses than just "Linus said this and that patch was OK to commit", 
since git was designed to work like king Arthur's round table; "Linus is 
in the same circle as me, so ofcourse we help each other out".

All suggestions I've been reading about tracking branches, 
separate-remotes and whatnot have their merit. If any of it gets 
implemented, I'd still like to be able to do one-shot pulls from remote 
repos *without* creating specific tracking branches for it. It's 
extremely useful to fetch other peoples topic-branches into my own 
"master" (or topic-branch) when I trust their changes to be good. Please 
consider that when you're hacking away on whatever changes to do.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 15:33:43 -0800 (PST), Linus Torvalds wrote:
> It's a lot more useful to have a merge message like
>
> 	Merge branch 'for-linus' of git://one.firstfloor.org/home/andi/git/linux-2.6
>
> than one like
>
> 	Merge branch 'for-linus'

There's more information in the first, sure. But I absolutely don't
accept that it's necessarily more useful, and definitely not that this
is a good argument for using pull with a remote branch instead of
fetch followed by merge with a local branch.

First, the pull may just fast-forward in which case there's no message
at all. And we've been through that topic enough recently that we all
know that no important information is lost by not doing any separate
recording in that case.

So you can't turn around and argue that the remote URL information is
suddenly important when it just so happens that it's not a fast
forward.

> And in a truly distributed situation, "pull" is strictly more powerful
> than a separate "fetch" + separate "merge".

I don't buy it. In my usage, I have several different remote
repositories I'm interested in tracking, each with any number of
branches. What I really want is an easy command that fetches all of
those branches, (even new ones that I've never heard about---but never
any of their "tracking branches" that wouldn't be of interest to
me). And I want to do that once, to get the online-access-required
part over with and get all the data into my local repository where I
can start working with it.

As for the URL from which I'm fetching all this stuff, it's really not
interesting to me at all. The URL for "Keith's stuff" keeps changing
anyway---I have no interest in recording that. But I do think it's
worth recording that the commits came from Keith's repository. I do
that right now with a keith/ prefix for his branches. It could also be
done by bringing in his .git/description during the fetch and storing
it somewhere. But I honestly don't see how storing something like that
during would make the system any less distributed in any sense.

-Carl

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

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Carl Worth <cworth@cworth.org> wrote:
> First, the pull may just fast-forward in which case there's no message
> at all. And we've been through that topic enough recently that we all
> know that no important information is lost by not doing any separate
> recording in that case.
>
> So you can't turn around and argue that the remote URL information is
> suddenly important when it just so happens that it's not a fast
> forward.

When it's a fast forward, the puller hasn't had to make any judgment
calls, so there's no editorial history to record.  When it's not, but
the puller chooses to retain the result on a persistent branch, that
_is_ an editorial decision (even if the result of the auto-merge is
clean); I like having that in the history.

> > And in a truly distributed situation, "pull" is strictly more powerful
> > than a separate "fetch" + separate "merge".
>
> I don't buy it. In my usage, I have several different remote
> repositories I'm interested in tracking, each with any number of
> branches. What I really want is an easy command that fetches all of
> those branches, (even new ones that I've never heard about---but never
> any of their "tracking branches" that wouldn't be of interest to
> me). And I want to do that once, to get the online-access-required
> part over with and get all the data into my local repository where I
> can start working with it.

What do you want all of those branches for?  They haven't been
published to you (that's a human interaction that doesn't go through
git), so for all you know they're just upstream experiments, and doing
things with them is probably shooting yourself in the foot.

I do agree that a robust form of "for b in .git/remotes/*; do git
fetch `basename $b`; done" would be a nice bit of porcelain.  The
entries in .git/remotes would probably need to grow a "Fetch-options:"
field so that you could choose whether or not to follow tags, etc.
Patch to follow.

Cheers,

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Thu, 16 Nov 2006 09:57:00 -0800, "Michael K. Edwards" wrote:
> What do you want all of those branches for?  They haven't been
> published to you (that's a human interaction that doesn't go through
> git), so for all you know they're just upstream experiments, and doing
> things with them is probably shooting yourself in the foot.

The same "what do you want them all for" question could be asked of
git-clone which also fetches all available branches. I really just
want to be able to easily watch what's going on in multiple
repositories.

I want to be able to just say "git update" (or whatever) and then be
able to list and browse and explore the stuff locally.

Yes, there's still outside communication that's necessary, but with
the ability to easily track all the remote branches that communication
can be even less formal if I can easily browse and explore things
locally. For example, I might not even know the name of the branch:

Me: Have you pushed a branch for your new work on the frob-widget?
Friend: Yes

And then I can "get fetch" and see "cool-new-frob" come in without
having to be told that name. Or I could have even just fetched
without the specific communication if I was already expecting it for
some reason.

-Carl

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

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Thu, 16 Nov 2006 09:57:00 -0800, "Michael K. Edwards" wrote:
>> What do you want all of those branches for?  They haven't been
>> published to you (that's a human interaction that doesn't go through
>> git), so for all you know they're just upstream experiments, and doing
>> things with them is probably shooting yourself in the foot.
>
> The same "what do you want them all for" question could be asked of
> git-clone which also fetches all available branches. I really just
> want to be able to easily watch what's going on in multiple
> repositories.
>
> I want to be able to just say "git update" (or whatever) and then be
> able to list and browse and explore the stuff locally.
>...

I have no objection to this if it is done in a controlled way
that does not make life more difficult for people who work with
multiple remote repositories.

And I think "git fetch" is the tool for what you want if
enhanced properly; see Linus's message that explaind that we
already have that support in "manually configurable" form but
initializing and maintaining the configuration is currently all
manual and can be improved.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Fri, 17 Nov 2006 00:41:33 -0800, Junio C Hamano wrote:
> I have no objection to this if it is done in a controlled way
> that does not make life more difficult for people who work with
> multiple remote repositories.

That's fine with me. Maybe I didn't explain this well before, but my
desire is exactly for this to work with multiple repositories.

Specifically, what we have in cairo is a "central" shared tree that
many people push to. But we only have two branches there, (one for
bug-fixes only for our stable releases, and one for ongoing
development of new features, and that only of stuff that's well
cooked).

So that tree looks and acts an awful lot like our cvs tree back in the
past. It's often very linear and often fairly boring to look at in gitk.

Meanwhile, all the really interesting stuff happens in personal
repositories where people have their own branches for stuff that is
still getting cooked. This is what's a lot more fun to watch, and
there's a lot more distributed back-and-forth that goes on here as
people collaborate on things. And it's all this kind of collaboration
that cvs never helped with at all, but git has been great.

So, what I want is both "git update" for the central tree. I said we
only have two branches, but that's really only two that are
active---the "stable" branch is actually a new branch after every
major release. It was 1.0 for a while, is 1.2 now, and will be 1.4
later. So I want "git update" to automatically pick those new branches
up as they get created.

Meanwhile, I also want to use "git update" to track everything that
people are working on in the more wild personal trees. So, yes, I do
want "git update" to be able to track lots of remote repositories in a
sane way.

What I have been doing up to this point is a little script I wrote
that does git-ls-remote on the repository I want to track and writes a
.git/remotes file to bring in all their branches. So if I want to see
what behdad is up to, I first refresh his .git/remotes file with my:

	cairo-git-setup-remotes behdad
then:
	git fetch behdad

And I end up with a bunch of branch names with "behdad-" prefixes that
I can explore or blow away if I'm no longer interested, (could have
used a "behdad/" prefix as well).

The first problem we ran into when doing that months ago was that I
don't want any tracking branches to come across this way. Or else I
end up with behdad-origin, he then gets cworth-behdad-origin, ad
nauseum. So we filtered "origin" out, but it will be nice to revisit
this if there's a sane distinction in git now to separate tracking
branches from heads.

> And I think "git fetch" is the tool for what you want if
> enhanced properly; see Linus's message that explaind that we
> already have that support in "manually configurable" form but
> initializing and maintaining the configuration is currently all
> manual and can be improved.

Yes, git-fetch is lovely, and it's the need for manual configuration
that's a problem, (and the mixing up of heads and remote tracking
branches that has been in git historically).

So, yes, I'll definitely look into improving this. I think the details
will involve:

1. Making clone do the --use-separate-remotes behavior by default

2. Taking advantage of that consistently for all branches instead of a
   special master:origin mapping in clone

3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
   there a desire for some other branch-specific section in the config
   file?)

4. Making git-fetch handle the disappearance of a remote branch
   gracefully

5. Adding something like git-fetch --all to allow it to pick up all new
   branches

6. Adding a "git update" that does a fetch for all appropriately
   marked remotes.

On this last point, maybe we do something like:

	update=no|yes|all

in .git/remotes. Then git-clone would set this up with update=all for
origin so git-update would do a "fetch --all" on the origin
repository. Then step 3 above would have to provide for setting this
update option as appropriate.

Anyway, something along those lines perhaps. Any feedback?

-Carl

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

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Fri, 17 Nov 2006, Carl Worth wrote:

> 1. Making clone do the --use-separate-remotes behavior by default

Fully agree.

> 2. Taking advantage of that consistently for all branches instead of a
>    special master:origin mapping in clone

Fully agree, too.

> 3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
>    there a desire for some other branch-specific section in the config
>    file?)

I introduced the remote.<nick>.{url,fetch,push} entries into the config 
with the goal to enhance -fetch to remember the current command line with 
a setting. I was the only one to find that useful.

BTW I still would argue that it is better to write the remote information 
into the config, because you have a saner way to manipulate that from 
scripts than .git/remotes/<nick>.

> 4. Making git-fetch handle the disappearance of a remote branch
>    gracefully

I think a message like "This remote branch no longer exists. Maybe you 
want to use 'git branch -d <branch>' to remove it locally?" should 
suffice.

> 5. Adding something like git-fetch --all to allow it to pick up all new
>    branches

IIRC this idea was rejected, but I would find it useful. Especially with 
what Han-Wen said: you can store the branches you fetch with "git fetch 
--all <nick>" under .git/refs/remotes/<nick>/<branchname>.

> 6. Adding a "git update" that does a fetch for all appropriately
>    marked remotes.
> 
> On this last point, maybe we do something like:
> 
> 	update=no|yes|all
> 
> in .git/remotes. Then git-clone would set this up with update=all for
> origin so git-update would do a "fetch --all" on the origin
> repository. Then step 3 above would have to provide for setting this
> update option as appropriate.

First thought was: it is only useful if you want to track multiple 
repositories. But next thought: if you mark the correct remotes in every 
of your local repositories, you don't have to remember which nick your 
upstream has. Yeah, I like it. But maybe do it as "git fetch --update" to 
avoid more cluttering of the bindir?

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Junio C Hamano]

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

>> 5. Adding something like git-fetch --all to allow it to pick up all new
>>    branches
>
> IIRC this idea was rejected, but I would find it useful. Especially with 
> what Han-Wen said: you can store the branches you fetch with "git fetch 
> --all <nick>" under .git/refs/remotes/<nick>/<branchname>.

With separate-remote layout, this can be done without risk of
tracking refname clashing with local refname, which was the
primary reason for an earlier reluctance.  

While separate-remote layout also solves Carl's "do not want to
track tracking branches remote has" problem, local branch
namespace can have both for-others (not necessarily "public" but
could be "for colleagues") and throwaway branches, so --all is
probably not the right thing to do in most cases.  But I am Ok
with the approach of seeing how well it works out in practice by
doing the simplest "--all" and giving options to restrict it
later.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> I introduced the remote.<nick>.{url,fetch,push} entries into the config 
> with the goal to enhance -fetch to remember the current command line with 
> a setting. I was the only one to find that useful.
> 
> BTW I still would argue that it is better to write the remote information 
> into the config, because you have a saner way to manipulate that from 
> scripts than .git/remotes/<nick>.

I'm *fully* in favor of the remote.<nick>.{url,fetch,push} entries
in the config file.  I've pretty much switched every repository to
that format at this point.

In writing git-gui I'm finding it much, much easier to manage
things through repo-config than to do any mucking around in the
.git/remotes directory.  Yes, the remote files have simple format,
but I can get everything in one "git repo-config --list" pull it
all into a Tcl array and work with it; using .git/remotes means I
have to open the file and read each line too.  :-(

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> What I have been doing up to this point is a little script I wrote
> that does git-ls-remote on the repository I want to track and writes a
> .git/remotes file to bring in all their branches. So if I want to see
> what behdad is up to, I first refresh his .git/remotes file with my:
>
> 	cairo-git-setup-remotes behdad
> then:
> 	git fetch behdad
>
> And I end up with a bunch of branch names with "behdad-" prefixes that
> I can explore or blow away if I'm no longer interested, (could have
> used a "behdad/" prefix as well).

I would suggest refs/remotes/behdad.

> So, yes, I'll definitely look into improving this. I think the details
> will involve:
>
> 1. Making clone do the --use-separate-remotes behavior by default
>
> 2. Taking advantage of that consistently for all branches instead of a
>    special master:origin mapping in clone

This already should be the case if you use separate-remote.  I
haven't run "clone --separate-remote" myself for a long time,
but the design was certainly to make it behave that way.
Specifically, map everything in refs/heads/ at remote to
refs/remotes/$origin/ with corresponding names, one-to-one.

I do not see much reason to change the mapping of master:origin
which is done for the traditional layout.  The traditional
layout is not suitable for your workflow anyway, and that is why
you prefer separate-remote layout for your project, and I fully
agree it would suit you better.

> 3. Enhancing git-fetch (or other) to modify .git/remotes, (or was
>    there a desire for some other branch-specific section in the config
>    file?)
>
> 4. Making git-fetch handle the disappearance of a remote branch
>    gracefully
>
> 5. Adding something like git-fetch --all to allow it to pick up all new
>    branches

These three are easily done for separate-remote layout but at
that point you would not want --all but more powerful --mirror
(or --update if you want to use that word), which goes the whole
nine yards of noticing disappearance of remote branch, making
matching deletion of local tracking branch, updating
.git/remotes, etc.  I've muttered something similar in a nearby
thread; see below.

> 6. Adding a "git update" that does a fetch for all appropriately
>    marked remotes.
>
> On this last point, maybe we do something like:
>
> 	update=no|yes|all
>
> in .git/remotes. Then git-clone would set this up with update=all for
> origin so git-update would do a "fetch --all" on the origin
> repository. Then step 3 above would have to provide for setting this
> update option as appropriate.

I would prefer this to be kept in contrib/; it feels like it is
filling rather very narrow need.

> Anyway, something along those lines perhaps. Any feedback?

I muttered something less elaborate in the nearby thread.

	Message-ID: <7vr6w78b4x.fsf@assigned-by-dhcp.cox.net>
	Message-ID: <7v64dev88t.fsf@assigned-by-dhcp.cox.net>

The part that deals with manual configuration (the last point in
the first message, and the second in message its entirety) is
something your workflow would not need nor want to worry about,
but I think it is necessary for different ref namespace layouts
and different workflows.  I think the automatable part (the
first two points in the "sensible thing to do" list in the first
message) is very relevant to what you talked about in your
message.

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 14:52:32 -0800
Carl Worth <cworth@cworth.org> wrote:

> The real fix is to stop glossing over git-merge and just give it a
> usable syntax.

Agreed 100%   There's just no good reason to hide the user level
merge command inside of pull.

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Sean <seanlkml@sympatico.ca> wrote:
> On Wed, 15 Nov 2006 14:52:32 -0800
> Carl Worth <cworth@cworth.org> wrote:
> 
> > The real fix is to stop glossing over git-merge and just give it a
> > usable syntax.
> 
> Agreed 100%   There's just no good reason to hide the user level
> merge command inside of pull.

So what about making git-merge take a -m "msg" argument to supply
the commit message, in which case it does the current behavior
(and thus git-pull needs to change to supply -m); and then make
git-merge without any -m parameter invoke "git pull . $@" ?

A minor tweak to both apps, a minor breakage to git-merge, but one
that I think anyone who invokes it by hand today would find sane
(using -m like we do elsewhere) and since the vintage of both
git-pull and git-merge should always match shouldn't break anyone
who uses git-pull today.

-- 

Re: Cleaning up git user-interface warts

[Richard CURNOW]

* Shawn Pearce <spearce@spearce.org> [2006-11-15]:
> 
> So what about making git-merge take a -m "msg" argument to supply
> the commit message, in which case it does the current behavior
> (and thus git-pull needs to change to supply -m); and then make
> git-merge without any -m parameter invoke "git pull . $@" ?

Sounds good to me.

When I'm merging in my own projects, I currently always use merge
(possibly preceded by fetch) rather than pull.  Why?  Because I don't
want my history full of commit messages like

Merge branch "trial_hack" from "../scratch_dir_with_silly_name"

In contrast to Linus's case of wanting to record where the remote merge
came from, I expressly don't want to record that - I want the merge
commit to describe conceptually what was being merged with what.

OK, I could use probably use pull with --no-commit, but I've already
trained my fingers to type out the merge syntax.  They'd be happier with
'git merge -m "Merge feature foo with fixes for bar" bar" though.

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Richard CURNOW wrote:

> In contrast to Linus's case of wanting to record where the remote merge
> came from, I expressly don't want to record that - I want the merge
> commit to describe conceptually what was being merged with what.
> 
> OK, I could use probably use pull with --no-commit, but I've already
> trained my fingers to type out the merge syntax.  They'd be happier with
> 'git merge -m "Merge feature foo with fixes for bar" bar" though.

For the moment, if you forget --no-commit, you can always do a "git-commit 
--amend" -- even with merges.

Hth,
Dscho

Re: Cleaning up git user-interface warts

[Jerome Lovy]

On Wed, 15 Nov 2006, Carl Worth wrote:
> Well, one of the problems is that with current git I can teach, (and I
> have), that there's a conceptual:
> 
> 	pull = fetch + merge
> 
> But then shortly after I have to teach an interface notion:
> 
> 	merge = pull .
> 
> So there's this goofy circular notion that people end up with
> mentally. If we fix it so that a local merge really is performed with
> "git merge <branch>" instead of "git pull . <branch>" then teaching
> pull=fetch+merge really is a lot easier.

On a conceptual level, can we not perhaps explain that if

	pull = fetch + merge

then

	merge = pull - fetch

and that the latter (pull - fetch) happens to be expressed with the 
interface as 'git pull .' ?

My 2 cents.
Jérôme

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 12:40:43PM -0800, Linus Torvalds wrote:
> And yes, this is why you should NOT try to use the same naming as "hg", 
> for example. Last I saw, hg still didn't even have local branches, To 
> mercurial, repository == branch, and that's it. It was what I came from 
> too, and I used to argue for using git that way too. I've since seen the 
> error of my ways, and git is simply BETTER. 

Actually, that's not true.  Mercurial has local branches, just as git
does.  Some people choose not to *use* this particular feature, and
use the BK style repository == branch, but that's mainly because it's
conceptually easy for them, and a number of BK refugees are very
happily using Hg.  

It's probably because of the BK refugee population that after you do
an hg pull, it will warn you that you need to do an "hg update" in
order to merge the working directory up to the latest version that was
just pulled --- and this change was made precisely because Hg supports
local branches, and merging with the current branch isn't always the
right thing, unlike with BK.

> And the concept of local branches is exactly _why_ you have to have 
> separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
> (because "pull ." does it for you).

It's just that the semantics are different, and many developers have
to use multiple DSCM's, depending on what project they happen to be
developing on.  So the reality is that there are people who have to
use bzr, git, and hg, all at the same time.  And while eventually
newbies will figure out and remember that "git pull ." == "merge", the
naming is simply confusing, that's all.  (What does "pull" have to do
with "merge"?  It's not at all obvious.)  

For somoene who uses git full-time, and to the exclusion of all other
systems, I'm sure it's not a problem at all.
	

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Theodore Tso wrote:
> On Wed, Nov 15, 2006 at 12:40:43PM -0800, Linus Torvalds wrote:
>> And yes, this is why you should NOT try to use the same naming as "hg", 
>> for example. Last I saw, hg still didn't even have local branches, To 
>> mercurial, repository == branch, and that's it. It was what I came from 
>> too, and I used to argue for using git that way too. I've since seen the 
>> error of my ways, and git is simply BETTER. 
> 
> Actually, that's not true.  Mercurial has local branches, just as git
> does.  Some people choose not to *use* this particular feature, and
> use the BK style repository == branch, but that's mainly because it's
> conceptually easy for them, and a number of BK refugees are very
> happily using Hg.  
> 
> It's probably because of the BK refugee population that after you do
> an hg pull, it will warn you that you need to do an "hg update" in
> order to merge the working directory up to the latest version that was
> just pulled --- and this change was made precisely because Hg supports
> local branches, and merging with the current branch isn't always the
> right thing, unlike with BK.
> 
>> And the concept of local branches is exactly _why_ you have to have 
>> separate "fetch" and "pull", but why you do _not_ need a separate "merge" 
>> (because "pull ." does it for you).
> 
> It's just that the semantics are different, and many developers have
> to use multiple DSCM's, depending on what project they happen to be
> developing on.  So the reality is that there are people who have to
> use bzr, git, and hg, all at the same time.  And while eventually
> newbies will figure out and remember that "git pull ." == "merge", the
> naming is simply confusing, that's all.  (What does "pull" have to do
> with "merge"?  It's not at all obvious.)  
> 
> For somoene who uses git full-time, and to the exclusion of all other
> systems, I'm sure it's not a problem at all.


It seems we should, cheaply, be able to avoid a large part of the 
confusion by

* Mentioning git-fetch before git-pull in all documentation newborn 
gitizens are likely to come across. Most git-users aren't Linus, and for 
every successful project the maintainers are outnumbered 100 to 1 by the 
contributors. Those projects successful *because* maintainers are 
heavily outnumbered so we should make it easier for contributors by 
teaching them the right things from the start and possibly have a 
separate man-page for maintainer (git-{maintainer,developer} man-pages, 
anyone?).
* Creating "git update" which might possibly be an internal alias to 
"git pull", except that it should read .git/remotes/* by default unless 
a specific remotes-file is specified.
* Renaming git-merge to git-merge-driver
* Implementing a git-merge that actually does what its name implies, 
possibly by making it an internal alias to pull, but with these differences:
   - It always merges into your current branch.
   - It understands "git merge branch" as well as "git merge . branch".

This is just the very low-hanging fruit. If we take these steps and let 
things cool down a bit, it would probably be proper to take a fresh look 
at this in a couple of months.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Andreas Ericsson wrote:
> 
> * Mentioning git-fetch before git-pull in all documentation newborn gitizens
> are likely to come across.

However, I also think it might make sense to talk about the _simple_ form 
of "git pull" first.

The form I use is actually a lot simpler (conceptually) than the "short" 
form.

When you do

	git pull <reponame> <branchname>

there are very few things that can confuse you (although trying to do it 
without a current branch at all is apparently one such thing ;). 

There are no local branches to worry about, and there aren't any issues 
about what the default repository or branchname on the remote side would 
be either.

So in many ways, if you use this format, you simply never have to worry. 
You may have to _type_ a bit more, so it's not the short or concise 
format, but it sure is the _simple_ format. There simply isn't anything to 
be confused about.

And yes, I actually tend to use this even for project that I don't develop 
on, partly because the defaults for the short and concise formats are bad. 
For example, I follow the "modesetting" branch on the xorg intel graphics 
driver tree, and because I'm always on that branch, what I do is

	git pull origin modesetting

which works correctly (while "git pull" would _not_ have done the right 
thing: it would have picked the right repository, but it would have picked 
the "master" branch of that repository, not the "modesetting" branch).

And notice how I don't do _any_ development there, I just follow that 
branch. The "merge" will obviously always be a fast-forward, but that's 
exactly what I want. 

> Most git-users aren't Linus, and for every successful project the 
> maintainers are outnumbered 100 to 1 by the contributors.

Well, as mentioned, I think even for non-developers, doing pulls with 
explicit branchnames is actually perfectly sane.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Thu, 16 Nov 2006 08:30:55 -0800 (PST), Linus Torvalds wrote:
> The form I use is actually a lot simpler (conceptually) than the "short"
> form.
>
> When you do
>
> 	git pull <reponame> <branchname>

Yes, that's what the user almost always wants. The UI problem here is
that the conceptually simpler form is syntactically longer, (which
means users aren't likely to find it).

So if we can just get <reponame> and <branchname> to default
correctly, (based on the current branch name, and clone/fetch/pull
history), then the conceptually simple form ends up syntactically
simple as "git pull".

And I definitely don't have any problem with that. I'd love to be able
to teach that kind of simple thing to new users.

> driver tree, and because I'm always on that branch, what I do is
>
> 	git pull origin modesetting
...
> Well, as mentioned, I think even for non-developers, doing pulls with
> explicit branchnames is actually perfectly sane.

The behavior is sane, but having to always type the branch name
specifically because it never changes... that's a user-interface bug.

This is a good example of the kind of thing I wanted to hit when
starting this thread. I don't think there are any big conceptual
changes needed in git to make it easier for new users. But there are
little things that are problems that really should be fixed. Wouldn't
it be great to have the following exchange:

	User: How do I track on-going development in a branch?
	Master: Use "git pull"

Rather than:

	User: How do I track on-going development in a branch?
	Master Use "git pull origin <name-of-branch-you-are-already-on>"

?

-Carl

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

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Carl Worth wrote:
>
> On Thu, 16 Nov 2006 08:30:55 -0800 (PST), Linus Torvalds wrote:
> > The form I use is actually a lot simpler (conceptually) than the "short"
> > form.
> >
> > When you do
> >
> > 	git pull <reponame> <branchname>
> 
> Yes, that's what the user almost always wants. The UI problem here is
> that the conceptually simpler form is syntactically longer, (which
> means users aren't likely to find it).

Yeah. 

And this is something I absolutely agree with. Our default branches for 
"pull" are horrible. You can "fix" it, but you can only fix it by adding 
_explicit_ branches to your .git/config file by hand, so I don't think 
that's actually a real fix at all. We should just fix the default (where 
even a "I don't know what branch you want" _error_ would be preferable 
over the current situation).

Along with the "git checkout <tag>" thing, I think these two things are 
definitely worth just fixing.

> The behavior is sane, but having to always type the branch name
> specifically because it never changes... that's a user-interface bug.

Yeah. Each branch should

 (a) have a "default source" initialized on the initial "clone"

 (b) have a way to set the source afterwards

 (c) error out if you do just a "git pull" or "git pull remotename" if 
     there is no default branch for the current local branch for that 
     remote.

We actually have (b) in a weak form right now ("weak" because it requires 
you to manually edit the config file: we've got the mechanism, but not a 
nice UI for it), but (a) and (c) are just broken.

And yeah, we should allow pulling into a branch that hasn't been 
initialized.

Re: Cleaning up git user-interface warts

[Sean]

On Thu, 16 Nov 2006 09:30:47 -0800 (PST)
Linus Torvalds <torvalds@osdl.org> wrote:

> Yeah. Each branch should
> 
>  (a) have a "default source" initialized on the initial "clone"
>
> (b) have a way to set the source afterwards
>
> (c) error out if you do just a "git pull" or "git pull remotename" if 
>     there is no default branch for the current local branch for that 
>     remote.

This would be _great_.  You just shouldn't have to hack at the
.git/config file to get reasonable default sources after a clone.
Or even for that matter after fetching a new branch into an
existing repo.

Re: Cleaning up git user-interface warts

[Anand Kumria]

On Wed, 15 Nov 2006 11:18:36 -0800, Linus Torvalds wrote:

> On Wed, 15 Nov 2006, Andy Parkins wrote:
>>
>> On the one hand you're arguing that git syntax is easy to learn, and on the 
>> other that no one will be able to learn a new syntax just as easily.
> 
> I'm saying that people who are new to git will _have_ to learn new 
> concepts ANYWAY.
> 
> I don't think the naming is the hard part. 

It isn't - the unexpectedness of what happens is.

I've started by teaching how to do stuff locally, then "pushing" it out to
others (me).  All the while being able to point out how this is either all
local, or sends stuff (without any local modifications) to others.

Come up to 'pull' and ere you have to point out that not only will you get
the remote changes but they are also merged into your repository. On the
wrong branch?

Too bad.

The problem with git-pull behaving illogically drove me to look at cogito
(an aside, perhaps cg-throw should be the corrollary to cg-fetch?)
instead. Alas it has problems with a cogito branch not being something you
can mentally map back to a git branch.

> But I bet people don't teach it that way. They _start_ by teaching "pull". 
> Right?

Nope.

Anand

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

>> But trying to rename "pull" (or the "git" name itself) is just going to
>> cause more confusion than you fix.
>
> I don't think so.  Mainly because the proposed new git pull would be a subset 
> of the existing git pull.  It's not changing function, it's just reducing in 
> function.

We usually use the word "regression" to refer to that kind of
change.

I think it makes a lot of sense having command x that does
essentially the same thing as the current fetch but with more
usability enhancements and more convention as built-in defaults,
and another command y that does what the current 'pull .' does
but with more usability enhancements and more convention as
built-in defaults.  I agree that kind of UI improvements would
make it easier to explain to new people.  Calling x "pull",
however, breaks the existing users and documents, and causes
confusion.  I really do not think you can argue with that.

That's why we are talking about using an uncontaminated word
"get".  I think it is a good effort.

>> aren't that complicated. There's no reason to rename them. We do have
>> other problems:
>
> That there are other problems doesn't negate these problems.

And I think Linus is right in pointing out that there are other
problems that are equally or even more pressing than _renaming_
to break things for existing users.

I personally do not think the current fetch/pull confusing, and
I do see real downside in _renaming_ them, but I am open to the
current get/put discussion because I think the new commands'
semantics may be designed to match newcomers' expectation better
(it's to match tools to newcomers instead of teaching them the
new language of the land) and I do not think that approach would
break existing users and documents.

For some things "matching tools to newcomers" would not really
work, though.  For example, I do not think you can get away with
hiding index forever if you want your users to do real work in a
workflow that involves merging and cherry picking.

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 10:03:18AM -0800, Linus Torvalds wrote:
> So the reason for using "git pull" is
> 
>  - bk did it that way, and like it or not, bk was the first usable 
>    distributed system. hg is totally uninteresting.

Yes, "bk pull" had an implied merge.  But, the reason why bk pull was
never really a problem with Bitkeeper is because it didn't really have
support for multiple branches active within the same repository ---
what Larry called "lines of development".  Or rather, Larry started
down the path of implementing lines of development, and then never
fully supported it, mainly because making it easy for people to use
was the tricky part.   

So with Bitkeeper, with "bk pull" there was never any question about
which branch ("line of development") you would be merging into after
doing a "bk pull", since there was only one LOD, and given that BK had
the rule that a within a LOD only one tip was allowed, a "bk pull"
_had_ to do do a merge operation.   

The moment you start supporting multiple unmerged tips in a repository
i.e., branches, it raises the question, "which branch should the pull
operation merge onto"?  And git's answer, "the current branch", is
often not the right one.  *That's* why always doing a merge isn't
always the right answer, and so in the git world, people are told, use
"git fetch" instead, and in the hg world, "hg pull" doesn't do the
merge.  IMO, it's a fundamental result of the fact that both git and
hg have chosen to support mulitple LOD's, whereas BK punted on the
concept.

If you are operating on your local development branch, the reality is
that merging is probably not the right answer in the general case,
which is why the hg world have omitted doing the merge.  And by
telling people, use "git fetch" instead, that's also an implicit
admission that merging onto the current branch is often not the Right
Thing.

The problem is that "pull" is a very evocative word, especially given
the existence "push", and so in the git world we are reduced to
telling people, "you really don't want to use pull, trust me".  

Is this a major issue?  Not really; I can think of a number of other
issues that make git hard to learn, and why hg has a more gentle
learning curve, and the "don't use pull" is probably a relatively
minor annoyance in the grand scheme of things.

If people are looking for a simple way out, maybe it would be enough
to have an option where if "git pull" is called from an interactive
terminal, and the "novice user" option is enabled, "git pull" returns
a warning message, "You probably want to use 'git fetch' instead; are
you sure?"  If people are saying that we shouldn't be teaching "git
pull" until fairly late in the game, maybe we should have a way of
discouraging novices from using, simply because they they are used to
seeing "pull" from other distributed SCM's.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> So with Bitkeeper, with "bk pull" there was never any question about
> which branch ("line of development") you would be merging into after
> doing a "bk pull", since there was only one LOD, and given that BK had
> the rule that a within a LOD only one tip was allowed, a "bk pull"
> _had_ to do do a merge operation.   

I've never used Bk and I really appreciate your comments here.

> If you are operating on your local development branch, the reality is
> that merging is probably not the right answer in the general case,

I agree, but I wonder why you are pulling/fetching (with or
without merge) if you are operating on your local development
branch (implying that you are in the middle of something else).

> ...  And by
> telling people, use "git fetch" instead, that's also an implicit
> admission that merging onto the current branch is often not the Right
> Thing.
>
> The problem is that "pull" is a very evocative word, especially given
> the existence "push", and so in the git world we are reduced to
> telling people, "you really don't want to use pull, trust me".  

I would rather say "use 'git branch' to make sure if you are
ready to merge".  Who teaches not to use "git pull"?

> If people are looking for a simple way out, maybe it would be enough
> to have an option where if "git pull" is called from an interactive
> terminal, and the "novice user" option is enabled, "git pull" returns
> a warning message,

I have to disagree with this.  In the simplest CVS-like central
repository with single branch setup in which many "novice users"
start out with, there is almost no need for "git fetch" nor
tracking branch.  You pull, resolve conflicts, attempt to push
back, perhaps gets "oh, no fast forward somebody pushed first",
pull again, then push back.  So I am not sure where "you really
do not want to use pull.  trust me" comes from.

It is a different story for people who _know_ git enough to know
what is going on.  They may be using multiple branches and
interacting with multiple remote branches, and there are times
you would want fetch and there are other times you would want
pull.  But for them, I do think the suggestion would never end
with "trust me" -- they would understand what the differences
are.

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Junio C Hamano <junkio@cox.net> writes:

> I would rather say "use 'git branch' to make sure if you are
> ready to merge".  Who teaches not to use "git pull"?

We do that for Wine. The problem is that we recommend using git-rebase
to make it easier for occasional developers to keep a clean history,
and rebase and pull interfere badly.

The result is that we recommend always using fetch+rebase to keep up
to date, but this is confusing many people too, because git-fetch
appears to do a lot of work yet leaves the working tree completely
unchanged, and git-rebase doesn't do anything (since in most cases
they don't have commits to rebase) but has an apparently magical
side-effect of updating the working tree.

Ideally it should be possible to have git-rebase do the right thing
even if the branch has been merged into; then we could tell people to
always use git-pull, and when they get confused by seeing merges in
their history have them do a git-rebase to clean things up.

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 12:34:27PM CET, Alexandre Julliard wrote:
> Junio C Hamano <junkio@cox.net> writes:
> 
> > I would rather say "use 'git branch' to make sure if you are
> > ready to merge".  Who teaches not to use "git pull"?
> 
> We do that for Wine. The problem is that we recommend using git-rebase
> to make it easier for occasional developers to keep a clean history,
> and rebase and pull interfere badly.

How do those developers submit their changes? Do they push? If they do,
git-rebase can be saving one merge at most, and the merge is actually a
good thing (someone should write some nice standalone writeup about
that).

If they don't have push access and maintain their patches locally until
they get accepted, perhaps it would be far simpler for them to use
StGIT?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Petr Baudis <pasky@suse.cz> writes:

> How do those developers submit their changes? Do they push? If they do,
> git-rebase can be saving one merge at most, and the merge is actually a
> good thing (someone should write some nice standalone writeup about
> that).

No, they use git-format-patch and mail them in.

> If they don't have push access and maintain their patches locally until
> they get accepted, perhaps it would be far simpler for them to use
> StGIT?

For regular developers, sure. But regular developers will need to
properly understand the git model anyway, and then they will able to
make sense even of the standard git commands ;-)  The problem is that
there isn't a smooth progression to that point.

At first, a user will simply want to download and build the code, and
for that git-pull works great, it's a one-stop command to update their
tree.

Then after a while the user will fix a bug here and there, and at that
point git-rebase is IMO the best tool, it's reasonably easy to use,
doesn't require learning other commands, and once the patch is
accepted upstream it nicely gets the tree back to the state that the
user is familiar with.

The problem is that rebase doesn't work with pull, so the user needs
to un-learn git-pull and start using git-fetch; it's to avoid this
that we recommend using git-fetch from the start, which is unfortunate
since it makes things harder for beginners.

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Alexandre Julliard wrote:

> Junio C Hamano <junkio@cox.net> writes:
> 
>> I would rather say "use 'git branch' to make sure if you are
>> ready to merge".  Who teaches not to use "git pull"?
> 
> We do that for Wine. The problem is that we recommend using git-rebase
> to make it easier for occasional developers to keep a clean history,
> and rebase and pull interfere badly.

What about proposed (and I think not accepted) merge strategy
"rebase" (formerly called "subordinate" or something like that)?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Alexandre Julliard]

Jakub Narebski <jnareb@gmail.com> writes:

> Alexandre Julliard wrote:
>
>> Junio C Hamano <junkio@cox.net> writes:
>> 
>>> I would rather say "use 'git branch' to make sure if you are
>>> ready to merge".  Who teaches not to use "git pull"?
>> 
>> We do that for Wine. The problem is that we recommend using git-rebase
>> to make it easier for occasional developers to keep a clean history,
>> and rebase and pull interfere badly.
>
> What about proposed (and I think not accepted) merge strategy
> "rebase" (formerly called "subordinate" or something like that)?

That sounds very interesting. Has it ever been implemented, or only
discussed?

-- 
Alexandre Julliard

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Alexandre Julliard wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>> Alexandre Julliard wrote:
>>> Junio C Hamano <junkio@cox.net> writes:
>>> 
>>>> I would rather say "use 'git branch' to make sure if you are
>>>> ready to merge".  Who teaches not to use "git pull"?
>>> 
>>> We do that for Wine. The problem is that we recommend using git-rebase
>>> to make it easier for occasional developers to keep a clean history,
>>> and rebase and pull interfere badly.
>>
>> What about proposed (and I think not accepted) merge strategy
>> "rebase" (formerly called "subordinate" or something like that)?
> 
> That sounds very interesting. Has it ever been implemented, or only
> discussed?

There was some implementation with warts

  http://thread.gmane.org/gmane.comp.version-control.git/30068
  Message-Id: <20061025155009.GD5591@parisc-linux.org>

which didn't got corrected and resent.
-- 
Jakub Narebski

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Wed, Nov 15, 2006 at 08:21:36PM -0800, Junio C Hamano wrote:
> Theodore Tso <tytso@mit.edu> writes:
> > So with Bitkeeper, with "bk pull" there was never any question about
> > which branch ("line of development") you would be merging into after
> > doing a "bk pull", since there was only one LOD, and given that BK had
> > the rule that a within a LOD only one tip was allowed, a "bk pull"
> > _had_ to do do a merge operation.   
> 
> I've never used Bk and I really appreciate your comments here.
> 
> > If you are operating on your local development branch, the reality is
> > that merging is probably not the right answer in the general case,
> 
> I agree, but I wonder why you are pulling/fetching (with or
> without merge) if you are operating on your local development
> branch (implying that you are in the middle of something else).

Well, when I was using BitKeeper, I never would.  Bitkeeper has what
Linus calls the broken "repository == branch" model.  So normally I
would have one repository where I would track the upstream branch, and
only do bk pull into that branch.  I would do my hacking in another
repository (i.e., branch), and periodically keep track wha was going
on in mainline by cd'ing to the mainline repository and doing the bk
pull there.  

The challenge when you put multiple branches into a single repository,
is you have to keep track of which branch you happen to be in.  In the
BK world, this was obvious because it would show up in my shell
prompt:

<tytso@candygram>       {/usr/src/linux-2.6}
2% 

(OK, obviously I'm in the Linux 2.6 upstream repository)

In a system where you need to keep track of what branch you are in via
an SCM-specific local state information, it's easy to get confused and
do a pull when you are in the "wrong" branch, or while you have local
state in your working directory.   

What I currently do (and I'm sure I'm being really horrible and need
to be say 100 "Hail, Linus"'es for penance for not adhering staying in
the one true distributed state of grace) is that I keep an entirely
separate Linux 2.6 git repository just to make sure I never get
confused about what branch I might happen to be in when I do the "git
pull" --- and yeah, I could have used "git fetch", but 3+ years of BK
usage plus Hg usage is hard to get away from.  I'm sure this is where
Linus would say that use of BK and Hg, causes permanent brain damage,
ala's Dijkstra's ofted quoted comment about use of Basic inducing
brain damage....

> I have to disagree with this.  In the simplest CVS-like central
> repository with single branch setup in which many "novice users"
> start out with, there is almost no need for "git fetch" nor
> tracking branch.  You pull, resolve conflicts, attempt to push
> back, perhaps gets "oh, no fast forward somebody pushed first",
> pull again, then push back.  So I am not sure where "you really
> do not want to use pull.  trust me" comes from.

I think the problem is the people who have had years of BK or Hg
experience.  Maybe it's more of a documentation problem; perhaps a
"git for BK" or "git for Hg" users is what's needed.  The problem
though is that while use of BK is definitely legacy, there are going
to be a lot of people who need to use both BK and Hg.   

> It is a different story for people who _know_ git enough to know
> what is going on.  They may be using multiple branches and
> interacting with multiple remote branches, and there are times
> you would want fetch and there are other times you would want
> pull.  But for them, I do think the suggestion would never end
> with "trust me" -- they would understand what the differences
> are.

Well, I think this is where git's learning curve challenges are.  Yes,
for users that are doing the stupidest, most simplistic usage models,
git is quite easy to use.  And I am willing to grant that for people
who are using the deepest, most complicated and most distributed
development, who understand multiple branches and the index, and all
of the deep git plumbing, there's also no problem.

The challenge is in between; to use a car analogy, git has a great
automatic transmision, and an extremely powerful "racing clutch".  But
for someone where the automatic transmission isn't good enough, when
as they start to learn how to use the manual transmission, git's
extremely touchy "racing clutch" is much more difficult master ---
especially in comparison to people who have learned to drive other,
more pedestrian "standard transmission" cars.  So people who try to
use git's racing clutch keep stalling out the car, and some give up in
frustration.

And maybe the problem is one that should be addressed only by lots of
training, but at the moment, that's the reason why I believe a number
of projects have chosen Hg instead of git; they need more than the
"stupid simple" git usage, but if they don't need the extreme power of
git, Hg is simpler for people to learn how to use.  The problem, of
course, comes when later on, the project finds out they really want
git's power, and now they have to deal with the repository conversion
as well as retraining their entire development community.

But hey, maybe this isn't a problem the git community wants to solve;
clearly git is optimized for the Linux kernel development, and maybe
it's too much to ask that it also work well for somewhat less
extremely distributed development models.  But in any case, that's why
I chose Hg for e2fsprogs.  At the time when I made my choice, git was
just too painful to learn how to use its more esoteric features, and
Hg was much closer to BK's model.  (Since then, Hg has added more
functionality, including better multiple branches in a repository
support, and it's gotten more complicated, but it's still much simper
to teach someone how to use Hg than git.)

Regards,

Re: Cleaning up git user-interface warts

[Theodore Tso]

On Thu, Nov 16, 2006 at 11:07:00AM -0500, Theodore Tso wrote:
> I think the problem is the people who have had years of BK or Hg
> experience.  Maybe it's more of a documentation problem; perhaps a
> "git for BK" or "git for Hg" users is what's needed.  The problem
> though is that while use of BK is definitely legacy, there are going
> to be a lot of people who need to use both BK and Hg.   

Err, what I meant to say is that there are going to be a lot of people
who will need to simultaneously use both git and Hg.

Re: Cleaning up git user-interface warts

[Sanjoy Mahajan]

The car analogy is excellently clear.

> they need more than the "stupid simple" git usage, but if they don't
> need the extreme power of git, Hg is simpler for people to learn how
> to use.

As a 80%-hg/20%-git user, I'm curious what features of git you had in
mind, so I know where to look as I wander up the git learning curve.

My experience with the git user interface, for what it's worth, is
that I never quite get the conceptual model crystal clear enough in my
head. So it won't stay for long enough for me to progress up the
learning curve and retain the gains.  I move up a bit, but the gain
soon evaporates and I backslide, and then just hack my way through it.

I found hg's conceptual model very easy to learn, almost as if I don't
have to remember anything.  Maybe that simplicity comes at a price,
whence my question at the start about the extreme-power features of
git.

-Sanjoy

`Never underestimate the evil of which men of power are capable.'

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Sanjoy Mahajan wrote:

> The car analogy is excellently clear.
> 
>> they need more than the "stupid simple" git usage, but if they don't
>> need the extreme power of git, Hg is simpler for people to learn how
>> to use.
> 
> As a 80%-hg/20%-git user, I'm curious what features of git you had in
> mind, so I know where to look as I wander up the git learning curve.
> 
> My experience with the git user interface, for what it's worth, is
> that I never quite get the conceptual model crystal clear enough in my
> head. So it won't stay for long enough for me to progress up the
> learning curve and retain the gains.  I move up a bit, but the gain
> soon evaporates and I backslide, and then just hack my way through it.
> 
> I found hg's conceptual model very easy to learn, almost as if I don't
> have to remember anything.  Maybe that simplicity comes at a price,
> whence my question at the start about the extreme-power features of
> git.

As I never used Mercurial (hg), only read a bit about it and discussed on
#revctrl, I cannot say what features git has that hg has not, but I can
tell what powerfull git features differ from other SCM.

First, usually in other SCM the concept of branch is closely tied to the
concept of repository, perhaps allowing to share storage between branches
on the same local filesystem (on the same machine). In git, repository
holds DAG, the graph of revisions (of versions). Branches are "only" ways
to access this graph, and to extend it of the new commits. This makes git
more powerfull, but also perhaps unnecessary complicated if you deal with
single-branch repositories, or few-branch case. Additionally this
"complication" makes very clean model of repository - but you have to
understand it...

Second, the index. One might think that it is performance hack, but it
allows for commiting changes piece by piece and, what is more important,
a place form making merge in. Cogito (alternate Git UI/porcelain) tries to
hide index. By the way, I wonder how hg does merges without index to
provide place where do merges in...

Third, explicit/on-demand packing. This allows for the most (I think)
compression of all SCMs, and for the wire format to be the same as on-disk
format (with the addition that you can send thin packs on wire). As of now
no porcelain tries to hide it, although with the latest work allowing for
historical packs it would be easy to add this without significantly
affecting preformance.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
>  - git itself has now done it that way for the last 18 months, and the 
>    fact is, the people _complaining_ are a small subset of the people who 
>    actually use git on a daily basis and don't complain.


that's not a good argument; the set of git users is a small subset of 
those that looked at git, and dismissed it because they couldn't wrap 
their heads around it.   It's worth trying to get those on board by 
fixing the annoying little issues that have popped up in this thread. 
The technical base for GIT is excellent, and the only reason for not 
using it is its arcane interface.

A version control system is often only tangentially related to the real 
work that needs to be done, so the incentive to learn it well is small, 
   and a steep learning curve only makes it worse.

FWIW, I regularly mess up with the differences between fetching, pulling 
and merging.  In particular, having to do a two step process to get 
remote changes in,

   git pull url-to-server master:master
      ..error message about not being a fast-forward..

   git pull --update-head-ok url-to-server master:master
      ..still an error message about update not being a fast-forward..

       (sigh)

   git pull url-to-server master:scrap-branch

   git pull . scrap-branch:my-current-branch

       (make mental note of deleting scrap-branch)


-- 

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> FWIW, I regularly mess up with the differences between fetching, pulling 
> and merging.  In particular, having to do a two step process to get 
> remote changes in,
> 
>    git pull url-to-server master:master
>       ..error message about not being a fast-forward..
> 
>    git pull --update-head-ok url-to-server master:master
>       ..still an error message about update not being a fast-forward..

What about:

     git pull --update-head-ok url-to-server +master:master

(or --force, but be careful with that one)?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> FWIW, I regularly mess up with the differences between fetching,
> pulling and merging.  In particular, having to do a two step process
> to get remote changes in,
>
>   git pull url-to-server master:master
>      ..error message about not being a fast-forward..
>
>   git pull --update-head-ok url-to-server master:master
>      ..still an error message about update not being a fast-forward..
>
>       (sigh)

Sigh indeed.

Why don't you do the simple and obvious

	git pull url master

or "git pull url" if you already know the master is the branch
you are interested in.

The more advanced form of using tracking branches are there and
documentation talks about them for completeness but that does
not mean you have to use it.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
>> FWIW, I regularly mess up with the differences between fetching,
>> pulling and merging.  In particular, having to do a two step process
>> to get remote changes in,
>>
>>   git pull url-to-server master:master
>>      ..error message about not being a fast-forward..
>>
>>   git pull --update-head-ok url-to-server master:master
>>      ..still an error message about update not being a fast-forward..
>>
>>       (sigh)
> 
> Sigh indeed.
> 
> Why don't you do the simple and obvious
> 
> 	git pull url master

It is not all evident from the git-pull man-page that this is the 
obvious and most common usage.

> or "git pull url" if you already know the master is the branch
> you are interested in.

Because I usually replace verbose commands with shortcuts only when I 
understand exactly what the shortcut is.

To me it's very unlogical that

   master:current-branch

doesn't work, but

   master:

does work, and does what I'd expect

   master:current-branch

to do. Interestingly, doing

   pull ..url.. master:HEAD

also doesn't merge into the current branch, but rather creates a bogus 
refs/heads/HEAD

I use the remote:local syntax, because I started using GIT in scripted 
compiles from copied branches of remote repositories. There the explicit 
remote:local statements are necessary because there is no default branch.

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> Junio C Hamano escreveu:
>>...
>> Sigh indeed.
>>
>> Why don't you do the simple and obvious
>>
>> 	git pull url master
>
> It is not all evident from the git-pull man-page that this is the
> obvious and most common usage.

In the git user poll a few months ago, many people recommended
"everyday git" as a good cheat sheet, and indeed it does not
talk anything about directing the underlying git-fetch to
manipulate tracking branches by giving explicit refspec pairs to
git pull.  You are obviously tripped by both the overeager
manpage (but manpage should strive to be complete so you cannot
really blame it) and less than optimally organized tutorial
style documents.

I myself do prefer, when learning a new tool, to use longhand
until I understand the shorthand, but that attitude requires a
true commitment to learn the tool, and most people do not go
that route.  Tutorial style documents tend to give the commonly
used shorthand first for that exact reason.

Shorthand to give only the branch name to fetch and merge
immediately without using a tracking branch is equivalent to
longhand "branch:" as you found out, so if that was what was
desired then people with the attitude "before understanding what
longhand does I prefer using shorthand" like myself and you
would have liked to learn "git pull url branch:" notation from
Tutorial.  But I think we _are_ minority.  People would not want
to see that seemingly useless colon there.

> To me it's very unlogical that
>
>   master:current-branch
>
> doesn't work,

That shows that you did not understand what fetch does.  Maybe
you do now, but a very natural consequence of directing fetch to
update tracking branches with the colon notation is:

 - "pull url master:master", while on master, is almost always
   wrong and not something you would want to do, ever.

   "fetch --update-head-ok url +master:master; reset --hard HEAD"

   may make sense but never "pull".

> I use the remote:local syntax, because I started using GIT in scripted
> compiles from copied branches of remote repositories. There the
> explicit remote:local statements are necessary because there is no
> default branch.

If you perhaps wanted to ask "is there a better way to do what
I've been doing?", then I am willing to think with you to come
up with an answer.  Unfortunately, however, I do not understand
the above paragraph, so I'd refrain from commenting on it in
this response.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

(not changing what I said but editorial)
> I myself do prefer, when learning a new tool, to use longhand
> until I understand the shorthand, but that attitude requires a
> true commitment to learn the tool, and most people do not go
> that route.  Tutorial style documents tend to give the commonly
> used shorthand first for that exact reason.

Eh, sorry, "prefer to use longhand until I understand what is
going on before using the shorthand" is what I wanted to say.

> Shorthand to give only the branch name to fetch and merge
> immediately without using a tracking branch is equivalent to
> longhand "branch:" as you found out, so if that was what was
> desired then people with the attitude "before understanding what
> longhand does I prefer using shorthand" like myself and you

"prefer not using shorthand", sorry again.

> would have liked to learn "git pull url branch:" notation from
> Tutorial.  But I think we _are_ minority.  People would not want
> to see that seemingly useless colon there.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>
>> Junio C Hamano escreveu:
>>>...
>>> Sigh indeed.
>>>
>>> Why don't you do the simple and obvious
>>>
>>> 	git pull url master
>>
>> It is not all evident from the git-pull man-page that this is the
>> obvious and most common usage.
>
> In the git user poll a few months ago, many people recommended
> "everyday git" as a good cheat sheet, and indeed it does not
> talk anything about ...

Sorry, I must have been very grumpy mood when I wrote the
message (cf. Pasky's utterance on #git a few days ago).  What I
wrote was a bit incoherent, so here is an attempt to clarify.

I should point out that the colon separated refspec pairs you
can give to "pull" was designed with considerable thought; it is
not a convenience hack that we give them to "pull" that "fetches
and merges".  Linus's and Michael's other messages in this
thread may seem to be saying that using tracking branches is not
a kosher way to use git, but I do not think that is a correct
interpretation of their messages.

The workflow that does not use any tracking branches is the
simplest and truly distributed way as Linus says.  The command
recommended in "everyday git" document:

	git pull $url $branchname

is the most natural way to express it, and simplest variant that
you do not have to say anything "colon" in it.

However that does not mean it is a bad practice to use tracking
branches.  Sometimes it is handy to be able to refer to what you
fetched from the remote the last time, possibly which is what
you merged into your branch if that last fetch was done via "git
pull", so that you can later examine its history without your
own development.  For that purpose, you need to store what you
fetched in your local refs/ namespace, and that is what tracking
branches are.

The workflow that fetches to tracking branches and then merges
within local repository as two separate steps loses the true
origin information ("Merge branch 'foo'" vs "Merge branch 'foo'
of git://git.bar.xz/foo.git").  That's the reason why not just
"git fetch" but also "git pull" take the colon separated refspec
pairs to direct git to update the tracking branches when "pull"
happenes.  The longhands are cumbersome to type all the time,
and we have shorthand, both to store URL: and Pull: lines in
remotes/ hierarchy, and also $branchname alone is a shorthand
for saying "${branchname}:", meaning "do not use a tracking
branch to store this".

So you have options to use or not to use tracking branches.
After cloning we happen to default to track all remote branches
with corresponding local tracking branches, but that is only
because may people on the list wanted to make life easier to CVS
migrants where following mostly static set of branches is the
norm ("set" is the static part: I do not mean the branches stay
still) and we wanted to make it easier for them.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:

> Linus Torvalds escreveu:
> >  - git itself has now done it that way for the last 18 months, and the
> > fact is, the people _complaining_ are a small subset of the people who
> > actually use git on a daily basis and don't complain.
> 
> 
> that's not a good argument; the set of git users is a small subset of those
> that looked at git, and dismissed it because they couldn't wrap their heads
> around it. 

And I've said this again, and I'll say it once more: that has basically 
_nothing_ to do with whether you spell "pull" as "pull" or "merge".

The reason people have trouble wrapping their heads around git is because 
they have been braindamaged by CVS and SVN, and just don't understand the 
fairly fundamental new concepts and workflow.

That's totally different from then arguing about stupid naming issues.

Peopel seem to believe that changign a few names or doing other totally 
_minimal_ UI changes would somehow magically make things understandable. I 
claim that isn't so at all. The fact is, git is different from CVS and 
SVN, and git _has_ to be different from CVS and SVN. It has to be 
different because the whole model of CVS and SVN is simpyl fundamentally 
BROKEN.

> It's worth trying to get those on board by fixing the annoying
> little issues that have popped up in this thread.

I claim that those "annoying little issues" are totally made up by people 
who had trouble wrapping their minds about git, and then make up reasons 
that have nothing to do with reality for why that might be so.

Let's face it, you could just alias "merge" to "pull", and it wouldn't 
really change ANYTHING. You'd still have to learn the new model. 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> And I've said this again, and I'll say it once more: that has basically 
> _nothing_ to do with whether you spell "pull" as "pull" or "merge".
>
> The reason people have trouble wrapping their heads around git is because 
> they have been braindamaged by CVS and SVN, and just don't understand the 
> fairly fundamental new concepts and workflow.
> ...
> Let's face it, you could just alias "merge" to "pull", and it wouldn't 
> really change ANYTHING. You'd still have to learn the new model. 

I had a bit different feeling about yesterday's discussion
myself.

If somebody uses git like you do in "truly distributed way", the
current pull behaviour and pull being an operational mirror to
push are natural consequence of the model and concepts, and
there is nothing to fix (modulo "the default merge source per
branch" should be made easier to use).  Renaming the pull to
merge would not make it any easier to use unless the underlying
model is understood, and I fully agree with you on that.

But for people working in a project organized around central
repository in the CVS/SVN fashion, the workflow is quite
different.  CVS does not even let you "fetch" without either
merging (co) or throwing away your work (co -C), and we already
do support that model with:

	git clone
        git pull
        work work work; git commit
        git push
        : oops not fast forward?
        git pull
        resolve work; git commit
	git push

without ever using a local branch, any tracking branch, nor
use of git-fetch.  So we do support both extremes ("truly
distributed" and "not distributed at all") reasonably well.

The trouble starts when the users hear about this wonderful
"distributed" stuff git offers, and try to use it without
understanding the key concepts.  People tend to learn by doing
and there is a leap the user need to make because now they need
to understand branched development, branches and fetching like
you explained if they want to use git the same way as you do.
Once they understand them, then the current set of tools offer
them a simple and very straightforward user interface (the tools
directly reflect the concepts and it is straightforward only
because we are talking about users who understood the concepts).

But we have to admit that this leap may rather be difficult for
people who are used to other models.  Telling them that our
model is different and it is different for a good reason does
not change the fact that the more different something is, the
more difficult to learn it.

I suspect that there could be a way to use git, not like you or
I do.  Our workflows are already quite different (e.g. you
almost never do topic branch merge yourself in your repository,
but I have abundance of them).  There is no reason to think
there won't be other workflows that are suitable for other
people.  Some workflows might be classified less distributed and
inferiour compared to the "truly git way" from "truly
distributed is the point of git" point of view, but nevertheless
could be "good enough" for those people.  In other words, a
workflow that is a bit more advanced than just a single trunk
CVS/SVN usage could still take advantage of some of the features
to support distributed development model git has, while not
taking full advantage of truly distributed nature of git.

I think the complaints in the yesterday's discussion are mostly
about frustration that, while we have a reasonable support for
the both extremes, we do not either know what that middle ground
workflow is, or even if we know what that is, we do not support
it very well.

And I am not opposed to people exploring what that different
workflow would be, and while they do so if they come up with a
set of commands (get/put perhaps) to suppor that slightly
different workflow, that would be a very good thing.

Add foreign SCM importers in the mix and the situation becomes
more difficult and interesting.  cvsimport mostly works and
quacks like git-fetch with set of tracking branches, which I
think is the right model for the importers, and would integrate
well with the current set of tools.  I believe svnimport is the
same way.  But I do not know about git-svn.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
>>>  - git itself has now done it that way for the last 18 months, and the
>>> fact is, the people _complaining_ are a small subset of the people who
>>> actually use git on a daily basis and don't complain.
>>
>> that's not a good argument; the set of git users is a small subset of those
>> that looked at git, and dismissed it because they couldn't wrap their heads
>> around it. 
> 
> And I've said this again, and I'll say it once more: that has basically 
> _nothing_ to do with whether you spell "pull" as "pull" or "merge".
> 
> The reason people have trouble wrapping their heads around git is because 
> they have been braindamaged by CVS and SVN, and just don't understand the 
> fairly fundamental new concepts and workflow.

 > I claim that those "annoying little issues" are totally made up by
 > people
 > who had trouble wrapping their minds about git, and then make up
 > reasons
 > that have nothing to do with reality for why that might be so.

Let me put this more personally: I continue to be bitten by stupid 
naming issues, and the myriad of little mostly non-orthogonal commands.
My head is doing just fine otherwise, and has no problems wrapping it 
around the core of GIT.  I've also used Darcs for almost a year. Darcs, 
which is much less overwhelming.

This is not about CVS or SVN, so don't put them up as a strawman.
If you want to argue that my brain is warped, use other distributed VCs 
as an example.

The following

   mkdir x y
   cd x
   hg init
   echo hoi > bla
   hg add
   hg commit -m 'yes, I am also too stupid to refuse explicit empty 
commit messages'
   cd ../y
   hg init
   hg pull ../x

pretty much works the same in Darcs, bzr and mercurial.

With GIT, this is what happens

[hanwen@haring y]$ git pull ../x
fatal: Needed a single revision
Pulling into a black hole?

[hanwen@haring y]$ git fetch ../x
warning: no common commits
remote: Generating pack...
Done counting 3 objects.
Deltifying 3 objects.
  100% (3/3) done
Total 3, wremote: ritten 3 (delta 0), reused 0 (delta 0)
Unpacking 3 objects
  100% (3/3) done

[hanwen@haring y]$ git checkout
fatal: ambiguous argument 'HEAD': unknown revision or path not in the 
working tree.
Use '--' to separate paths from revisions
fatal: Not a valid object name HEAD

[hanwen@haring y]$ git branch master
fatal: Needed a single revision

at this point, I resort to adding a bogus commit and/or editing 
.git/HEAD by hand. I'm sure there is a saner way of doing it, but I 
still haven't found out what it is.

This might not be typical GIT use, but it does show the typical GIT user 
experience, at least mine.

If you want to have another example of how not to design a 
user-interface, try the above on Monotone.

> That's totally different from then arguing about stupid naming issues.
> 
> Peopel seem to believe that changign a few names or doing other totally 
> _minimal_ UI changes would somehow magically make things understandable. I 
> claim that isn't so at all. The fact is, git is different from CVS and 
> SVN, and git _has_ to be different from CVS and SVN. It has to be 
> different because the whole model of CVS and SVN is simpyl fundamentally 
> BROKEN.
> 
>> It's worth trying to get those on board by fixing the annoying
>> little issues that have popped up in this thread.
> 
> 
> Let's face it, you could just alias "merge" to "pull", and it wouldn't 
> really change ANYTHING.

I don't want ANYTHING to really change, I just want a sane interface to it.


-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

You claim it is _an interface_ issue but it is not.

> With GIT, this is what happens
>
> [hanwen@haring y]$ git pull ../x
> fatal: Needed a single revision
> Pulling into a black hole?

You asked it to fetch from the neighbour repository and merge it
into your current branch which does not exist (I presume that
you omitted to describe what you did in directory y/ and I am
assuming you did "mkdir y && cd y && git initdb" and nothing
else).  You are pulling into a black hole.

> [hanwen@haring y]$ git fetch ../x
>...
> [hanwen@haring y]$ git checkout

You fetched without telling it in which tracking branch to store
what you fetched, and as a result your HEAD is not updated, so
your current branch still does not exist.  A failure from
checking out nothingness is not an interface issue; expectation
for it to work is a concept level issue.

> [hanwen@haring y]$ git branch master
> fatal: Needed a single revision

You are not at any commit yet and you try to create a branch?

Of course, the "right" (in some sense of the word) thing is to
do "git clone x y" in the parent directory, without creating y
upfront.

If you have an empty y to begin with, then you can do this:

	$ git fetch ../x :origin
        $ git reset --hard origin

which would mirror a part of what "git clone" would have done
for you.  It copies from the other repository, stores the tip in
your tracking branch called "origin", and make your HEAD to be
the same as origin.  After these two commands, you would have
two branches, origin and master, and you will be on master.

You can name 'origin' any way you want.  You might want to name
it 'x' to make it clear (to yourself) that it is used to track
what will happen in the neighboring repository 'x'.  Also, you
would most likely be fetching and merging from the same ../x
from now on, so it might be handy to set up the remotes for it:

	$ cat >.git/remotes/x <<EOF
        URL: ../x
        Pull: master:origin
	EOF

Then subsequent work of yours would be done on 'master' branch
(you have only two branches, and origin is a tracking branch so
you will never make commits on it, which means the above is a
logical consequence), and from time to time you would sync with
whoever is working in ../x

	$ git pull x

Here, 'x' is just a shorthand which looks up the URL: and Pull: line
through .git/remotes/x.  If your .git/remotes/ file was named origin
(not x), you could even have written:

	$ git pull

because pull defaults to 'origin' (without any other configuration).

>> Let's face it, you could just alias "merge" to "pull", and it
>> wouldn't really change ANYTHING.
>
> I don't want ANYTHING to really change, I just want a sane interface to it.

I agree that you do not want to change anything.  You just
needed a bit of handholding, because you deviated from the
cookbook usage, to correct your course.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>
>> [hanwen@haring y]$ git pull ../x
>> fatal: Needed a single revision
>> Pulling into a black hole?

Having said all that, I happen to think that this particular
case of pulling into void could deserve to be special cased to
pretend it is a fast forward (after all, nothingness is an
ancestor of anything), if only to make new people's first
experience more pleasant.

Working from nothingness is something not usually done in
everyday work, so from practical and technical point of view it
does not add much _real_ value to the people who actually uses
the system, but nevertheless, new people typically start
learning the system from either cloned repository (which I
believe is covered by the existing tools fairly well) or
emptiness (which bitten us here in a bad way), and making the
first experience more pleasnt to new people have a positive
value of flattening the learning curve.

So please consider that this is classified as a bug.

Re: Cleaning up git user-interface warts

[Horst H. von Brand]

Junio C Hamano <junkio@cox.net> wrote:
> Junio C Hamano <junkio@cox.net> writes:
> > Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
> >
> >> [hanwen@haring y]$ git pull ../x
> >> fatal: Needed a single revision
> >> Pulling into a black hole?
> 
> Having said all that, I happen to think that this particular
> case of pulling into void could deserve to be special cased to
> pretend it is a fast forward (after all, nothingness is an
> ancestor of anything), if only to make new people's first
> experience more pleasant.

If you make pushing into an empty repository work also, you fix the case of
"create an empty repo for somebody, let them fill it up remotely later".

[...]

> So please consider that this is classified as a bug.

Thanks!
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: Cleaning up git user-interface warts

[Shawn Pearce]

"Horst H. von Brand" <vonbrand@inf.utfsm.cl> wrote:
> If you make pushing into an empty repository work also, you fix the case of
> "create an empty repo for somebody, let them fill it up remotely later".

This seems to work just fine now.  I do it all of the time.

-- 

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Horst H. von Brand wrote:
> Junio C Hamano <junkio@cox.net> wrote:
>> Junio C Hamano <junkio@cox.net> writes:
>>> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>>>
>>>> [hanwen@haring y]$ git pull ../x
>>>> fatal: Needed a single revision
>>>> Pulling into a black hole?
>> 
>> Having said all that, I happen to think that this particular
>> case of pulling into void could deserve to be special cased to
>> pretend it is a fast forward (after all, nothingness is an
>> ancestor of anything), if only to make new people's first
>> experience more pleasant.
> 
> If you make pushing into an empty repository work also, you fix the case of
> "create an empty repo for somebody, let them fill it up remotely later".

That was only the _pull_ which didn't work in empty repo.
Fetch and push worked (and work) just fine with empty repo.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> You claim it is _an interface_ issue but it is not.

 >> I don't want ANYTHING to really change, I just want a sane interface 
 >> to it.
 >
 > I agree that you do not want to change anything.  You just
 > needed a bit of handholding, because you deviated from the
 > cookbook usage, to correct your course.

Users (well, I do at least) start fiddling with systems to find out how 
they work.   Reading the manual is usually done as a last resort. I 
think this is pretty well documented in usability research.

I'm trying to show how GIT is badly suited to this. Your response is to 
explain to me what I should have done. That's nice, but that approach 
doesn't scale, because you don't reach the dozens of users out there who 
try the same, fail and give up.

If you really want to find out the weaknesses, you'd have to sit someone 
new to git in front of a computer, and let him figure how to operate it, 
while videotaping everything.

Writing a manual for newbies is also an effective (and simpler and 
cheaper) approach of figuring out what needs to be changed.



As another example:  annoyances regarding program invocation

  - option handling: -x -f -z != -xfz , "--max-count 1" doesn't work, 
but needs an '='

  - git --help lists an unordered set, which is too long scan quickly. 
I'd expect that list to either contain everything or the minimum set for 
daily use. I.e. the set introduced in a first tutorial.  Why are merge, 
prune, verify-tag there?

Try "bzr help" for comparison.

  - --pretty option with wholly uninformative options full, medium, 
short, raw.  It's not even documented what each option does.


I can go on with listing idiosyncrasies, but my point is not to get help 
from you, but rather to show how git can be improved.


>> With GIT, this is what happens
>>
>> [hanwen@haring y]$ git pull ../x
>> fatal: Needed a single revision
>> Pulling into a black hole?
> 
> You asked it to fetch from the neighbour repository and merge it
> into your current branch which does not exist (I presume that
> you omitted to describe what you did in directory y/ and I am
> assuming you did "mkdir y && cd y && git initdb" and nothing
> else).  You are pulling into a black hole.

as you remark in the other reply, there is IMO no reason for not having 
an empty 'master' branch. If master + HEAD gets created on the first 
commit, it might as well be created on the init-db.

-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Han-Wen Nienhuys escreveu:

> I can go on with listing idiosyncrasies, but my point is not to get help 
> from you, but rather to show how git can be improved.

oh, and another annoying one: git's insistence on firing up a pager if 
there is nothing to page, eg. try

   git-log je-n-existe-pas

-- 
  Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> As another example:  annoyances regarding program invocation
> 
>   - option handling: -x -f -z != -xfz , "--max-count 1" doesn't work, 
> but needs an '='

That's true, and the probable cause is that git tries to first, avoid
dependency on options parsers like getopt/getopt_long/argp or popt for
commands in C, getopt for commands in shell, Getopt::Std/Getopt::Long for
commands in Perl, and something for commands in Python (if there are any
left); second, existing options parsers do not deal (I think) with
distinction between arguments to wrapper and arguments to command, '--' to
separate revisions from pathnames not options from arguments, and the whole
revisions and revision list specifying syntax (where "a --not b" is not
equivalent to "--not a b").

That said, perhaps we should craft our own options parsing (or modify
existing one)...

>   - git --help lists an unordered set, which is too long scan quickly. 

It is one page of alphabetically ordered commands.

git(7) gives whole list of commands, divided into categories, by the way.

> I'd expect that list to either contain everything or the minimum set for 
> daily use. I.e. the set introduced in a first tutorial.  Why are merge, 
> prune, verify-tag there?
> 
> Try "bzr help" for comparison.

I wonder why "repack" isn't there, if "prune" is.

>   - --pretty option with wholly uninformative options full, medium, 
> short, raw.  It's not even documented what each option does.

And 'oneline' and undocumented 'email'. True, git lacks documentation (and
this one of main complaints in git survey).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Jakub Narebski escreveu:

>>   - --pretty option with wholly uninformative options full, medium, 
>> short, raw.  It's not even documented what each option does.
> 
> And 'oneline' and undocumented 'email'. True, git lacks documentation (and
> this one of main complaints in git survey).

The recently posted patch documenting is an improvement, but why not
add an option so you can do

  --format 'committer %c\nauthor %a\n'
  
this catches all combinations, and is easier for scripting.

Right now, I have some scripts that have to munge log output with
regular expressions to strip out the "author:"  prefixes.


-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Han-Wen Nienhuys wrote:

> Jakub Narebski escreveu:
> 
>>>   - --pretty option with wholly uninformative options full, medium, 
>>> short, raw.  It's not even documented what each option does.
>> 
>> And 'oneline' and undocumented 'email'. True, git lacks documentation (and
>> this one of main complaints in git survey).
> 
> The recently posted patch documenting is an improvement, but why not
> add an option so you can do
> 
>   --format 'committer %c\nauthor %a\n'
>   
> this catches all combinations, and is easier for scripting.
> 
> Right now, I have some scripts that have to munge log output with
> regular expressions to strip out the "author:"  prefixes.

If we ever implemented this, I'd rather to separate what is now of format
parsing in git-for-each-ref (although I'd like to make it more like rpm's
--query-format argument, with %-n{header}, %[array] etc.) into separate
module, and reuse it for git-log and friends --pretty/--format handling.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Fri, 24 Nov 2006, Han-Wen Nienhuys wrote:

> The recently posted patch documenting is an improvement, but why not
> add an option so you can do
> 
>   --format 'committer %c\nauthor %a\n'
>   
> this catches all combinations, and is easier for scripting.

Yes, it would be easier for scripting, and it would probably be relatively 
easy, what with the addition of interpolate.[ch] to git. However, it is 
work, and I am lazy.

What information would you like, anyway? IOW can you provide me with a 
list like this:

%c	committer
%a	author
%d	committer_date
...

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Junio C Hamano]

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

> On Fri, 24 Nov 2006, Han-Wen Nienhuys wrote:
>
>> The recently posted patch documenting is an improvement, but why not
>> add an option so you can do
>> 
>>   --format 'committer %c\nauthor %a\n'
>>   
>> this catches all combinations, and is easier for scripting.
>
> Yes, it would be easier for scripting, and it would probably be relatively 
> easy, what with the addition of interpolate.[ch] to git. However, it is 
> work, and I am lazy.

Lazy is good when the details should not matter.  If some people
are scripting, they are fully capable of reading raw or fuller.

[PATCH for "next"] pretty-formats: add 'format:<string>'

[Johannes Schindelin]

With this patch,

$ git show -s \
	--pretty=format:'  Ze komit %h woss%n  dunn buy ze great %an'

shows something like

  Ze komit 04c5c88 woss
  dunn buy ze great Junio C Hamano

The supported placeholders are:

	'%H': commit hash
	'%h': abbreviated commit hash
	'%T': tree hash
	'%t': abbreviated tree hash
	'%P': parent hashes
	'%p': abbreviated parent hashes
	'%an': author name
	'%ae': author email
	'%ad': author date
	'%aD': author date, RFC2822 style
	'%ar': author date, relative
	'%at': author date, UNIX timestamp
	'%cn': committer name
	'%ce': committer email
	'%cd': committer date
	'%cD': committer date, RFC2822 style
	'%cr': committer date, relative
	'%ct': committer date, UNIX timestamp
	'%e': encoding
	'%s': subject
	'%b': body
	'%Cred': switch color to red
	'%Cgreen': switch color to green
	'%Cblue': switch color to blue
	'%Creset': reset color
	'%n': newline

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---

	On Fri, 24 Nov 2006, Han-Wen Nienhuys wrote:

	> The recently posted patch documenting is an improvement, but why 
	> not add an option so you can do
	> 
	>   --format 'committer %c\nauthor %a\n'
	>   
	> this catches all combinations, and is easier for scripting.

	So, I overcame my laziness after 91 days...

	Of course, this is not as efficient as it could be: it _will_ get 
	_all_ variables from the commit, even if not needed. However, I 
	don't think that it matters in reality.

	BTW I have not found any implementation of xstrndup(), so I let it 
	be static.

 Documentation/pretty-formats.txt |   44 +++++++++
 commit.c                         |  195 ++++++++++++++++++++++++++++++++++++++
 commit.h                         |    1 +
 log-tree.c                       |    2 +-
 4 files changed, 241 insertions(+), 1 deletions(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index fb0b0b9..2fe6c31 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -77,9 +77,53 @@ displayed in full, regardless of whether --abbrev or
 true parent commits, without taking grafts nor history
 simplification into account.
 
+	* 'format:'
++
+The 'format:' format allows you to specify which information
+you want to show. It works a little bit like printf format,
+with the notable exception that you get a newline with '%n'
+instead of '\n'.
+
+E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<"'
+would show something like this:
+
+The author of fe6e0ee was Junio C Hamano, 23 hours ago
+The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
+
+The placeholders are:
+
+- '%H': commit hash
+- '%h': abbreviated commit hash
+- '%T': tree hash
+- '%t': abbreviated tree hash
+- '%P': parent hashes
+- '%p': abbreviated parent hashes
+- '%an': author name
+- '%ae': author email
+- '%ad': author date
+- '%aD': author date, RFC2822 style
+- '%ar': author date, relative
+- '%at': author date, UNIX timestamp
+- '%cn': committer name
+- '%ce': committer email
+- '%cd': committer date
+- '%cD': committer date, RFC2822 style
+- '%cr': committer date, relative
+- '%ct': committer date, UNIX timestamp
+- '%e': encoding
+- '%s': subject
+- '%b': body
+- '%Cred': switch color to red
+- '%Cgreen': switch color to green
+- '%Cblue': switch color to blue
+- '%Creset': reset color
+- '%n': newline
+
+
 --encoding[=<encoding>]::
 	The commit objects record the encoding used for the log message
 	in their encoding header; this option can be used to tell the
 	command to re-code the commit log message in the encoding
 	preferred by the user.  For non plumbing commands this
 	defaults to UTF-8.
+
diff --git a/commit.c b/commit.c
index 8d279b0..a97aef3 100644
--- a/commit.c
+++ b/commit.c
@@ -3,6 +3,7 @@
 #include "commit.h"
 #include "pkt-line.h"
 #include "utf8.h"
+#include "interpolate.h"
 
 int save_commit_buffer = 1;
 
@@ -36,8 +37,11 @@ struct cmt_fmt_map {
 	{ "full",	5,	CMIT_FMT_FULL },
 	{ "fuller",	5,	CMIT_FMT_FULLER },
 	{ "oneline",	1,	CMIT_FMT_ONELINE },
+	{ "format:",	7,	CMIT_FMT_USERFORMAT},
 };
 
+static char *user_format;
+
 enum cmit_fmt get_commit_format(const char *arg)
 {
 	int i;
@@ -46,6 +50,12 @@ enum cmit_fmt get_commit_format(const char *arg)
 		return CMIT_FMT_DEFAULT;
 	if (*arg == '=')
 		arg++;
+	if (!prefixcmp(arg, "format:")) {
+		if (user_format)
+			free(user_format);
+		user_format = xstrdup(arg + 7);
+		return CMIT_FMT_USERFORMAT;
+	}
 	for (i = 0; i < ARRAY_SIZE(cmt_fmts); i++) {
 		if (!strncmp(arg, cmt_fmts[i].n, cmt_fmts[i].cmp_len) &&
 		    !strncmp(arg, cmt_fmts[i].n, strlen(arg)))
@@ -710,6 +720,188 @@ static char *logmsg_reencode(const struct commit *commit,
 	return out;
 }
 
+static char *xstrndup(const char *text, int len)
+{
+	char *result = xmalloc(len + 1);
+	memcpy(result, text, len);
+	result[len] = '\0';
+	return result;
+}
+
+static void fill_person(struct interp *table, const char *msg, int len)
+{
+	int start, end, tz = 0;
+	unsigned long date;
+	char *ep;
+
+	/* parse name */
+	for (end = 0; end < len && msg[end] != '<'; end++)
+		; /* do nothing */
+	start = end + 1;
+	while (end > 0 && isspace(msg[end - 1]))
+		end--;
+	table[0].value = xstrndup(msg, end);
+
+	if (start >= len)
+		return;
+
+	/* parse email */
+	for (end = start + 1; end < len && msg[end] != '>'; end++)
+		; /* do nothing */
+
+	if (end >= len)
+		return;
+
+	table[1].value = xstrndup(msg + start, end - start);
+
+	/* parse date */
+	for (start = end + 1; start < len && isspace(msg[start]); start++)
+		; /* do nothing */
+	if (start >= len)
+		return;
+	date = strtoul(msg + start, &ep, 10);
+	if (msg + start == ep)
+		return;
+
+	table[5].value = xstrndup(msg + start, ep - msg + start);
+
+	/* parse tz */
+	for (start = ep - msg + 1; start < len && isspace(msg[start]); start++)
+		; /* do nothing */
+	if (start + 1 < len) {
+		tz = strtoul(msg + start + 1, NULL, 10);
+		if (msg[start] == '-')
+			tz = -tz;
+	}
+
+	interp_set_entry(table, 2, show_date(date, tz, 0));
+	interp_set_entry(table, 3, show_rfc2822_date(date, tz));
+	interp_set_entry(table, 4, show_date(date, tz, 1));
+}
+
+static long format_commit_message(const struct commit *commit,
+		const char *msg, char *buf, unsigned long space)
+{
+	struct interp table[] = {
+		{ "%H" },	/* commit hash */
+		{ "%h" },	/* abbreviated commit hash */
+		{ "%T" },	/* tree hash */
+		{ "%t" },	/* abbreviated tree hash */
+		{ "%P" },	/* parent hashes */
+		{ "%p" },	/* abbreviated parent hashes */
+		{ "%an" },	/* author name */
+		{ "%ae" },	/* author email */
+		{ "%ad" },	/* author date */
+		{ "%aD" },	/* author date, RFC2822 style */
+		{ "%ar" },	/* author date, relative */
+		{ "%at" },	/* author date, UNIX timestamp */
+		{ "%cn" },	/* committer name */
+		{ "%ce" },	/* committer email */
+		{ "%cd" },	/* committer date */
+		{ "%cD" },	/* committer date, RFC2822 style */
+		{ "%cr" },	/* committer date, relative */
+		{ "%ct" },	/* committer date, UNIX timestamp */
+		{ "%e" },	/* encoding */
+		{ "%s" },	/* subject */
+		{ "%b" },	/* body */
+		{ "%Cred" },	/* red */
+		{ "%Cgreen" },	/* green */
+		{ "%Cblue" },	/* blue */
+		{ "%Creset" },	/* reset color */
+		{ "%n" }	/* newline */
+	};
+	enum interp_index {
+		IHASH = 0, IHASH_ABBREV,
+		ITREE, ITREE_ABBREV,
+		IPARENTS, IPARENTS_ABBREV,
+		IAUTHOR_NAME, IAUTHOR_EMAIL,
+		IAUTHOR_DATE, IAUTHOR_DATE_RFC2822, IAUTHOR_DATE_RELATIVE,
+		IAUTHOR_TIMESTAMP,
+		ICOMMITTER_NAME, ICOMMITTER_EMAIL,
+		ICOMMITTER_DATE, ICOMMITTER_DATE_RFC2822,
+		ICOMMITTER_DATE_RELATIVE, ICOMMITTER_TIMESTAMP,
+		IENCODING,
+		ISUBJECT,
+		IBODY,
+		IRED, IGREEN, IBLUE, IRESET_COLOR,
+		INEWLINE
+	};
+	struct commit_list *p;
+	char parents[1024];
+	int i;
+	enum { HEADER, SUBJECT, BODY } state;
+
+	if (INEWLINE + 1 != ARRAY_SIZE(table))
+		die("invalid interp table!");
+
+	/* these are independent of the commit */
+	interp_set_entry(table, IRED, "\033[31m");
+	interp_set_entry(table, IGREEN, "\033[32m");
+	interp_set_entry(table, IBLUE, "\033[34m");
+	interp_set_entry(table, IRESET_COLOR, "\033[m");
+	interp_set_entry(table, INEWLINE, "\n");
+
+	/* these depend on the commit */
+	if (!commit->object.parsed)
+		parse_object(commit->object.sha1);
+	interp_set_entry(table, IHASH, sha1_to_hex(commit->object.sha1));
+	interp_set_entry(table, IHASH_ABBREV,
+			find_unique_abbrev(commit->object.sha1,
+				DEFAULT_ABBREV));
+	interp_set_entry(table, ITREE, sha1_to_hex(commit->tree->object.sha1));
+	interp_set_entry(table, ITREE_ABBREV,
+			find_unique_abbrev(commit->tree->object.sha1,
+				DEFAULT_ABBREV));
+	for (i = 0, p = commit->parents;
+			p && i < sizeof(parents) - 1;
+			p = p->next)
+		i += snprintf(parents + i, sizeof(parents) - i - 1, "%s ",
+			sha1_to_hex(p->item->object.sha1));
+	interp_set_entry(table, IPARENTS, parents);
+	for (i = 0, p = commit->parents;
+			p && i < sizeof(parents) - 1;
+			p = p->next)
+		i += snprintf(parents + i, sizeof(parents) - i - 1, "%s ",
+			find_unique_abbrev(p->item->object.sha1,
+				DEFAULT_ABBREV));
+	interp_set_entry(table, IPARENTS_ABBREV, parents);
+
+	for (i = 0, state = HEADER; msg[i] && state < BODY; i++) {
+		int eol;
+		for (eol = i; msg[eol] && msg[eol] != '\n'; eol++)
+			; /* do nothing */
+
+		if (state == SUBJECT) {
+			table[ISUBJECT].value = xstrndup(msg + i, eol - i);
+			i = eol;
+		}
+		if (i == eol) {
+			state++;
+			/* strip empty lines */
+			while (msg[eol + 1] == '\n')
+				eol++;
+		} else if (!prefixcmp(msg + i, "author "))
+			fill_person(table + IAUTHOR_NAME,
+					msg + i + 7, eol - i - 7);
+		else if (!prefixcmp(msg + i, "committer "))
+			fill_person(table + ICOMMITTER_NAME,
+					msg + i + 10, eol - i - 10);
+		else if (!prefixcmp(msg + i, "encoding "))
+			table[IENCODING].value = xstrndup(msg + i, eol - i);
+		i = eol;
+	}
+	if (msg[i])
+		table[IBODY].value = xstrdup(msg + i);
+	for (i = 0; i < ARRAY_SIZE(table); i++)
+		if (!table[i].value)
+			interp_set_entry(table, i, "<unknown>");
+
+	interpolate(buf, space, user_format, table, ARRAY_SIZE(table));
+	interp_clear_table(table, ARRAY_SIZE(table));
+
+	return strlen(buf);
+}
+
 unsigned long pretty_print_commit(enum cmit_fmt fmt,
 				  const struct commit *commit,
 				  unsigned long len,
@@ -727,6 +919,9 @@ unsigned long pretty_print_commit(enum cmit_fmt fmt,
 	char *reencoded;
 	char *encoding;
 
+	if (fmt == CMIT_FMT_USERFORMAT)
+		return format_commit_message(commit, msg, buf, space);
+
 	encoding = (git_log_output_encoding
 		    ? git_log_output_encoding
 		    : git_commit_encoding);
diff --git a/commit.h b/commit.h
index c737444..83507a0 100644
--- a/commit.h
+++ b/commit.h
@@ -47,6 +47,7 @@ enum cmit_fmt {
 	CMIT_FMT_FULLER,
 	CMIT_FMT_ONELINE,
 	CMIT_FMT_EMAIL,
+	CMIT_FMT_USERFORMAT,
 
 	CMIT_FMT_UNSPECIFIED,
 };
diff --git a/log-tree.c b/log-tree.c
index ac86194..6ce239d 100644
--- a/log-tree.c
+++ b/log-tree.c
@@ -211,7 +211,7 @@ void show_log(struct rev_info *opt, const char *sep)
 				 sha1, sha1);
 			opt->diffopt.stat_sep = buffer;
 		}
-	} else {
+	} else if (opt->commit_format != CMIT_FMT_USERFORMAT) {
 		fputs(diff_get_color(opt->diffopt.color_diff, DIFF_COMMIT),
 		      stdout);
 		if (opt->commit_format != CMIT_FMT_ONELINE)
-- 
1.5.0.1.620.gac8f

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Han-Wen Nienhuys]

Johannes Schindelin escreveu:
> With this patch,
> 
> $ git show -s \
> 	--pretty=format:'  Ze komit %h woss%n  dunn buy ze great %an'
> 
> shows something like
> 
>   Ze komit 04c5c88 woss
>   dunn buy ze great Junio C Hamano
> 
> The supported placeholders are:

nitpick:

  \n

for newline would be nice. Similar for backslash, formfeed, alarm, etc.

 

-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Johannes Schindelin]

Hi,

On Fri, 23 Feb 2007, Han-Wen Nienhuys wrote:

> nitpick:
> 
>   \n
> 
> for newline would be nice. Similar for backslash, formfeed, alarm, etc.

Yes, I thought about that. But it would change behaviour (even if I don't 
think it would do serious damage; the only user of interpolate.[ch] I saw 
is git-daemon, and that does not need \n, I guess).

Besides, "%n" is

- more consistent,
- date(1) does it the same way, and
- you can put BS, FF, AL, etc. into the format string before passing 
  it as an option to git; git does not have to help you there.

Ciao,
Dscho

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Robin Rosenberg]

fredag 23 februari 2007 02:07 skrev Johannes Schindelin:
> Hi,
> 
> On Fri, 23 Feb 2007, Han-Wen Nienhuys wrote:
> 
> > nitpick:
> > 
> >   \n
> > 
> > for newline would be nice. Similar for backslash, formfeed, alarm, etc.
> 
> Yes, I thought about that. But it would change behaviour (even if I don't 
> think it would do serious damage; the only user of interpolate.[ch] I saw 
> is git-daemon, and that does not need \n, I guess).
Other tools that come to mind, rpm and clearcase use \n vfor newline in the
format argument, which is good because I can guess that even without looking 
at the documentation. %n I'd guess would be for a number of some kind, e..g.
the ordinal number of the commit listed (in subset and order of the listed commits)

> Besides, "%n" is
> 
> - more consistent,
with...?
> - date(1) does it the same way, and
Ok, I learnt something. Never fi
> - you can put BS, FF, AL, etc. into the format string before passing 
>   it as an option to git; git does not have to help you there.
They are hard to type in shells and even harder in gui's.

-- robin

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Johannes Schindelin]

Hi,

On Fri, 23 Feb 2007, Robin Rosenberg wrote:

> fredag 23 februari 2007 02:07 skrev Johannes Schindelin:
> > 
> > On Fri, 23 Feb 2007, Han-Wen Nienhuys wrote:
> > 
> > > nitpick:
> > > 
> > >   \n
> > > 
> > > for newline would be nice. Similar for backslash, formfeed, alarm, 
> > > etc.
> > 
> > Yes, I thought about that. But it would change behaviour (even if I 
> > don't think it would do serious damage; the only user of 
> > interpolate.[ch] I saw is git-daemon, and that does not need \n, I 
> > guess).
>
> Other tools that come to mind, rpm and clearcase use \n vfor newline in 
> the format argument, which is good because I can guess that even without 
> looking at the documentation. %n I'd guess would be for a number of some 
> kind, e..g. the ordinal number of the commit listed (in subset and order 
> of the listed commits)

Okay. Patch?

> > Besides, "%n" is
> > 
> > - more consistent,
>
> with...?

... itself? Why should not _one_ escape character be enough?

> > - you can put BS, FF, AL, etc. into the format string before passing
> >   it as an option to git; git does not have to help you there.
>
> They are hard to type in shells and even harder in gui's.

You would not do that all that often, but rather write a script. Even the 
config format allows for inclusion of special characters, so aliases 
should be fine.

Ciao,
Dscho

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Junio C Hamano]

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

> With this patch,
>
> $ git show -s \
> 	--pretty=format:'  Ze komit %h woss%n  dunn buy ze great %an'
>
> shows something like
>
>   Ze komit 04c5c88 woss
>   dunn buy ze great Junio C Hamano

Does it say "This commit is by a fool whose name is blah"?

> The supported placeholders are:
>
> 	'%H': commit hash
>...
> 	'%b': body

Hmmm.  Would we want to make them somehow interoperable with
git-for-each-ref format atoms?

Also, it _might_ be worthwhile to do something like "%+4b"
which means "indent each line of this field with 4 spaces", for
a multi-line field like "%b".

> 	'%Cred': switch color to red
> 	'%Cgreen': switch color to green
> 	'%Cblue': switch color to blue
> 	'%Creset': reset color

Hmmm.  I strongly suspect that we would want to reuse code to
grok colors and attributes in color.c.

> 	>   --format 'committer %c\nauthor %a\n'
> 	>   
> 	> this catches all combinations, and is easier for scripting.

I do not have strong preference between "\n" and "%n".

> 	So, I overcame my laziness after 91 days...

Thanks.

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Johannes Schindelin]

Hi,

On Thu, 22 Feb 2007, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > With this patch,
> >
> > $ git show -s \
> > 	--pretty=format:'  Ze komit %h woss%n  dunn buy ze great %an'
> >
> > shows something like
> >
> >   Ze komit 04c5c88 woss
> >   dunn buy ze great Junio C Hamano
> 
> Does it say "This commit is by a fool whose name is blah"?

Vy, it iss korrekt Churmen Inklish [Translation: Why, it is correct 
German "English"]... ;-)

> > The supported placeholders are:
> >
> > 	'%H': commit hash
> >...
> > 	'%b': body
> 
> Hmmm.  Would we want to make them somehow interoperable with
> git-for-each-ref format atoms?

But those placeholders are so long! Not even GNU date supports such long 
placeholders... And I could not reuse interpolate.[ch] as is for that.

> Also, it _might_ be worthwhile to do something like "%+4b" which means 
> "indent each line of this field with 4 spaces", for a multi-line field 
> like "%b".

Same goes here: interpolate.[ch] does not (yet) allow for that.

> > 	'%Cred': switch color to red
> > 	'%Cgreen': switch color to green
> > 	'%Cblue': switch color to blue
> > 	'%Creset': reset color
> 
> Hmmm.  I strongly suspect that we would want to reuse code to grok 
> colors and attributes in color.c.

And again...

> > 	>   --format 'committer %c\nauthor %a\n'
> > 	>   
> > 	> this catches all combinations, and is easier for scripting.
> 
> I do not have strong preference between "\n" and "%n".

This would be easy, methink, to teach to interpolate().

Maybe I can overcome my laziness, and extend interpolate() so that it can 
actually call callbacks with callback data...

Alternatively, I could imitate for-each-ref, and roll my own 
interpolate()? :-)

Ciao,
Dscho

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Junio C Hamano]

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

>> > The supported placeholders are:
>> >
>> > 	'%H': commit hash
>> >...
>> > 	'%b': body
>> 
>> Hmmm.  Would we want to make them somehow interoperable with
>> git-for-each-ref format atoms?
>
> But those placeholders are so long! Not even GNU date supports such long 
> placeholders... And I could not reuse interpolate.[ch] as is for that.

What I was hinting at was to fix (or extend) for-each-ref to
accept these short-and-sweet placeholders.

>> Also, it _might_ be worthwhile to do something like "%+4b" which means 
>> "indent each line of this field with 4 spaces", for a multi-line field 
>> like "%b".
>
> Same goes here: interpolate.[ch] does not (yet) allow for that.

Nah, if you feel it is too much work, I trust your judgement (I
do not recall details of how interpolate.c does its thing).  I
do not think it's worth it.

Re: [PATCH for "next"] pretty-formats: add 'format:<string>'

[Johannes Schindelin]

Hi,

On Fri, 23 Feb 2007, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> >> > The supported placeholders are:
> >> >
> >> > 	'%H': commit hash
> >> >...
> >> > 	'%b': body
> >> 
> >> Hmmm.  Would we want to make them somehow interoperable with 
> >> git-for-each-ref format atoms?
> >
> > But those placeholders are so long! Not even GNU date supports such 
> > long placeholders... And I could not reuse interpolate.[ch] as is for 
> > that.
> 
> What I was hinting at was to fix (or extend) for-each-ref to accept 
> these short-and-sweet placeholders.

Ah, the other way round...

> >> Also, it _might_ be worthwhile to do something like "%+4b" which 
> >> means "indent each line of this field with 4 spaces", for a 
> >> multi-line field like "%b".
> >
> > Same goes here: interpolate.[ch] does not (yet) allow for that.
> 
> Nah, if you feel it is too much work, I trust your judgement (I
> do not recall details of how interpolate.c does its thing).  I
> do not think it's worth it.

Sure, it _would_ be nice to let interpolate call back, instead of having 
to fill a table with static strings (xstrdup()ing them, no less).

However, I want to go play Snooker tonight, so this is up-for-grabs.

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> 
> This is not about CVS or SVN, so don't put them up as a strawman.
> If you want to argue that my brain is warped, use other distributed VCs as an
> example.

Your example has nothing at all to do with "pull" vs "fetch", though.

Your example is about something totally _different_, namely that under 
git, "git init-db" is _only_ for creating a _new_ project.

> The following
> 
>   mkdir x y
>   cd x
>   hg init
>   echo hoi > bla
>   hg add
>   hg commit -m 'yes, I am also too stupid to refuse explicit empty commit messages'
>   cd ../y
>   hg init
>   hg pull ../x
> 
> pretty much works the same in Darcs, bzr and mercurial.
> 
> With GIT, this is what happens
> 
> [hanwen@haring y]$ git pull ../x

Bzzt. This is where you went wrong, and you blamed "pull".

The way you do this in git is to NOT do "git init". Instead, you replace 
all the

	mkdir y
	cd ../y
	hg init
	hg pull ../x

with a simple

	git clone x y

and YOU ARE DONE.

Now, we could certainly _make_ "git pull" work on an empty git project, 
but that has _nothing_ to do with what people have been talking about.

In fact, the fact that "git fetch" kind of works is not exactly accidental 
(because "git fetch" _is_ meant to add new local branches too), but all 
the problems you have with it are due to the SAME issue. You started 
without any branch at all, because you started with an empty git repo, and 
you're simply not _supposed_ to do that.

So current rule (and this is not new, it's always been true): the ONLY 
time you use "git init-db" is when you are going to start a totally new 
project. Never _ever_ otherwise. If you want to track another project, use 
"git clone".

> This might not be typical GIT use, but it does show the typical GIT user
> experience, at least mine.

It's not that it isn't typical, it's that you are using the wrong model. 
Maybe it's not well documented, I can easily give you that, but ALL your 
problems come from that fundamental starting point: you shouldn't have 
used "git init-db" in the first place.

Somebody want to document it?

Alternatively, we certainly _could_ make "git pull" just accept an empty 
git repo, and make it basically create the current branch.

(And we probably should improve the error messahe)

> I don't want ANYTHING to really change, I just want a sane interface to it.

The sane interface _exists_. It's called "git clone".

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:

> So current rule (and this is not new, it's always been true): the ONLY 
> time you use "git init-db" is when you are going to start a totally new 
> project. Never _ever_ otherwise. If you want to track another project, use 
> "git clone".

Actually, only a 2 weeks ago, you suggested that I share the website
and main source code for my project in a single repository for reasons
of organization.

In this setup I find it logical to do

  git init-db
  git pull ..url.. website/master

to wind up with just the 5mb website, instead of the complete 70mb
of packed source code with all of its branches and tags.

> It's not that it isn't typical, it's that you are using the wrong model. 
> Maybe it's not well documented, I can easily give you that, but ALL your 
> problems come from that fundamental starting point: you shouldn't have 
> used "git init-db" in the first place.
> 
> Somebody want to document it?
> 
> Alternatively, we certainly _could_ make "git pull" just accept an empty 
> git repo, and make it basically create the current branch.

Yes, I would like that.  


-- 

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> 
> Actually, only a 2 weeks ago, you suggested that I share the website
> and main source code for my project in a single repository for reasons
> of organization.
> 
> In this setup I find it logical to do
> 
>   git init-db
>   git pull ..url.. website/master

I don't disagree per se. It should be easy to support, it's just that it's 
not traditionally been something we've ever done.

So the way you'd normally set up a single repo that contains multiple 
other existing repositories is to basically start with one ("git clone") 
and then add the other branches and "git fetch" them.

So again, instead of "git init-db" + "git pull", you'd just use "git 
clone" instead.

Note that there _is_ another difference between "git pull" and 
"fetch+merge". The difference being that "git pull" implicitly does the 
checkout for you (I say "implicitly", because that's the way the git 
merge conceptually works: we always merge in the working tree. That's not 
the only way it _could_ be done, though - for trivial merges, we could do 
them without any working tree at all, but we don't suppotr that).

And that "git pull" semantic actually means that if you want a _bare_ 
repository, I think "git --bare init-db" + "git --bare fetch" actually 
does exactly the right thing right now too. But "git pull" would not be 
the right thing to use.

Btw, another normal way to generate a central "multi-headed repo" for is 
to not use "pull" or "fetch" or "clone" at ALL, but I would likely do 
something like

	mkdir central-repo
	cd central-repo
	git --bare init-db

and that's it. You now have a central repository, and you _never_ touch it 
again in the central place except to repack it and do other "maintenance" 
(eg pruning, fsck, whatever).

Instead, from the _outside_, you'd probably just do

	git push central-repo mybranch:refs/heads/central-branch-name

(actually, you'd probably set up that branch-name translation of 
"mybranch:refs/heads/central-branch-name" in your remote description, but 
I'm writing it out in full as an example).

So there are many ways to do it. It just happens that "git init-db" 
followed by "git pull" is not one of them ;)

(And the real reason for that is simple: "git pull" simply wants to have 
something to _start_ with. It's not hugely fundamental, it's just how it 
was written).

multi-project repos (was Re: Cleaning up git user-interface warts)

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> 
> On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
>> Actually, only a 2 weeks ago, you suggested that I share the website
>> and main source code for my project in a single repository for reasons
>> of organization.
>>
>> In this setup I find it logical to do
>>
>>   git init-db
>>   git pull ..url.. website/master
> 
> I don't disagree per se. It should be easy to support, it's just that it's 
> not traditionally been something we've ever done.
> 
> So the way you'd normally set up a single repo that contains multiple 
> other existing repositories is to basically start with one ("git clone") 

You're misunderstanding me: the multi-repo is at git.sv.gnu.org is the
remote one. The example I gave was about locally creating a single
project repo from a remote multiproject repo. 

On a tangent: why is there no reverse-clone?  I have no shell access
to the machine, so when I created the remote repo, I had to push, and
ended up putting 1.2 Gb data on the server.

<looks at manpage>

is this send-pack? From UI perspective it would be nice if this could
also be done with clone,

  git clone . ssh+git://....

>And that "git pull" semantic actually means that if you want a _bare_ 
>repository, I think "git --bare init-db" + "git --bare fetch" actually

yes, this works. Two remarks:


* it needs

  website/master:master

otherwise you still don't have a branch.

* why are objects downloaded twice?  If I do

  git --bare fetch git://git.sv.gnu.org/lilypond.git web/master

it downloads stuff, but I don't get a branch. If I then do 

  git --bare fetch git://git.sv.gnu.org/lilypond.git web/master:master

it downloads the same stuff again. 

-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> 
> You're misunderstanding me: the multi-repo is at git.sv.gnu.org is the
> remote one. The example I gave was about locally creating a single
> project repo from a remote multiproject repo. 

Ahh.

Ok, try the patch I just sent out, and see if it works for you. It 
_should_ allow you to do exactly that

	mkdir new-repo
	cd new-repo
	git init-db
	git pull <remote> <onehead>

and now your "master" branch should be initialized to "onehead".

Oh, except I just realized that I forgot to do a "git checkout" in my 
patch, so you'd need to add that (or do it by hand, but you really 
shouldn't need to, since the checkout is implied by the "pull").

The downside with this is that it does NOT populate your "remotes" 
information (like "git clone" would have done), so either we'd need to 
teach "git pull" to do that too, or you just have to do it by hand (so 
that you then can do the shorthand "git pull" to update in the future).

> On a tangent: why is there no reverse-clone?  I have no shell access
> to the machine, so when I created the remote repo, I had to push, and
> ended up putting 1.2 Gb data on the server.

Yeah, you're supposed to "init-db" and "push". Right now, that tends to 
unpack everything (which is bad), although that is hopefully getting fixed 
(ie the receiving end shouldn't unpack any more if it is recent. Junio?)

> <looks at manpage>
> 
> is this send-pack?

"git push" uses send-pack internally, you shouldn't ever need to use it 
yourself.

> From UI perspective it would be nice if this could also be done with clone,
> 
>   git clone . ssh+git://....

The creation of a new archive tends to need special rights (with _real_ 
ssh access and a shell you could do it, but "ssh+git" really means "git 
protocol over a connection that was opened with ssh, but doesn't 
necessarily have a real shell at the other end").

So for most protocols, you simply cannot (and shouldn't) do it. Think 
about services like the one that Pasky has set up, that allow you to set 
up a new git repo - the setup phase really _has_ to be separate (because 
you need to set up your keys etc).

So I think the above syntax is actually not a good one, because it cannot 
work in the general case. It's much better to get used to setting up a 
repo first, and then pushing into it, and just accepting that it's a 
two-phase thing.

Also, from a bandwidth standpoint, you can often (although obviously not 
always) make the setup start with something that is _closer_ to what you 
want to do. So, for example, you'd often do something like:

 (a) ssh to central repository
 (b) create the new repository by cloning it _locally_ at the central 
     place from some other repository that is related
 (c) then, from your local (non-central) repository, do a "git push --force"
     to force your changes (which now only needs the _incremental_ thing).

An example of this is again the "forking" thing that he repos at  at 
http://git.or.cz/ already supports. 


> >And that "git pull" semantic actually means that if you want a _bare_ 
> >repository, I think "git --bare init-db" + "git --bare fetch" actually
> 
> yes, this works. Two remarks:
> 
> * it needs
> 
>   website/master:master
> 
> otherwise you still don't have a branch.

Right. In fact, you should probably do

	website/master:refs/heads/master

just to make it really explicit.

> * why are objects downloaded twice?  If I do
> 
>   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master
> 
> it downloads stuff, but I don't get a branch.

A "fetch" by default won't actually generate a local branch unless you 
told it to. It just squirrels the end result into the magic FETCH_HEAD 
name, so that you can do

	# do the fetch
	git fetch git://git.sv.gnu.org/lilypond.git web/master

	# look at changes
	gitk ..FETCH_HEAD

	# If you're happy with them, merge them in
	git merge "merge new code" HEAD FETCH_HEAD

and you never actually created a real local branch at all.

If you want "git fetch" to fetch _into_ a branch, you need to tell it so, 
by using the full "src:dest" format. Otherwise it doesn't know what branch 
to fetch it into.

(And, of course, you can define that branch relationship in your remote 
configuration, so you don't actually have to say it explicitly every time)

> If I then do 
> 
>   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master:master
> 
> it downloads the same stuff again. 

Right. So you can either

 (a) do it that way to begin with (because you now told it to put the 
     results in "master", so you never needed to do the second fetch in 
     the first place)

or

 (b) after you did the first fetch (into FETCH_HEAD), you could also have 
     just decided to do 

	git update-ref HEAD FETCH_HEAD ""

     (where that "" at the end is really not technically necessary, but it 
     tells "update-ref" that you _only_ want to do this if the old HEAD 
     was empty/undefined. Without it, "git update-ref" will just 
     overwrite HEAD without caring what it contained before, so it can be 
     a dangerous operation!)

See?

Re: multi-project repos

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> Yeah, you're supposed to "init-db" and "push". Right now, that tends to 
> unpack everything (which is bad), although that is hopefully getting fixed 
> (ie the receiving end shouldn't unpack any more if it is recent. Junio?)

Correct.

> See?
>
> 			Linus

Saw.

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
> 
> A "fetch" by default won't actually generate a local branch unless you 
> told it to. It just squirrels the end result into the magic FETCH_HEAD 
> name [...]

Btw, the magic heads are probably not all that well documented. They do 
come up in the man-pages, but I don't think there is any central place 
talking about them. We have:

 - "HEAD" itself, which is obviously the default pointer for a lot of 
   operations, and that specifies the current branch (ie it should 
   currently always be a symref, although we've talked about relaxing 
   that)

 - "ORIG_HEAD" is very useful indeed, and it's the head _before_ a merge 
   (or some other operations, like "git rebase" and "git reset": think of 
   it as a "original head before we did some uncontrolled operation 
   where we otherwise can't use HEAD^ or similar")

   I use "gitk ORIG_HEAD.." a lot, and if I don't like something I see 
   when I do it, I end up doing "git reset --hard ORIG_HEAD" to undo a 
   pull I've done. This is important exactly because ORIG_HEAD is _not_ 
   the same as the first parent of a merge, since a merge could have been 
   just a fast-forward.

 - "FETCH_HEAD" as mentioned. Normally you'd only use this in scripting, I 
   suspect, but it's potentially useful if you prefer to do a fetch first 
   and then check out it (perhaps cherry-picking stuff instead of merging, 
   for example).

   So you could do (for example)

	git fetch some-other-repo branch
	gitk ..FETCH_HEAD
	git cherry-pick <some-particular-commit-you-picked>

 - "MERGE_HEAD" is kind of the opposite of "ORIG_HEAD" when you're in 
   the middle of a merge: it's the "other" branch that you're merging.

   It's mainly useful for merge resolution, ie

	git log -p HEAD...MERGE_HEAD -- some/file/with/conflicts

   is a great way to see what happened along both branches (note the 
   _triple_ dot: it's a symmetric difference), to see _why_ the confict 
   happened.

Most of the above are used implicitly in various cases, not just HEAD. The 
"--merge" flag to git-rev-list (and thus git log and friends) is just 
shorthand for the above "HEAD...MERGE_HEAD" behaviour (with the addition 
of also limiting the result to just conflicting files), so

	git log -p --merge

is basically exactly the same as the above (except for _all_ files that 
have conflicts in them rather than just one hand-specified one).

Anyway, maybe somebody didn't know about these, and finds them useful. 
Normally, the only one you would _really_ use is "ORIG_HEAD" (which is 
described in several of the tutorials and examples, so people hopefully 
already know about it). Most of the others tend to mostly be used 
implicitly, not by explicitly naming them - although you _can_.

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Shawn Pearce]

Linus Torvalds <torvalds@osdl.org> wrote:
>  - "ORIG_HEAD" is very useful indeed, and it's the head _before_ a merge 
>    (or some other operations, like "git rebase" and "git reset": think of 
>    it as a "original head before we did some uncontrolled operation 
>    where we otherwise can't use HEAD^ or similar")
> 
>    I use "gitk ORIG_HEAD.." a lot, and if I don't like something I see 
>    when I do it, I end up doing "git reset --hard ORIG_HEAD" to undo a 
>    pull I've done. This is important exactly because ORIG_HEAD is _not_ 
>    the same as the first parent of a merge, since a merge could have been 
>    just a fast-forward.

Although if you have reflog enabled on your current branch there
is a 1 character shorter syntax:

	gitk HEAD@{1}..

as recent Git understands that to mean the value that HEAD just had,
which is also what is in ORIG_HEAD.  Except that unlike ORIG_HEAD
it can also show even older values (e.g. HEAD@{3}, 3 ops back)
and it works very, very well on tracking branches.  "What did I
just fetch in next?" `git log next@{1}..next`

-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1391 bytes --]



On Fri, 17 Nov 2006, Shawn Pearce wrote:
> 
> Although if you have reflog enabled on your current branch there
> is a 1 character shorter syntax:
> 
> 	gitk HEAD@{1}..

Heh. With a finnish keyboard, that "@" is AltGr+'2', and the '{'/'}' is 
AltGr+'7'/'0', I guarantee that it's not "1 character shorter", it's 
"three pretty complicated characters longer" and "off the normal path 
where you hold your fingers on the keyboard ;)

And that's not even mentioning that '{'/'}' is a magic sequence for 
filename expansion to the shell, so every time I see that, I have to think 
about it (and it turns out that because there is no comma in between 
there, it's ok. Otherwise you would need to quote it or escape them...)

So the reflog syntax is fine, but it's definitely not a "simple" syntax. 
I'd only use it for things where I want something that ORIG_HEAD won't 
give me ("ORIG_HEAD" you can type by just holding the shift key down all 
the time, and letting your fingers dance over the keyboard, both on a US 
and a Finnish keyboard).

And yes, I actually use a Finnish keyboard, still. Don't ask me why. I 
don't actually need the åäö characters often enough for it to matter, and 
I have used US keyboards elsewhere enough that I can switch between the 
two without thinking, but I still ended up having my sister ship me a 
keyboard from Finland when I wanted to upgrade..

			Linus

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Carl Worth]

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

On Fri, 17 Nov 2006 08:45:39 -0800 (PST), Linus Torvalds wrote:
> > Although if you have reflog enabled on your current branch there
> > is a 1 character shorter syntax:
> >
> > 	gitk HEAD@{1}..
>
> Heh. With a finnish keyboard, that "@" is AltGr+'2', and the '{'/'}' is
> AltGr+'7'/'0', I guarantee that it's not "1 character shorter", it's
> "three pretty complicated characters longer" and "off the normal path
> where you hold your fingers on the keyboard ;)

It's not even all that convenient on a U.S. keyboard. My pinky suffers
a bit having to pop on and off of shift for the '{', '1', '}'. Then
again, I don't like having to hold shift down for all of ORIG_HEAD
either, (but it's definitely easier in comparison).

But since reflog does everything ORIG_HEAD does and more, shall we
just clean up the syntax somehow? Ideas anyone? And then fix the
documentation to explain that?

-Carl

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

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Shawn Pearce]

Linus Torvalds <torvalds@osdl.org> wrote:
> On Fri, 17 Nov 2006, Shawn Pearce wrote:
> > 
> > Although if you have reflog enabled on your current branch there
> > is a 1 character shorter syntax:
> > 
> > 	gitk HEAD@{1}..
> 
> Heh. With a finnish keyboard, that "@" is AltGr+'2', and the '{'/'}' is 
> AltGr+'7'/'0', I guarantee that it's not "1 character shorter", it's 
> "three pretty complicated characters longer" and "off the normal path 
> where you hold your fingers on the keyboard ;)

I forgot that you use a finnish keyboard.  :-)

I agree with you; its not easier to type, for you.  Me, I'm a dumb
American who uses a Kinesis keyboard, therefore my left foot is
my shift key and its in sync with my fingers.  I have no extra
pinky load for either syntax.  And since the reflog syntax works
in a lot more contexts (e.g. after a fetch into a tracking branch)
I have just forgotten about ORIG_HEAD entirely.  Oh sure, I know
its there, but its not something I think about using...

-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Carl Worth]

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

On Fri, 17 Nov 2006 11:26:05 -0500, Shawn Pearce wrote:
> Linus Torvalds <torvalds@osdl.org> wrote:
> >  - "ORIG_HEAD" is very useful indeed, and it's the head _before_ a merge
...
> Although if you have reflog enabled on your current branch there
> is a 1 character shorter syntax:
>
> 	gitk HEAD@{1}..

Yes, this was my exact thought when reading what Linus
wrote. ORIG_HEAD might be fine and all, but it pales in functionality
compared to what reflog provides.

I would very much like to see reflog getting first-class citizen
support in git:

1. Be on by default

2. Get documented in all the right places, (much better than adding
   documentation for ORIG_HEAD in my opinion)

3. Tighter integration with branch manipulations. Do we already delete
   reflog when deleting a branch? We don't have a branch rename
   operation, but if we get one, renaming the reflog should go
   hand-in-hand, etc.

-Carl

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

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Shawn Pearce]

Carl Worth <cworth@cworth.org> wrote:
> Yes, this was my exact thought when reading what Linus
> wrote. ORIG_HEAD might be fine and all, but it pales in functionality
> compared to what reflog provides.
> 
> I would very much like to see reflog getting first-class citizen
> support in git:
> 
> 1. Be on by default

I have:

	git repo-config --global core.logAllRefUpdates true

especially since Junio fixed it to only create logs for heads and
not tags.  That way its on by default for me.  But I think it should
be on by default in the next version of Git.
 
> 2. Get documented in all the right places, (much better than adding
>    documentation for ORIG_HEAD in my opinion)

Agreed.  I'm not likely to do it anytime soon however, so I'm hoping
someone else will do it...  :-)
 
> 3. Tighter integration with branch manipulations. Do we already delete
>    reflog when deleting a branch? We don't have a branch rename
>    operation, but if we get one, renaming the reflog should go
>    hand-in-hand, etc.

Yes, we delete the log when we delete the branch, and we prune
back the empty directories too just like we do on the branch side,
so that new branches can be correctly created.

There was a recent discussion about that from Junio if I recall.
Several people that I work with have asked that branch rename
support be added to Git, and that if you rename the branch the
reflog follows.  Because in their mind they are simply changing
the name of the branch, any old history of that branch should
stick around.

I tried to think of an option to "git branch" to do the rename but
kept thinking that:

	git rename-branch old new

is the better syntax...  even though that's command number 133
or something like that...

We should stick a "null" event into the reflog during a branch
rename.  Make both the old and new SHA1 the current SHA1 but drop
a message in saying "renamed branch old -> new" (for example).

-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Marko Macek]

Shawn Pearce wrote:
> Carl Worth <cworth@cworth.org> wrote:
>> Yes, this was my exact thought when reading what Linus
>> wrote. ORIG_HEAD might be fine and all, but it pales in functionality
>> compared to what reflog provides.
>>
>> I would very much like to see reflog getting first-class citizen
>> support in git:
>>
>> 1. Be on by default

I agree.

> I have:
> 
> 	git repo-config --global core.logAllRefUpdates true
> 
> especially since Junio fixed it to only create logs for heads and
> not tags.  That way its on by default for me.  But I think it should
> be on by default in the next version of Git.

Why is it not useful for tags for having logs? 

I also have a question:

Does git-fsck-objects/prune check the ref logs?

Mark

Re: multi-project repos

[Junio C Hamano]

Marko Macek <marko.macek@gmx.net> writes:

> Shawn Pearce wrote:
>...
>> I have:
>>
>> 	git repo-config --global core.logAllRefUpdates true
>>
>> especially since Junio fixed it to only create logs for heads and
>> not tags.  That way its on by default for me.  But I think it should
>> be on by default in the next version of Git.
>
> Why is it not useful for tags for having logs?

When I make a tag that says "this is the v1.2.0 release", it is
expected it won't change in the future, ever.  I _can_ make
mistake and tag a wrong commit under v1.2.0 name, in which case
I may have to replace it with another corrected tag, but
recoding that mistake does not really add value.  So most of the
time ref-log for a tag would contain only one entry per file, its
creation, but that creation time is already recorded in the tag
object itself anyway.

At times, it may be useful to have some floating tag that point
at the "latest", or "today's", but that use is a minority.  For
these minority cases, you can manually create an empty file
under .git/logs/ directory to record their updates.

The configuration mechanism only kicks in when there is no such
existing file to prime the process, and not creating ref-log for
tags by default is the sensible thing to do.

> I also have a question:
>
> Does git-fsck-objects/prune check the ref logs?

They deliberately ignore ref-log for the same reason lost-found
does not drop found refs under .git/refs hierarchy.

This only matters if you somehow rewind an existing branch in
order to lose part of its history, using "reset --hard HEAD~n"
or "rebase".  If the updates to your branch tips always build on
top of the previous (either by commiting on top of the current,
merging on top of the current, or fast-forwarding), and if you
never rewind the branch, the commits recorded in the ref-log for
the branch are always ancestors of the tip of the branch, so
checking ref-log does not give you anything other than slowing
the operation down.

However, if you rewind the tip of a branch, the story changes.
Until the next "prune", objects reachable from the ref-log of
the branch but not reachable from the tip of the branch are
still available in your object store and in a pinch you can
recover them, but after a "prune" they will be lost forever if
they do not have any other references.  So it might seem that
they should be protected from pruning.

But if you did so, you can never remove cruft from your object
store once you make a mistake.  You can clean up your history by
a reset and/or a rebase, and cleaning up to _lose_ part of the
history was the reason you rewound the branch in the first
place.

In other words, running 'prune' is a conscious act of saying "I
know I am not in the middle of something; I thought over what
I've done recently, salvaged necessary bits from what I
discarded earlier, and there is nothing that need to be salvaged
later anymore -- I have refs to what I need.  Now go clean up
the cruft from my object store".

Re: multi-project repos

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Linus Torvalds <torvalds@osdl.org> wrote:
>>  - "ORIG_HEAD" is very useful indeed, and it's the head _before_ a merge 
>>    (or some other operations, like "git rebase" and "git reset": think of 
>>    it as a "original head before we did some uncontrolled operation 
>>    where we otherwise can't use HEAD^ or similar")
>> 
>>    I use "gitk ORIG_HEAD.." a lot, and if I don't like something I see 
>>    when I do it, I end up doing "git reset --hard ORIG_HEAD" to undo a 
>>    pull I've done. This is important exactly because ORIG_HEAD is _not_ 
>>    the same as the first parent of a merge, since a merge could have been 
>>    just a fast-forward.
>
> Although if you have reflog enabled on your current branch there
> is a 1 character shorter syntax:
>
> 	gitk HEAD@{1}..

Are you sure about this?  I've seen "next@{1}" to look at
history of the named branch, but never history of "HEAD".

Re: multi-project repos

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Shawn Pearce <spearce@spearce.org> writes:
> > Although if you have reflog enabled on your current branch there
> > is a 1 character shorter syntax:
> >
> > 	gitk HEAD@{1}..
> 
> Are you sure about this?  I've seen "next@{1}" to look at
> history of the named branch, but never history of "HEAD".
 
Yes.  :-)

If the ref name is a symref then we resolve the symref all the
way down to the real ref before we open and walk the reflog.
Therefore this works.

-- 

Re: multi-project repos

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> Shawn Pearce <spearce@spearce.org> writes:
>> > Although if you have reflog enabled on your current branch there
>> > is a 1 character shorter syntax:
>> >
>> > 	gitk HEAD@{1}..
>> 
>> Are you sure about this?  I've seen "next@{1}" to look at
>> history of the named branch, but never history of "HEAD".
>  
> Yes.  :-)
>
> If the ref name is a symref then we resolve the symref all the
> way down to the real ref before we open and walk the reflog.
> Therefore this works.

True, except if you did:

        $ git pull
        $ git checkout otherbranch
        $ git show HEAD@{1}

My real point was that I was wondering if it also makes sense
for ref-log to record switching branches for the symref itself.

But after sending that message I thought about it a bit more and
concluded that it is not an interesting information.  It is more
code that affects unrelated places even if we were to implement
it and without real gain, so let's not log symref itself and
keep the current implementation.

Re: multi-project repos

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> True, except if you did:
> 
>         $ git pull
>         $ git checkout otherbranch
>         $ git show HEAD@{1}
> 
> My real point was that I was wondering if it also makes sense
> for ref-log to record switching branches for the symref itself.
> 
> But after sending that message I thought about it a bit more and
> concluded that it is not an interesting information.  It is more
> code that affects unrelated places even if we were to implement
> it and without real gain, so let's not log symref itself and
> keep the current implementation.

I agree completely.

I have no interest in a history of what branches I've recently
been on.  All I care about is the history of this branch.  And I
consider HEAD to be nothing but a shortcut that always points to
the current branch... so its darn useful for that.

In retrospect CURR may have been a better name for the HEAD symref
but its far too late to even consider changing that, so lets not
go down that road.  :-)

-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Linus Torvalds wrote:

> On Thu, 16 Nov 2006, Han-Wen Nienhuys wrote:
> > 
> > * why are objects downloaded twice?  If I do
> > 
> >   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master
> > 
> > it downloads stuff, but I don't get a branch.
> 
> A "fetch" by default won't actually generate a local branch unless you 
> told it to.

This is actually a perfect example for

- a script that is porcelain as well as plumbing (you are supposed to use 
it directly, or via pull), and for

- a terrible UI.

_If_ you use git-fetch directly you virtually always want to store the 
result. I was tempted quite often to submit a patch which adds a command 
line switch --no-warn, which is passed to git-fetch by git-pull, and 
without which git-fetch complains if the branch-to-be-fetched is not 
stored right away (and refuses to go along).

_Also_, git-pull not storing the fetched branches at least temporarily 
often annoyed me: the pull did not work, and the SHA1 was so far away I 
could not even scroll to it. The result: I had to pull (and fetch!) the 
whole darned objects again. Again, I was tempted quite often to submit a 
patch which makes git-pull fetch the branches into refs/fetch-temp/* and 
only throw them away when the merge succeeded.

Ciao,
Dscho

Re: multi-project repos

[Junio C Hamano]

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

> _If_ you use git-fetch directly you virtually always want to store the 
> result. I was tempted quite often to submit a patch which adds a command 
> line switch --no-warn, which is passed to git-fetch by git-pull, and 
> without which git-fetch complains if the branch-to-be-fetched is not 
> stored right away (and refuses to go along).
>
> _Also_, git-pull not storing the fetched branches at least temporarily 
> often annoyed me: the pull did not work, and the SHA1 was so far away I 
> could not even scroll to it. The result: I had to pull (and fetch!) the 
> whole darned objects again. Again, I was tempted quite often to submit a 
> patch which makes git-pull fetch the branches into refs/fetch-temp/* and 
> only throw them away when the merge succeeded.

I think the earlier write-up by Linus on magic HEADs would help
documenting FETCH_HEAD better.

Re: multi-project repos

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Junio C Hamano wrote:

> I think the earlier write-up by Linus on magic HEADs would help 
> documenting FETCH_HEAD better.

I am not sure that documenting FETCH_HEAD better would help. As Han-Wen 
pointed out (and some colleagues of mine who would never subscribe to a 
mailing list), people do not read the manual, but rather try to wrap their 
heads around the inner workings from the interface. And FETCH_HEAD just 
does not meet _any_ expectation a sane (read: untainted) user might have.

While I'm at it: the problem I pointed out with -pull may annoy just me.

But there is another problem with "git fetch": a common work flow is 
tracking other peoples branches. And since git makes it so easy to 
have multiple branches, chances are that you track more than one 
branch per remote repository.

Now, an old gripe of mine was the lack of "git fetch --all". I wrote a 
script for that (Linus would be proud of me!), which just does "git 
ls-remote" and constructs a command line for "git fetch" from that.

But even if you agree with the common story that you should specify the 
branches you want to track: it is hard!

If I were new to git, after reading some tutorials I would _expect_ "git 
fetch" to be the tool to track branches. (I posted a patch to at least be 
able to store the current "git fetch" command line under a nick IIRC). But 
it does not.

(Of course, after reading several documentation, as a new user I would 
eventually find that I should edit .git/remotes/<nick>, or even 
edit/-repo-config the remotes information in the config, but I would fully 
expect a new user to give up before reaching that stage.)

But maybe I got it all wrong and this is not the common expectation...

Ciao,
Dscho

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

On Thu, 16 Nov 2006, Johannes Schindelin wrote:
>
> - a terrible UI.

Why? We _do_ have the temporary branch. It's called FETCH_HEAD.

> _Also_, git-pull not storing the fetched branches at least temporarily 
> often annoyed me: the pull did not work, and the SHA1 was so far away I 
> could not even scroll to it.

Again, why didn't you use FETCH_HEAD?

If the user doesn't give us a head to write to, we clearly MUST NOT write 
to any long-term branch. That would be a _horrible_ mistake. 

So all your complaints seem totally misplaced. The UI is both usable and 
practical, and your complaint that git pull doesn't store the fetched 
branches is just NOT TRUE.

And your "solution" is obviously totally unusable. git ABSOLUTELY MUST NOT 
overwrite any existing branches unless explicitly told to do so by the 
user.

So I really don't see your point. 

A lot of the complaints seem to not be about the interfaces, but about 
people not _understanding_ and knowing what the interfaces do. If you were 
confused about something (like not realizing that FETCH_HEAD is there and 
very much usable), how about sending in a patch to make FETCH_HEAD use 
clearer in whatever docs you looked at and didn't find it mentioned in.

Now, there is no question that some of the interfaces can get a bit 
"interesting" to use. For example, if you really don't want to re-fetch 
for some reason, FETCH_HEAD actually does contain enough information that 
you should be able to just re-do a failed merge, for example, including 
the message generation. But at that point it really _does_ get a bit 
complicated, and you end up doing something like

	git merge "$(git fmt-merge-msg < .git/FETCH_HEAD)" HEAD FETCH_HEAD

which should _work_, but I'm not going to claim that it's all that easy to 
understand.

(That said, read that one-liner a few times, and suddenly it doesn't seem 
_that_ complicated any more, now does it? You can probably even guess what 
it's really going to do, even if you don't know git all that well. It's 
not unreadable line noise, is it?)

Of course, if I had a merge that failed (the most common reason being that 
I had some uncommitted patch in a file that wanted to be updated by the 
merge), I'd never actually do the above one-liner. I'd just re-do the 
pull. But if networking was _really_ slow, and I _really_ cared, maybe I'd 
do the above.

(And no, I didn't actually test the above one-liner. Maybe it doesn't work 
for some reason. Somebody should check, just for fun).

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
>
> 	git merge "$(git fmt-merge-msg < .git/FETCH_HEAD)" HEAD FETCH_HEAD

Btw, I'd like to claim that this is a _great_ user interface.

Yeah, it's different from other SCM's. I don't think you'd really want to 
script a merge like this in CVS, especially not using standard UNIX 
pipelines etc. But it's an example of how a lot of git operations - even 
the "high level ones" are pretty scriptable, using very basic and very 
simple standard UNIX shell scripting.

So even though I'd not actually _do_ the above one-liner, I think it's a 
great example of how git really works, and how scriptable it can be, 
without a lot of huge problems.

So considering that "FETCH_HEAD" works pretty much everywhere, and that 
you can also use the totally non-scripting approach of doing "standard" 
SCM things like

	git diff ..FETCH_HEAD

or 

	gitk HEAD...FETCH_HEAD

to look at what got fetched (and in the latter case look at both the 
current HEAD _and_ FETCH_HEAD, and what was in one but not the other), I 
really think it's unfair to say that "git fetch" does not have a nice UI.

It's just that "git fetch" can be used two totally different ways:

 - "git fetch" to get something temporary: use FETCH_HEAD, and do _not_ 
   specify a destination branch

 - "git fetch" as a way to update the branches you already have, by either 
   using explicit branch specifiers (which would be unusual, but works), 
   or by just having the branch relationships listed in your .git/remotes/ 
   file or .git/config file.

both are actually very natural things to do.

What is probably _not_ that natural is to do the explicit branch 
specifier, ie

	git fetch somerepo remotebranch:localbranch

which obviously works, but you wouldn't want to actually do this very 
often. Either you do something once (and use FETCH_HEAD, which is actually 
nicer than a real branch in some respects: it also tells you were you 
fetched _from_, and it can contain data on merging from _multiple_ 
branches), or you set up a "real translation" in your configuration files.

So I would say that the natural thing to do is:

 - "git pull somerepo"

   This will _also_ fetch all the branches you've said you want to track, 
   of course.

 - "git fetch somerepo somebranch"

   Look at FETCH_HEAD, and be happy

 - "git fetch somerepo"

   This is kind of strange, but it can be useful if you are basically just 
   mirroring another repo, and want to fetch all the branches you've said 
   you want to track, but don't actually want to check them out.

while the "complicated" scenario like the following is something you 
should generally _avoid_, because it's just confusing and complex:

 - "git fetch somerepo branch1:mybranch1 branch2:mybranch2"

   This works, and I'm sure it's useful, and I've even used it (usually 
   with just one branch, though), but let's face it - it's too damn 
   complicated to be anything you want to do _normally_.

So git is definitely powerful, but I think some people have looked at the 
_complicated_ cases more than the simple cases (ie maybe people have 
looked too much at that last case, not realizing that there really isn't 
much reason to use it - and FETCH_HEAD is one big reason why you seldom 
need the complicated format).

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Linus Torvalds wrote:

> On Thu, 16 Nov 2006, Johannes Schindelin wrote:
> >
> > - a terrible UI.
> 
> Why? We _do_ have the temporary branch. It's called FETCH_HEAD.

It is a terrible UI, because it was not that obvious to me. And I consider 
myself not a git newbie.

Besides, it is not really a temporary branch. If it was, the pull would 
_not_ download all these objects again, would it?

> > _Also_, git-pull not storing the fetched branches at least temporarily 
> > often annoyed me: the pull did not work, and the SHA1 was so far away I 
> > could not even scroll to it.
> 
> Again, why didn't you use FETCH_HEAD?

Because I am a Jar-HEAD?

> If the user doesn't give us a head to write to, we clearly MUST NOT write 
> to any long-term branch. That would be a _horrible_ mistake. 

I was _not_ suggesting a long-term branch. Just a way to do-what-i-want 
and not waste bandwidth.

> And your "solution" is obviously totally unusable. git ABSOLUTELY MUST NOT 
> overwrite any existing branches unless explicitly told to do so by the 
> user.

Guess three times why I did not post the patches.

But the real problem is not necessarily the behaviour; it is the obscure 
fashion of the behaviour. You may not understand that problem, because you 
were there from the beginning. You saw the big-bang and how all the 
quarks formed all of a sudden, and how matter and eventually planets 
and suns came into being.

But others (me included) were not there. Or they did not really watch. And 
now they see all these creatures, and plants, and bacteria, and they do 
not understand how these are all connected, because of that. And now they 
think "wow that must have been some intelligent design, and really a 
miracle, and I cannot understand how it works." But that is not true 
(the latter part of course).

There is something to be said about the simplicity of Mercurial. It's 
inner workings may suck, but people get easily attracted by it.

I do not claim we should imitate Mercurial, or even hide the index (even 
if I sometimes wonder if the index is not just a clever way to accelerate 
commits, and nothing more).

> So I really don't see your point. 
> 
> A lot of the complaints seem to not be about the interfaces, but about 
> people not _understanding_ and knowing what the interfaces do.

But the interfaces should be usable interfaces! They should _explain_ what 
they do. Other software does so, it can't be _that_ hard.

> 	git merge "$(git fmt-merge-msg < .git/FETCH_HEAD)" HEAD FETCH_HEAD

I find that quite easy to understand. Why? Because I happen to _know_ the 
syntax of -merge and -fmt-merge-msg. For similar reasons I _understand_ 
why -pull behaves like it does. But others don't; they will shudder and 
then run.

Maybe it is not important that -pull fetches all objects all over again. 
But it _is_ important to make things like merging branches (local or 
remote) trivial. It _is_ important to make the user experience be fun.

Ciao,
Dscho

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Linus Torvalds]

On Fri, 17 Nov 2006, Johannes Schindelin wrote:
> > Why? We _do_ have the temporary branch. It's called FETCH_HEAD.
> 
> It is a terrible UI, because it was not that obvious to me. And I consider 
> myself not a git newbie.

Heh. The "temporary branches" are actually the _original_ branches as far 
as git is concerned. The long-term branches only came later.

So in many ways, HEAD, FETCH_HEAD, MERGE_HEAD and ORIG_HEAD are more 
fundamental than any long-term branch has ever been, and maybe they should 
be taught first as such.

So you're newbie enough that you've only seen those new-fangled "real" 
branches.

When I was young, we had to walk to school up-hill in three feet of snow 
every day. And we _liked_ our FETCH_HEAD's.

> Besides, it is not really a temporary branch. If it was, the pull would 
> _not_ download all these objects again, would it?

Well, exactly because they are temporary, we can't actually trust the 
objects they point to. They have no "real" long-term life, so no, I'm 
afraid that we always will have to re-fetch the objects, because fetching 
them is the only way to know that we still have them. 

That said, we could certainly _make_ them be honored by things like "git 
prune" and friends. But yes, they really _are_ temporary branches right 
now, and part of the meaning of that "temporary" is exactly the fact that 
git fetch will not trust that you still have the objects. 

For example, if you used one of the old-fashioned commit walkers, maybe we 
got the initial commit, but we may not have gotten the whole _chain_. See?

Temporary branch indeed.

> > Again, why didn't you use FETCH_HEAD?
> 
> Because I am a Jar-HEAD?

Well, we clearly should document them better. Anybody?

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Carl Worth]

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

On Thu, 16 Nov 2006 16:49:29 -0800 (PST), Linus Torvalds wrote:
> So in many ways, HEAD, FETCH_HEAD, MERGE_HEAD and ORIG_HEAD are more
> fundamental than any long-term branch has ever been, and maybe they should
> be taught first as such.

Older in git's history as it developed is not a good match for more
fundamental in the concepts that git makes available today.

> > > Again, why didn't you use FETCH_HEAD?
> >
> > Because I am a Jar-HEAD?
>
> Well, we clearly should document them better. Anybody?

I for one am totally unsatisfied with this approach.

Here's an operations I'd like to be able to do:

	Given a (URL, branch) pair I'd like I'd like to be able to
	investigate that code, (say with the fancy new "read-only
	branch" concept we've been talking about).

What are my options for this operation? What might a new user's
reaction to them be?

a) git fetch URL branch
   git checkout FETCH_HEAD

   This is really ugly. A name like "FETCH_HEAD" is something a user
   should really never have to type. It's hideously hard to type and
   has no natural discoverability. Yuck, yuck, yuck.

b) vi .git/remotes/something
   git fetch something
   git checkout branch

   Also yuck. I hope it's obvious that having to edit a configuration
   for this simple operation is a non-starter.

c) git fetch URL branch:local-branch
   git checkout local-branch

   We're getting close to the desired functionality now, but the UI
   makes users cringe? "What's that : for?" Why do I need another
   name?" etc. Linus, you yourself said this is a form that users
   should generally avoid.

d) git fetch URL branch:branch
   git checkout branch

   One step closer. But there's still that goofy extra ':' and a
   doubled name in the first command. "Why is that there? Git sure is
   weird...".

What I think this operation should look like is:

	git fetch URL branch
	git checkout branch

And the fetch should just complain if there's a name clash. Or better,
the fetch should tuck the fetched branch into its own URL-specific
namespace and then the checkout command can kindly prompt if there is
any ambiguity:

	Which "branch" do you want?
		local/branch
		remote-url/branch

or whatever.

See? That's what reasonable UI should look like.

Please feel free to keep using vestiges like FETCH_HEAD as much as you
like, but please don't recommend documenting them better as a solution
for UI warts in git. (If you would only look at these warts closer,
you'd see they have some lovely locks of hair on them.)

-Carl

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

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Johannes Schindelin]

Hi,

On Thu, 16 Nov 2006, Linus Torvalds wrote:

> On Fri, 17 Nov 2006, Johannes Schindelin wrote:
> 
> > Besides, it is not really a temporary branch. If it was, the pull would 
> > _not_ download all these objects again, would it?
> 
> Well, exactly because they are temporary, we can't actually trust the 
> objects they point to.

Nonono.

We made _sure_ that FETCH_HEAD is only written once _all_ the objects were 
received. So, actually, we _can_, and we _should_ trust the objects they 
point to!

Or did I miss something?

> For example, if you used one of the old-fashioned commit walkers, maybe we 
> got the initial commit, but we may not have gotten the whole _chain_. See?

Huh? I am quite certain that FETCH_HEAD is not updated in that case. If it 
is, that's a bug.

Ciao,

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Petr Baudis]

On Fri, Nov 17, 2006 at 02:22:35AM CET, Johannes Schindelin wrote:
> On Thu, 16 Nov 2006, Linus Torvalds wrote:
> > For example, if you used one of the old-fashioned commit walkers, maybe we 
> > got the initial commit, but we may not have gotten the whole _chain_. See?
> 
> Huh? I am quite certain that FETCH_HEAD is not updated in that case. If it 
> is, that's a bug.

It may be updated and then things may break _afterwards_. git-prune will
happily blow anything referenced by FETCH_HEAD, it's not considered by
the fsck-objects reachability analysis.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Johannes Schindelin]

Hi,

On Fri, 17 Nov 2006, Petr Baudis wrote:

> On Fri, Nov 17, 2006 at 02:22:35AM CET, Johannes Schindelin wrote:
> > On Thu, 16 Nov 2006, Linus Torvalds wrote:
> > > For example, if you used one of the old-fashioned commit walkers, maybe we 
> > > got the initial commit, but we may not have gotten the whole _chain_. See?
> > 
> > Huh? I am quite certain that FETCH_HEAD is not updated in that case. If it 
> > is, that's a bug.
> 
> It may be updated and then things may break _afterwards_. git-prune will
> happily blow anything referenced by FETCH_HEAD, it's not considered by
> the fsck-objects reachability analysis.

This actually underlines my point: FETCH_HEAD is no _real_ branch, not 
even a temporary one. If it was, git-prune would not lose the related 
objects.

Ciao,
Dscho

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> A lot of the complaints seem to not be about the interfaces, but about 
> people not _understanding_ and knowing what the interfaces do. If you were 

From the point of view of a user, there is not really a difference
between the two.  As a user, you form a mental model of how things
work by looking at the interface. If the interface is bad, the user
creates a faulty model in his head, and starts doing things that
are perfectly logical in the faulty model, but stupid and silly when
you consider the actual internals.

A nice book about this is "The Design of Everyday Things" by Donald
Norman.

-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
>> You're misunderstanding me: the multi-repo is at git.sv.gnu.org is the
>> remote one. The example I gave was about locally creating a single
>> project repo from a remote multiproject repo. 
> 
> Ahh.
> 
> Ok, try the patch I just sent out, and see if it works for you. It 
> _should_ allow you to do exactly that

I'm leaving for a short holiday tomorrow, but will do when I come back.

>> From UI perspective it would be nice if this could also be done with clone,
>>
>>   git clone . ssh+git://....
> 
> The creation of a new archive tends to need special rights (with _real_ 
> ssh access and a shell you could do it, but "ssh+git" really means "git 
> protocol over a connection that was opened with ssh, but doesn't 
> necessarily have a real shell at the other end").

What happens on savannah is that the sysadmins set up an empty GIT
repo with access, and leave it to you to push the stuff.  Of course,
if the initial import gets packed automatically, that's also ok.

> So I think the above syntax is actually not a good one, because it cannot 
> work in the general case. It's much better to get used to setting up a 
> repo first, and then pushing into it, and just accepting that it's a 
> two-phase thing.

Perhaps ; from a UI viewpoint, it would be nice though, even if it
were aliased to a simple push. (Darcs has a get command analogous to
git-clone, but also a put command to which git lacks the equivalent).

>> * why are objects downloaded twice?  If I do
>>
>>   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master
>>
>> it downloads stuff, but I don't get a branch.
> [..] 
>> If I then do 
>>
>>   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master:master
>>
>> it downloads the same stuff again. 
> 
> Right. So you can either
> [..]
> See?

No, I don't understand. In the fetch all the objects with their SHA1s
were already downloaded. I'd expect that the fetch with a refspec
would simply write a HEAD and a refs/heads/master, and notice that all
the actual data was already downloaded, and doesn't download it again. 


-- 

Re: multi-project repos (was Re: Cleaning up git user-interface warts)

[Jakub Narebski]

Han-Wen Nienhuys wrote:
> Linus Torvalds escreveu:

>>> If I then do 
>>>
>>>   git --bare fetch git://git.sv.gnu.org/lilypond.git web/master:master
>>>
>>> it downloads the same stuff again. 
>> 
>> Right. So you can either
>> [..]
>> See?
> 
> No, I don't understand. In the fetch all the objects with their SHA1s
> were already downloaded. I'd expect that the fetch with a refspec
> would simply write a HEAD and a refs/heads/master, and notice that all
> the actual data was already downloaded, and doesn't download it again. 

But how git is to know that you have this already downloaded? Git compares
_refs_ on the local and remote side to calculate what needs to be
downloaded. It does not (and should not) send all the objects IDs local
side has.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
> 
> (And the real reason for that is simple: "git pull" simply wants to have 
> something to _start_ with. It's not hugely fundamental, it's just how it 
> was written).

Here's a very lightly tested patch that allows you to use "git pull" to 
populate an empty repository.

I'm not at all sure this is necessarily the nicest way to do it, but it's 
fairly straightforward.

Junio, what do you think?

		Linus

---
diff --git a/git-pull.sh b/git-pull.sh
index ed04e7d..7e5cee2 100755
--- a/git-pull.sh
+++ b/git-pull.sh
@@ -44,10 +44,10 @@ do
 	shift
 done
 
-orig_head=$(git-rev-parse --verify HEAD) || die "Pulling into a black hole?"
+orig_head=$(git-rev-parse --verify HEAD 2> /dev/null)
 git-fetch --update-head-ok --reflog-action=pull "$@" || exit 1
 
-curr_head=$(git-rev-parse --verify HEAD)
+curr_head=$(git-rev-parse --verify HEAD 2> /dev/null)
 if test "$curr_head" != "$orig_head"
 then
 	# The fetch involved updating the current branch.
@@ -80,6 +80,11 @@ case "$merge_head" in
 	exit 0
 	;;
 ?*' '?*)
+	if test -z "$orig_head"
+	then
+		echo >&2 "Cannot merge multiple branches into empty head"
+		exit 1
+	fi
 	var=`git-repo-config --get pull.octopus`
 	if test -n "$var"
 	then
@@ -95,6 +100,12 @@ case "$merge_head" in
 	;;
 esac
 
+if test -z "$orig_head"
+then
+	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
+	exit
+fi
+
 case "$strategy_args" in
 '')

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> On Thu, 16 Nov 2006, Linus Torvalds wrote:
>> 
>> (And the real reason for that is simple: "git pull" simply wants to have 
>> something to _start_ with. It's not hugely fundamental, it's just how it 
>> was written).
>
> Here's a very lightly tested patch that allows you to use "git pull" to 
> populate an empty repository.
>
> I'm not at all sure this is necessarily the nicest way to do it, but it's 
> fairly straightforward.
>
> Junio, what do you think?

Yeah, I talked about making "merge" treat missing HEAD as a
special case of fast forward, but I like yours better.  It is a
lot cleaner and to the point.

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Linus Torvalds wrote:
> @@ -95,6 +100,12 @@ case "$merge_head" in
>  	;;
>  esac
>  
> +if test -z "$orig_head"
> +then
> +	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
> +	exit
> +fi
> +

So this is the place that probably wants a "git-checkout" before the 
exit, otherwise you'd (illogically) have to do it by hand for that 
particular case.

Of course, we should _not_ do it if the "--bare" flag has been set, so you 
migth want to tweak the exact logic here.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> On Thu, 16 Nov 2006, Linus Torvalds wrote:
>> @@ -95,6 +100,12 @@ case "$merge_head" in
>>  	;;
>>  esac
>>  
>> +if test -z "$orig_head"
>> +then
>> +	git-update-ref -m "initial pull" HEAD $merge_head "" || exit 1
>> +	exit
>> +fi
>> +
>
> So this is the place that probably wants a "git-checkout" before the 
> exit, otherwise you'd (illogically) have to do it by hand for that 
> particular case.
>
> Of course, we should _not_ do it if the "--bare" flag has been set, so you 
> migth want to tweak the exact logic here.

As you said, pull inherently involve a merge which implies the
existence of associated working tree, so I do not think there is
any room for --bare to get in the picture.  We already do the
checkout when we recover from a fetch that is used incorrectly
and updated the current branch head underneath us.

To give the list a summary of the discussion so far, here is a
consolidated patch.

-- >8 --
From: Linus Torvalds <torvalds@osdl.org>
Subject: git-pull: allow pulling into an empty repository

We used to complain that we cannot merge anything we fetched
with a local branch that does not exist yet.  Just treat the
case as a natural extension of fast forwarding and make the
local branch'es tip point at the same commit we just fetched.
After all an empty repository without an initial commit is an
ancestor of any commit.

Signed-off-by: Junio C Hamano <junkio@cox.net>

---
diff --git a/git-pull.sh b/git-pull.sh
index ed04e7d..e23beb6 100755
--- a/git-pull.sh
+++ b/git-pull.sh
@@ -44,10 +44,10 @@ do
 	shift
 done
 
-orig_head=$(git-rev-parse --verify HEAD) || die "Pulling into a black hole?"
+orig_head=$(git-rev-parse --verify HEAD 2>/dev/null)
 git-fetch --update-head-ok --reflog-action=pull "$@" || exit 1
 
-curr_head=$(git-rev-parse --verify HEAD)
+curr_head=$(git-rev-parse --verify HEAD 2>/dev/null)
 if test "$curr_head" != "$orig_head"
 then
 	# The fetch involved updating the current branch.
@@ -80,6 +80,11 @@ case "$merge_head" in
 	exit 0
 	;;
 ?*' '?*)
+	if test -z "$orig_head"
+	then
+		echo >&2 "Cannot merge multiple branches into empty head"
+		exit 1
+	fi
 	var=`git-repo-config --get pull.octopus`
 	if test -n "$var"
 	then
@@ -95,6 +100,13 @@ case "$merge_head" in
 	;;
 esac
 
+if test -z "$orig_head"
+then
+	git-update-ref -m "initial pull" HEAD $merge_head "" &&
+	git-read-tree --reset -u HEAD || exit 1
+	exit
+fi
+
 case "$strategy_args" in
 '')
 	strategy_args=$strategy_default_args

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Thu, 16 Nov 2006, Junio C Hamano wrote:
> 
> As you said, pull inherently involve a merge which implies the
> existence of associated working tree, so I do not think there is
> any room for --bare to get in the picture.

Fair enough. Feel free to add the signed-off-by from me too, 

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Thu, 16 Nov 2006 09:17:32 -0800 (PST), Linus Torvalds wrote:
> So the way you'd normally set up a single repo that contains multiple
> other existing repositories is to basically start with one ("git clone")
> and then add the other branches and "git fetch" them.

For that we'd also need a way for clone to be able to fetch just a
single branch, and not all of them as well.

There is some clone vs. fetch asymmetry here that has annoyed me for a
while, and that I don't think has been mentioned in this thread
yet. Namely:

clone: can only be executed once, fetches all branches, "remembers"
       URLs for later simplified use

fetch: can be executed many times, fetches only named branches,
       doesn't remember anything for later

I've often been in the situation where I cloned a long time ago, but
I'd like to be able to fetch everything that I would get if I were to
start a fresh clone.

-Carl

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

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> Peopel seem to believe that changign a few names or doing other totally 
> _minimal_ UI changes would somehow magically make things understandable. 

Never ever underestimate pet peeves. If we give many people an obvious 
reason (however trivial and bike-shed-coloured) to complain, they will 
complain.

If we pull (pun intended) that reason away under their collective 
backsides, they will have to find another reason to complain. But by the 
time they found something, they will already be happy git users!

But since you just provided a patch to make life easier on non-gitters, I 
guess you agree with that already.

And hopefully you also agree that enhancing the syntax of git-merge to 
grok "git-merge [-m message] <branch>" and "git-merge [-m message] 
<url-or-remote> <branch>" would be a lovely thing, luring even more 
people into using git.

Maybe they even start complaining about subversion and CVS calling a merge 
"update", who knows?

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Fri, 17 Nov 2006, Johannes Schindelin wrote:
> 
> Never ever underestimate pet peeves. If we give many people an obvious 
> reason (however trivial and bike-shed-coloured) to complain, they will 
> complain.

I do actually think that this discussion has been informative, partly 
because I never even realized that some people would ever think to do 
"init-db" + "pull". 

Making things like that work is easy enough, it's just that I never saw 
any point until people complained. And when they complained, the initial 
complaint wasn't actually obvious. Only when Han-Wen actually gave 
something that didn't work, was it clear that the real issue wasn't so 
much _naming_, as just expectations about the _work_flow_.

> And hopefully you also agree that enhancing the syntax of git-merge to 
> grok "git-merge [-m message] <branch>" and "git-merge [-m message] 
> <url-or-remote> <branch>" would be a lovely thing, luring even more 
> people into using git.

I definitely think we can make "git merge" have a more pleasant syntax. 
I'm just still not sure that people should actually use it ;)

My real point was/is that usually it's really not the "naming details" 
that people _really_ have problems with. The real problems tend to be in 
learning a new workflow.

We can make some of those workflows easier, but I would heartily recommend 
that people not worry about naming of "pull" vs "fetch", because that's 
almost certainly not really the issue. Instead, if you have a problem, 
rather than concentrating on the names of the programs, say:

 - what do you want to get done.

   Most likely it's _trivial_ to do with git, it's just that somebody used 
   the wrong approach, and then it didn't work at all.

 - give actual examples of a workflow that didn't work or was complex.

   (again, the "init-db" + "pull" example). 

   And yes, in many cases, it might well be a case of "sure, we can make 
   that _other_ workflow work too". But somebody like me, who has used git 
   for a year and a half, and used BK before it, probably simply uses a 
   different workflow than somebody who comes from CVS. 

For example, I suspect that your gripe with "git fetch" was just from 
using it in a really awkward manner. Maybe we could make your workflow 
work with git too, but maybe it really already (and always) did, you just 
used a particular tool in a way that made the use be really really 
painful.

Sometimes it's just a question of "ok, use it like _this_, and now it's 
actually really simple". Other times it's "ok, I didn't even realize that 
you wanted to use it like _that_, and yeah, that's incredibly 
inconvenient, and we can change it".

I just got involved in this discussion because I thought people were 
talking about all the wrong things. Command naming really can't be _that_ 
big of a deal. I really don't believe that we should have some people use 
"gh" instead of "git" just because they think "pull" should mean not to 
merge or something.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> My real point was/is that usually it's really not the "naming details" 
> that people _really_ have problems with. The real problems tend to be in 
> learning a new workflow.

I agree that discussions on naming may cloud the issue, but "learning
the workflow" implies that people should adapt to the limitations of
their tools.  That's only a viable stance when the tools are finished
and completely perfect.

Until that time, it would be good goal to remove all idiosyncrasies,
all gratuitious asymetries and needless limitations in the commands of
git, eg.

 - clone but not a put-clone,

 - pull = merge + fetch, but no command for merge + throw

 - clone for getting all branches of a repo, but no command for
   updating all branches of a repo.  

Of course, when all warts are fixed, backward compatibility will force
us to choose some new names. At that point, a discussion on naming is
in place.


-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

>  - clone but not a put-clone,

What's put-clone?  Care to explain?

>  - pull = merge + fetch, but no command for merge + throw

What's merge+throw?  Care to explain?

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.  

This one I can understand, but how would you propose to "update
all branches", in other words what's your design for mapping
remote branch names to local branch namespaces?

It would be nice if the design does not straightjacket different
repository layouts different people seem to like, but I think it
would be Ok to limit ourselves only to support the straight
one-to-one mapping and support only separate-remote layout.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
> 
>>  - clone but not a put-clone,
> 
> What's put-clone?  Care to explain?

put clone would be the putative inverse of clone, ie. make a clone of
a local repository on a remote server.

>>  - pull = merge + fetch, but no command for merge + throw
> 
> What's merge+throw?  Care to explain?

throw is the hypothetical opposite of fetch. I agree that this is
academical, because it's logical to only allow fast-forwards for
sending revisions.

>>  - clone for getting all branches of a repo, but no command for
>>    updating all branches of a repo.  
> 
> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?
> 
> It would be nice if the design does not straightjacket different
> repository layouts different people seem to like, but I think it
> would be Ok to limit ourselves only to support the straight
> one-to-one mapping and support only separate-remote layout.

I think the whole clone design is a bit broken, in that the "master"
branch gets renamed or copied to "origin", but all of the other
branches remain unchanged in their names.

It's more logical for clone to either

 * leave all names unchanged

 * put all remote branches into a subdirectory.  This would also make
   it easier to track branches from multiple servers.

   At present,  I have in my build-daemon the following branches,

	cvs-head-repo.or.cz-lilypond.git
	hanwen-repo.or.cz-lilypond.git
	hwn-jcn-repo.or.cz-lilypond.git
	lilypond_1_0-repo.or.cz-lilypond.git
	lilypond_1_2-repo.or.cz-lilypond.git
	lilypond_1_4-repo.or.cz-lilypond.git
	lilypond_1_6-repo.or.cz-lilypond.git
	lilypond_1_8-repo.or.cz-lilypond.git
	lilypond_2_0-repo.or.cz-lilypond.git
	lilypond_2_2-repo.or.cz-lilypond.git
	lilypond_2_3_2b-repo.or.cz-lilypond.git
	lilypond_2_3_5b-repo.or.cz-lilypond.git
	lilypond_2_4-repo.or.cz-lilypond.git
	lilypond_2_6-repo.or.cz-lilypond.git
	lilypond_2_8-repo.or.cz-lilypond.git
	master-git.sv.gnu.org-lilypond.git
	master-hanwen
	master-repo.or.cz-lilypond.git
	origin-repo.or.cz-lilypond.git
	stable
	stable-2.10
	stable--2.10-git.sv.gnu.org-lilypond.git

  It would solve lots of problems for me if cloning and fetching would
  put branches into a subdirectory, ie.

    git clone git://repo.or.cz/lilypond.git

  leads to branches

    repo.or.cz/lilypond_2_8
    repo.or.cz/lilypond_2_6
    repo.or.cz/lilypond_2_4
    repo.or.cz/master
     (etc..)

	
-- 

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Fri, Nov 17, 2006 at 01:27:53AM CET, Han-Wen Nienhuys wrote:
> put clone would be the putative inverse of clone, ie. make a clone of
> a local repository on a remote server.

So effectively to tell git push not to unpack on the remote side, and to
push all branches and relevant tags.

..snip..
> It's more logical for clone to either
> 
>  * leave all names unchanged
> 
>  * put all remote branches into a subdirectory.  This would also make
>    it easier to track branches from multiple servers.
> 
>    At present,  I have in my build-daemon the following branches,
> 
> 	cvs-head-repo.or.cz-lilypond.git
> 	hanwen-repo.or.cz-lilypond.git
> 	hwn-jcn-repo.or.cz-lilypond.git
> 	lilypond_1_0-repo.or.cz-lilypond.git
> 	lilypond_1_2-repo.or.cz-lilypond.git
> 	lilypond_1_4-repo.or.cz-lilypond.git
> 	lilypond_1_6-repo.or.cz-lilypond.git
> 	lilypond_1_8-repo.or.cz-lilypond.git
> 	lilypond_2_0-repo.or.cz-lilypond.git
> 	lilypond_2_2-repo.or.cz-lilypond.git
> 	lilypond_2_3_2b-repo.or.cz-lilypond.git
> 	lilypond_2_3_5b-repo.or.cz-lilypond.git
> 	lilypond_2_4-repo.or.cz-lilypond.git
> 	lilypond_2_6-repo.or.cz-lilypond.git
> 	lilypond_2_8-repo.or.cz-lilypond.git
> 	master-git.sv.gnu.org-lilypond.git
> 	master-hanwen
> 	master-repo.or.cz-lilypond.git
> 	origin-repo.or.cz-lilypond.git
> 	stable
> 	stable-2.10
> 	stable--2.10-git.sv.gnu.org-lilypond.git
> 
>   It would solve lots of problems for me if cloning and fetching would
>   put branches into a subdirectory, ie.
> 
>     git clone git://repo.or.cz/lilypond.git
> 
>   leads to branches
> 
>     repo.or.cz/lilypond_2_8
>     repo.or.cz/lilypond_2_6
>     repo.or.cz/lilypond_2_4
>     repo.or.cz/master
>      (etc..)

That's basically exactly what git clone --use-separate-remote should do.
Now only if it would become the default... :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Thu, 16 Nov 2006 16:13:44 -0800, Junio C Hamano wrote:
> >  - clone for getting all branches of a repo, but no command for
> >    updating all branches of a repo.

I want this one as well.

> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?

As long as its consistent with "clone" I'll be happy, (I think as part
of a separate topic we need to fix the mappings in clone, see
--use-separate-remotes as default and related).

The current case is really annoying where I have to throw use clone
into a new repository just to get everything, rather than just being
able to fetch everything into the repository I already have.

-Carl

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

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Thu, 16 Nov 2006 16:13:44 -0800, Junio C Hamano wrote:
> This one I can understand, but how would you propose to "update
> all branches", in other words what's your design for mapping
> remote branch names to local branch namespaces?

What I want here is a command "git update" that fetches and
fast-forwards the all branches which are designated as "tracking" a
branch in some known remote repository. And git-clone would setup all
branches appropriately so that they would be updated by git-update.

Additionally, it would be nice if git-update would also create new
tracking branches for all remotes repositories that had been
designated as being tracked, (and git-clone would do this as well).

There should also be a mechanism to easily create new tracking support
for specific branches or all branches of a repository, (could be "git
fetch URL branch" or "git fetch --all URL", for example).

With this kind of setup, I would use "git update" regularly, and only
ever merge locally. And by definition merging with any local tracking
branch would have just as much information available as "pull URL
branch" so the message would be the same.

I've been using git for 10-11 months, so I think I understand the
models fairly well, and I'd be really happy with a setup like that. I
also have talked with a fair number of (non-git-using) users who think
git is confusing, but I think would find the above scenario just fine.

In this scenario, git pull would still work just fine, but it would
also be much easy to teach a workflow that didn't use pull at all, so
if there's any git-pull confusion that's an actual problem, it could
be avoided.

Junio, what do you think of a setup something like that? I really
don't want to create a command other than "git" to implement it.

-Carl

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

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Fri, 17 Nov 2006, Han-Wen Nienhuys wrote:
> 
> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.

Well, a lot of the assymmetries aren't actually gratuitous at all.

>  - clone but not a put-clone,

As mentioned, in order to "put-clone", you generally have to "create" 
first, so the "put-clone" really makes no sense.

The _true_ reverse is really your

 - "git init-db" on both sides

 - "git pull" (your workflow ;) on receiving

 - "git push" on sending.

The fact that we can do "git clone" on the _receiving_ side is an 
assymmetry, but it's not gratutous: when receiving we don't need any extra 
permissions or setup to create a new archive. In contrast, when sending, 
you do have to have that "get permission to create new archive" phase.

>  - pull = merge + fetch, but no command for merge + throw

Again, this is not gratuitous, and the reason is very similar: when you 
pull, you're pulling into something that _you_ control and _you_ have 
access to, namely your working directory. In order to merge you have to 
have the ability to fix up conflicts (whether automatically or manually), 
and this is something that you _fundamentally_ can only do when you own 
the repo space.

Again, when you do "push", the reason you can't merge is not a "gratuitous 
assymmetry", but a _fundamental_ assymmetry: by definition, you're pushing 
to a _remote_ thing, and as such you can't merge, because you can't fix up 
any merge problems.

See?

In many ways, if you want _symmetry_, you need to make sure that the 
_cases_ are symmetrical. If you have ssh shell access, you can often do 
that, and the "reverse" of a "git pull" is actually just another "git 
pull" from the other side:

	ssh other-side "cd repo ; git pull back"

Now they really _are_ symmetrical: "git pull" is really in many ways ITS 
OWN reverse operation. 

But "push" and "pull" _fundamentally_ aren't symmetric operations, and you 
simply cannot possibly make them symmetric. Any system that tries would be 
absolutely horrible to use, exactly because it would be either:

 - making local/remote operations totally equivalent

   This sounds like a "good" thing, but from a real user perspective it's 
   actually horribly horribly bad. Knowing the difference between local 
   and remote is what allows a lot of performance optimizations, and a lot 
   of security. Your local repo is _yours_, and nobody can take that away 
   from you, and that's a really fundamental reason for why the symmetry 
   cannot exist, and why local/remote operations MUST NOT be something 
   that you can mix without thinking about them,

 - limit local operations in a way to make them effectively unusable and 
   unscriptable.

   You'd basically have to do everything even _locally_ through some 
   server interface, and you'd not be allowed to ever touch your local 
   checked-out repository directly. Again: local repositories really _are_ 
   special, because you can touch the checked out copy. If you try to 
   suppress that, you're screwed.

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.  

As in sending? Sure there is: use "git push --all". It will push out every 
branch (and tag) you have. Add "--force" if you want to make sure that it 
also pushed out branches even if the result isn't a strict superset (of 
course, the receiving end may actually end up refusing to take it, there's 
a option for the receiver to say "I will refuse any update that isn't a 
strict superset of what I had").

If you mean as in "receiving new branches", then yeah, you do have to 
script it, with some fairly trivial "git ls-remote" to make sure you get 
the new remotes.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Linus Torvalds escreveu:
> The fact that we can do "git clone" on the _receiving_ side is an 
> assymmetry, but it's not gratutous: when receiving we don't need any extra 
> permissions or setup to create a new archive. In contrast, when sending, 
> you do have to have that "get permission to create new archive" phase.
> 
>>  - pull = merge + fetch, but no command for merge + throw
> 
> Again, this is not gratuitous, and the reason is very similar: when you 
> pull, you're pulling into something that _you_ control and _you_ have 

>But "push" and "pull" _fundamentally_ aren't symmetric operations, and you 
>simply cannot possibly make them symmetric. 

Point taken;  thank you. 

In that case, we're full circle with the command naming issues. Push
and pull are fundamentally asymmetric operations, but then a
consistent UI would dictate that they wouldn't be named symmetrically,
as they are now.


-- 

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

I think there's a fundamental assumption built into the design of git
that most programmers accustomed to a corporate environment don't
understand.  Namely, that each programmer owns his or her entire
"repository", and can do whatever he or she darn well pleases with it
at any time.  Go ahead and create hundreds of transient branches as
part of a scripted "merge complexity metric" calculation.  Try three
different refactoring strategies on different branches, abandon two of
them, and prune them months later.  And generally use the power of the
SCM to juggle a lot of things at once, because there's no sysadmin
gatekeeper stopping you, and the thing is designed and coded scalably
so it doesn't grind to a halt as soon as everyone has dozens of
private branches.

Even if you do find a way to push git in a direction that it doesn't
scale, it's no one's problem but your own -- people who pull from you
are pulling the _content_ on the branches they care about, not the
structure of your repository.

On 11/16/06, Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:
> I agree that discussions on naming may cloud the issue, but "learning
> the workflow" implies that people should adapt to the limitations of
> their tools.  That's only a viable stance when the tools are finished
> and completely perfect.
>
> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.

One person's gratuitous asymmetry is another's minimalism.  (If the
symmetric thing doesn't make any sense or can't be implemented
scalably, leave it out.)  It is more important that git continue to
work than that it appear symmetric without reference to its function.

>  - clone but not a put-clone,

What possible use would that be?  git is not rsync.

>  - pull = merge + fetch, but no command for merge + throw

pull = fetch + merge.  It is (almost?) always followed by a judgment
call based on the merge results.  merge + throw doesn't make any sense
in terms of the job at hand, which is facilitating human judgments
about whether to accept someone else's work into one's working tree.

>  - clone for getting all branches of a repo, but no command for
>    updating all branches of a repo.

clone is shorthand for the steps involved in setting up a new
repository with content similar to an existing one.  There isn't any
merge involved, and no scope for human judgment, so it's simplest to
clone the whole state of the remote repository (including tags and
branches) and let the user blow away any branches he doesn't need.
But once the clone is done, all of those branches are _truly_ _local_
-- they don't retain any reference to the remote branches, and you can
commit to all of them.  The only entry placed in .git/remotes is the
"origin" of the new clone, which is the "master" of the remote
repository.  That's for the user's convenience, and is about the only
thing in the new clone that _isn't_ a copy of something in the remote
tree.

So the "update all" process wouldn't look anything like a clone, it
would be a fetch and replay of each remote branch onto the
corresponding local branch.  You and Carl seem to want "git clone" not
only to copy the heads of the remote branches but to populate
.git/remotes with trackers for all of those branches, and then to
start each "git update" by polling all of the remote repositories to
see if branches have been created or deleted, then pull every branch
in sight.  What do you do when "upstream" creates a branch with the
same name as a local branch you have created?  How do you deal with
branch points that don't exist in your repository because you touched
one of the "tracker" branches between pulls?

In short, if you want a local, read-only tracker for a whole remote
repository instead of a branch that's actually published to you (and
maintained accordingly), you might consider s/git/rsync/.

Cheers,

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Michael K. Edwards <medwards.linux@gmail.com> wrote
>   The only entry placed in .git/remotes is the
> "origin" of the new clone, which is the "master" of the remote
> repository.  That's for the user's convenience, and is about the only
> thing in the new clone that _isn't_ a copy of something in the remote
> tree.

Actually, this "origin" entry does contain "Pull:" lines for all of
the branches that were cloned, so that "git pull" fetches and merges
updates to all of these branches.  (If upstream is in the habit of
reverting things, you may need "git pull -f"; I just did that on the
git repo to handle a failure to fast-forward on the "pu" branch.)

Presumably "git branch -D" should inspect everything under
.git/remotes to see whether one or more Pull: lines need to be deleted
along with the branch.  Currently, it looks like "remotes" entries are
created only by "git clone" or by hand.  Junio, are there any plans to
manage the contents of "remotes" through the tool instead of by hand?

Cheers,

Re: Cleaning up git user-interface warts

[Junio C Hamano]

"Michael K. Edwards" <medwards.linux@gmail.com> writes:

> Presumably "git branch -D" should inspect everything under
> .git/remotes to see whether one or more Pull: lines need to be
> deleted along with the branch.

I am not sure what you mean.  .git/remotes files do not describe
any relationship between local branches (and that is where one
of the problem raised in recent thread -- pull does not notice
on which branch you are on and change its behaviour depending on
it), so I do not think there is anything gained for "git branch
-D" by going through them.

> Currently, it looks like "remotes" entries are
> created only by "git clone" or by hand.  Junio, are there any plans to
> manage the contents of "remotes" through the tool instead of by hand?

I muttered something in a near-by thread

	Message-ID: <7vr6w78b4x.fsf@assigned-by-dhcp.cox.net>

I am reasonably sure a separate tool (what I tentatively called
"maint-remote" in the message) is necessary, because, while it
would be relatively easy to make "git fetch" and friends to add
new mappings in the default way under a new option, people with
different workflows would want differnt "default mappings", and
adding new mappings for _all_ remote branches is useful only for
people who work in one particular way (namely, the CVS-style
"the central distribution point is where everybody meet" model).

The tool, under "interactive" mode, would probably take one
parameter, the short name of a remote ($name), and would give
you a form to update its URL:, shows ls-remote output against
that repository and would let you:

 - update the URL: which would probably cause the ls-remote to
   be re-run;

 - remove existing mappings;

 - add mappings for a remote branch for which you do not have a
   corresponding tracking branch, with a straightforward default
   mapping:

   	refs/heads/$branch:refs/remotes/$name/$branch

But I haven't thought things through yet.

Re: Cleaning up git user-interface warts

[Michael K. Edwards]

On 11/16/06, Junio C Hamano <junkio@cox.net> wrote:
> "Michael K. Edwards" <medwards.linux@gmail.com> writes:
>
> > Presumably "git branch -D" should inspect everything under
> > .git/remotes to see whether one or more Pull: lines need to be
> > deleted along with the branch.
>
> I am not sure what you mean.  .git/remotes files do not describe
> any relationship between local branches (and that is where one
> of the problem raised in recent thread -- pull does not notice
> on which branch you are on and change its behaviour depending on
> it), so I do not think there is anything gained for "git branch
> -D" by going through them.

.git/remotes/foo does contain Pull: lines which indicate the local
branch onto which to _fetch_ remote changes.  It's the subsequent
_merge_ that doesn't notice which branch you have checked out.

Cheers,

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Michael K. Edwards wrote:

> Currently, it looks like "remotes" entries are
> created only by "git clone" or by hand.  Junio, are there any plans to
> manage the contents of "remotes" through the tool instead of by hand?

Don't forget quite new work with managing remotes (and per-branch
configuration) in the config instead of separate remotes/ (or even older
branches/) file
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Horst H. von Brand]

Han-Wen Nienhuys <hanwen@xs4all.nl> wrote:

[...]

> Until that time, it would be good goal to remove all idiosyncrasies,
> all gratuitious asymetries and needless limitations in the commands of
> git, eg.
> 
>  - clone but not a put-clone,

Lost me there.

>  - pull = merge + fetch, but no command for merge + throw

throw + merge (at the remote end, that is)?
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 07:03:18PM CET, Linus Torvalds wrote:
> If you think "pull" is confusing, I can guarantee you that _changing_ the 
> name is a hell of a lot more confusing. In fact, I think a lot of the 
> confusion comes from cogito, not from git - the fact that cogito used 
> different names and different syntax was a mistake, I think.

  I would agree that having "pull" mean something different in Cogito
than in Git was a bad idea (explanation: historically, for some period
of time Cogito had cg-pull which meant the same as cg-fetch or hg pull;
later it got renamed to cg-fetch). But I'm also happy that Cogito just
does not use the "pull" expression at all currently: "updating" seems to
be a clear and unloaded enough concept for new people. Pull is really
_very_ confusing, with it meaning something different (but not different
enough) in _all_ other systems but BK (which is basically irrelevant
nowadays).

  That said, I agree with your argument that changing it in Git now
might just result in more confusion. I'm just trying to explain Cogito's
choice here, and I believe it does no good nor harm to Core Git if it
just uses different name for the concept and avoids the original name at
all (except explaining in the docs that updating in Cogito is what
pulling is in Git).

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
> You have to admit both pull and fetch have been contaminated
> with loaded meanings from different backgrounds. I was talking
> about killing the source of confusion in the longer term by
> removing fetch/pull/push, so we are still on the same page.

How was/is fetch contaminated?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Petr Baudis wrote:

> On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
> > You have to admit both pull and fetch have been contaminated
> > with loaded meanings from different backgrounds. I was talking
> > about killing the source of confusion in the longer term by
> > removing fetch/pull/push, so we are still on the same page.
> 
> How was/is fetch contaminated?

I think "fetch" is sane.  Its only problem is a missing symetrical 
counterpart verb, like "get" and "put".

Re: Cleaning up git user-interface warts

[Linus Torvalds]

On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> 
> I think "fetch" is sane.  Its only problem is a missing symetrical 
> counterpart verb, like "get" and "put".

If you're a dog owner, the obvious counterpart for "fetch" is "throw" ;)

I think "get" and "put" would be bad, just because of confusion with 
"sccs get" (ie it has that "get this file" connotations).

Maybe "fetch" and "push" aren't totally diametrically opposite, but 
really, I don't think they are that hard to understand either. We do have 
the BK legacy of "pull" implying a merge, and that's fairly fundamental. 

It's also true that in a lot of usage schenarios, what people actually 
_use_ is "pull" and "push", and no, they aren't mirror images (since push 
will _not_ do the merge), but at the same time, from a _usage_ standpoint 
they really _are_ each others opposites. 

You "pull" to get other peoples data into your branch (and once you've 
internalized local branches and the merge thing, you know what this 
means), and you "push" to push your changes out. It really _is_ the usage 
schenario, and using "opposite" words really _does_ make sense.

It's true that _technically_ "fetch" is the opposite of "push", but at the 
same time, that really is about technology, not about usage models. You 
normally wouldn't do a "git fetch + git push" pair. You _can_ do so, but 
it's not the natural way to work - unless you're just doing a mirror 
service.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Linus Torvalds wrote:

> 
> 
> On Wed, 15 Nov 2006, Nicolas Pitre wrote:
> > 
> > I think "fetch" is sane.  Its only problem is a missing symetrical 
> > counterpart verb, like "get" and "put".
> 
> If you're a dog owner, the obvious counterpart for "fetch" is "throw" ;)

Yeah.  You could always throw a branch to your dog.

Or maybe we should introduce the concept of "bones" to GIT in place of 
branches?  ;-)

> I think "get" and "put" would be bad, just because of confusion with 
> "sccs get" (ie it has that "get this file" connotations).

Has SCCS really had a similar level of influence than BK or CVS in that 
matter?

> Maybe "fetch" and "push" aren't totally diametrically opposite, but 
> really, I don't think they are that hard to understand either. We do have 
> the BK legacy of "pull" implying a merge, and that's fairly fundamental. 
> 
> It's also true that in a lot of usage schenarios, what people actually 
> _use_ is "pull" and "push", and no, they aren't mirror images (since push 
> will _not_ do the merge), but at the same time, from a _usage_ standpoint 
> they really _are_ each others opposites. 

The problem is the "usage standpoint" distinction that has to be made.  
Exactly because in GIT it is a bit distorted from what most people 
expect from other standpoints.

> You "pull" to get other peoples data into your branch (and once you've 
> internalized local branches and the merge thing, you know what this 
> means), and you "push" to push your changes out. It really _is_ the usage 
> schenario, and using "opposite" words really _does_ make sense.

But that's exactly why newbies have problems.  Instead of simply 
understanding the bare operation (fetch data in a branch _then_ merge 
it) they sort of need to abstract the concept of branch away because a 
"pull" does it all automagically.  Which is fine as long as you're 
willing to ignore branch concepts altogether.  But once branches are 
back in the picture for more involved operations then the "pull" word 
simply feels odd.  Even more so with the local merge syntax.

When I say to someone "just merge branch weezee with your current 
branch" the most intuitive command would be:

	git merge weezee

But because "pull" mixes two concepts together this makes the thing more 
esoteric.  Unless, of course, you get used to the mental model you 
outlined above, but IMHO simply needing a mental model to explain the 
tool is a sign that something is mapped wrong.

Re: Cleaning up git user-interface warts

[Anand Kumria]

On Wed, 15 Nov 2006 15:26:44 -0500, Nicolas Pitre wrote:

> On Wed, 15 Nov 2006, Petr Baudis wrote:
> 
>> On Wed, Nov 15, 2006 at 03:10:16AM CET, Junio C Hamano wrote:
>> > You have to admit both pull and fetch have been contaminated
>> > with loaded meanings from different backgrounds. I was talking
>> > about killing the source of confusion in the longer term by
>> > removing fetch/pull/push, so we are still on the same page.
>> 
>> How was/is fetch contaminated?
> 
> I think "fetch" is sane.  Its only problem is a missing symetrical 
> counterpart verb, like "get" and "put".

"throw" ?

But I think "I'll just 'throw' this set of patches at you" is a lot
harshers sounding than "I'll just 'push' this set of patches at you".

Anand

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Tue, 14 Nov 2006 15:52:47 -0500 (EST), Nicolas Pitre wrote:
>> Even if I have a clear preference for GIT's _technology_, I still think
>> that the HG user interface is more convivial.  I even been thinking
>> about writing something like an hg-like frontend to GIT from time to
>> time just so that GIT could then be better compared to (and actually
>> just used like) HG.
>
> I've actually been tempted to do the same myself. I really think that
> the technology is a more important criterion than the UI so the
> imagined hg-on-git interface would be an attempt to get people to look
> past the interface differences and look at the technology when
> deciding.
>...
>> I still think that the GIT user interface sucks in many ways.  The
>...

I've actually been tempted to do that too, and my earlier "if I
were to redo git from scratch" message was the beginning of it
to summarize my preference about some of the issues raised in
this thread.

Commenting on the messages in this thread:

 - "resolve / resolved" are both confusing, when you are talking
   about "mark-resolved" operation.

 - "pull/push/fetch" have undesired confusion depending on where
   people learned the term.  I'd perhaps vote for replacing
   fetch with download and push with upload.

 - I think it would be sensible to make remote tracking branches
   less visible.  For example:

	git diff origin

   where origin is the shorthand for your upstream (e.g. you
   have .git/remotes/origin that records the URL and the branch
   you are tracking) should be easier to understand than

   	git diff remotes/origin/HEAD

   The latter is an implementation detail.  I could imagine we
   might even want to allow

	git diff origin#next

   to name the branch of the remote repository.  The notion of
   "where the tips of remote repository's branches are" is
   probably be updated by "git download" (in other words, the
   above "git diff" does not automatically initiate network
   transfer).

 - "git merge" to merge another branch into the current would
   make sense.  "git pull . remotes/origin/next" is showing too
   much implementation detail.  It should just be:

	git merge origin#next

And I agree with Pasky that fixing UI is hard unless you are
willing to get rid of historical warts.  Syntax of the command
line arguments the current set of Porcelain-ish takes are
sometimes just horrible.  It may not be a bad idea to start
building the fixed UI from scratch, using different prefix than
"git" (say "gu" that stands for "git UI" or "gh" that stands for
"git for humans").

Of course, it could even be "cg" ;-).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

>  - I think it would be sensible to make remote tracking branches
>    less visible.  For example:
>...
>  - "git merge" to merge another branch into the current would
>    make sense.  "git pull . remotes/origin/next" is showing too
>    much implementation detail.  It should just be:
>
> 	git merge origin#next

This and other examples in "making remote tracking branches less
visible" are hard to read because I used the word "origin" in
two different sense.  So here is a needed clarification.

If you have remotes/upstream that says:

	URL: git://git.xz/repo.git
        Pull: refs/heads/master:remotes/origin/master
        Pull: refs/heads/next:remotes/origin/next

Then, currently the users need to say:

	git diff remotes/origin/master
        git merge remotes/origin/next

By "making tracking branches less visible", what I mean is to
let the users say this instead:

	git diff upstream
        git merge upstream#next

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Junio C Hamano <junkio@cox.net> writes:
> 
> >  - I think it would be sensible to make remote tracking branches
> >    less visible.  For example:
> >...
> >  - "git merge" to merge another branch into the current would
> >    make sense.  "git pull . remotes/origin/next" is showing too
> >    much implementation detail.  It should just be:
> >
> > 	git merge origin#next
> 
> This and other examples in "making remote tracking branches less
> visible" are hard to read because I used the word "origin" in
> two different sense.  So here is a needed clarification.
> 
> If you have remotes/upstream that says:
> 
> 	URL: git://git.xz/repo.git
>         Pull: refs/heads/master:remotes/origin/master
>         Pull: refs/heads/next:remotes/origin/next
> 
> Then, currently the users need to say:
> 
> 	git diff remotes/origin/master
>         git merge remotes/origin/next
> 
> By "making tracking branches less visible", what I mean is to
> let the users say this instead:
> 
> 	git diff upstream
>         git merge upstream#next

What is the point of hiding tracking branches?  Why just not making them 
easier to use instead?  There are currently so many ways to specify 
remote branches that even I get confused.

OK..... let's pretend this is my follow-up to your "If I were redoing 
git from scratch" query.  Actually I would not redo it from scratch 
since the vast majority of it is rather sane already.  But here's some 
changes that I would do:

1) make "git init" an alias for "git init-db".

What's the point of "-db"?  Sure we're initializing the GIT database.  
But who cares?  The user doesn't care if GIT uses a "database" or 
whatever.  And according to some people's definition of a "database" it 
could be argued that GIT doesn't use a database at all in the purist 
sense of it. What the user wants is to get started and "init" (without 
the "-db" is so much more to the point. Doesn't matter if incidentally 
it happens to be the same keyword HG uses for the same operation because 
we are not afflicted by the NIH disease, right? And it has 3 chars less 
to type which is for sure a premium improvement to the very first GIT 
user experience!

2) "pull" and "push" should be symmetrical operations

They are symmetrical in the dictionary and in people's mind.  OK but what 
if I merge content from another _local_ branch into the current one?  
Isn't that kind of a pull as well?  Answer: NO IT IS NOT!  Reason: 
because we already have "merge" for that very operation for damn sake!  
And because "merging" isn't a synonym for "pulling" at all, we cannot 
pretend it should sort of become more true if taken the other way 
around.

Actually, if we _merge_ stuff together, we certainly have to /pull/ some 
of it, meaning that "merge" might imply a "pull", even in real life 
situations outside of the GIT context (think merging Vodka and Kahlua in 
a glass where you might have to pull the Vodka bottle out of the freezer 
before you can merge it). And thankfully we got it right with git-merge 
which can take either a branch or an URL as argument which in the later 
case will perform a pull implicitly (OK currently a fetch but you know 
what I mean).

But trying to put in people's head that "pulling" implies a "merge"?  No 
that doesn't work really well.  OK if you pull too hard on the Vodka 
bottle that might imply a merge at some point but it would certainly be 
accidental.  And it is not without coincidence that some people had 
accidental GIT merges by using git-pull.

Conclusion:  git-pull must not perform any merge.  It is the symmetrical 
operation of a push meaning that it pulls content from a remote branch 
and does no more.  People understands that pretty well, .  This makes 
git-fetch redundant (or an alias to git-pull) in that case, and again we 
don't mind it becoming similar to in HG because we admit HG was right 
about it.

3) remote branch handling should become more straight forward.

OK! Now that we've solved the pull issue and that everybody agrees with 
me (how can't you all agree with me anyway) let's have a look at remote 
branches.  It should be simple:

a)	git-pull git://repo.com/time_machine.git

This pulls every branches from the time_machine.git repository and 
create identically named branches locally, except for the remote 
master becoming origin locally.  All those branches are marked read-only 
(i.e. cannot commit to them) and _each_ of those branches get an URL 
associated to them somehow (the association is an implementation 
detail).

If then you do:

b)	git-pull origin

Then it will pull the git://repo.com/time_machine.git:master branch into 
the local "origin" branch.  IOW, local tracking branches becomes 
synonyms for their remote URLs after they've been pulled once.  If the 
remote branch "next" became a local "next" with the first pull (because 
it didn't specify any branch meaning that they were all pulled), doing 
a:

c)	git-pull next

would actually be the same as:

d)	git-pull git://repo.com/time_machine.git:next

Now to have different remote and local names for those tracking 
branches:

e)	git-pull git://repo.com/time_machine.git:master upstream

would be a variation where a remote branch gets a different local name. 
This pulls the remote master branch but calls it "upstream" locally.  
If that "upstream" branch does exist locally already then fail with 
appropriate error message, unless the local branch happens to have the 
same URL attribute already.  You then have two local branches tracking 
the same remote branch which is weird but still fine if someone wants
to have different views (today's pull and yesterday's pull).  This is 
not necessarily something to encourage but only a fallout of the branch 
semantic.  And again a simple:

f)	git-pull upstream

would update the "upstream" branch from the remote master branch.

I think the concept of "branch group" should be preserved too.  So if 
you create a group called "warp", then add "origin", "next", and 
"upstream" to it, then:

g)	git-pull warp

would pull all the included branches.  One way to create a branch group 
with the initial pull is not to specify the remote branch but only the 
repository URL, like:

h)	git-pull git://repo.com/time_machine.git warp

Because no specific branch in the remote repository was specified just 
like in (a) then all branches are pulled, but because a local name was 
provided then this becomes a branch group.

Branch groups could be used to extend the branch namespace as well to 
avoid clashes with different remote repositories.  In this case the 
branch groups could be a way to arrange branches in a hierarchy so 
"warp" refer to all branches included in the warp group while 
"warp/upstream" refer to only one branch. In this case "upstream" and 
"warp/upstream" would be the same branch if "upstream" was effectively 
added to the "warp" group, but it doesn't need to be so.  And branches 
in a group don't have to come from the same remote repository either 
since the source of each branch (the URL) is a per branch attribute.

To make it "easy" on the user, I think that any branch (or tag) down the 
hierarchy should be used without the "path" leading to it if there is no 
conflict.  We already do that with heads and tags, So if for example the 
"warp" group contained a branch named "lightspeed" but no such branch 
(or tag) existed anywhere else then it could be referenced with simply 
"lightspeed" or "warp/lightspeed".

Then you don't need any strange scheme for diff and merge.  Just using 
"git-diff upstream" or "git-merge origin next" suffice.  Oh and I don't 
think it would be a good idea to have a completely separate namespace 
for local vs remote aka tracking branches.  Maybe in .git/refs/ they 
should be separate to distinguish which ones are read-only remote 
tracking ones and which ones are local, but that must not be forced on 
the UI.

Thinking about it some more, maybe (a) should create a default branch 
group if the remote repository has more than one branches, say "origin".  
This way, git-pull without any argument would be the same as 
"git-pull origin" by default.  If "origin" is a single branch then 
(git-pull" would pull only one branch, but if "origin" is a branch group 
then all included branches would be pulled.

This becomes formalized as:

	git_pull [<URL>] [<local_name>]

If <URL> includes a branch name then <local_name> is a single branch 
name.  If <URL> doesn't include any branch name then <local_name> 
becomes a local branch group name containing all branches in the remote 
repository. If <URL> is specified but not <local_name> then <local_name> 
is set to "origin" by default, unless it already exists in which case it 
is an error and the pull fails.  If <URL> is not specified then the URL 
attribute to the specified branch(es) is used.  If nothing is specified 
then "origin" is used for <local_name> by default and URL attribute of 
the origin branch or the origin branch group is/are used.

*****

OK I think this is enough for now. I know that parts of what I've said 
can already be found in GIT, but I wanted the explanation to be 
complete and therefore tentatively coherent.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> What is the point of hiding tracking branches?  Why just not making them 
> easier to use instead?  There are currently so many ways to specify 
> remote branches that even I get confused.

Ok, I think in essence we are saying the same thing except I
went overboard by suggsting to extend sha1_name to also look at
.git/remotes/$name which is not necessary, because we already
have the .git/refs/remotes/%s/HEAD magic there.  Consider the
suggestion of "upstream#next" syntax retracted, please.

> 1) make "git init" an alias for "git init-db".

Or even better, have "gh init".

> 2) "pull" and "push" should be symmetrical operations

I think that makes a lot of sense to have "gh pull" and "gh
push" as symmetric operations, and make "gh merge" do the
fast-forward and 3-way merge magic done in the current "git
pull".  These three words would have a lot saner meaning.

> 3) remote branch handling should become more straight forward.
>
> OK! Now that we've solved the pull issue and that everybody agrees with 
> me (how can't you all agree with me anyway) let's have a look at remote 
> branches.

I would probably prefer making the default namespace under
.git/refs/remotes/remote-name for the tracking branches this
proposal creates, but other than that I agree with the general
direction this proposal is taking us, including branch groups.
We have .git/refs/remotes/%s/HEAD magic so I do not think we
even need to treat one branch repository any specially as you
suggsted.

The reason I am suggsting "gh" instead of "git" is primarily to
deal with stale documentation people would find googling.  I can
easily see people get confused by reading "pull = fetch + merge"
from either mailing list archive or Git cheat sheet various
projects seem to have developed.

It does not mean we need to redo _all_ UI.  I think most of the
archaeology commands have sane UI so during the transition
period (git 1.99) we can have "git log" and "gh log" which are
one and the same program, and perhaps git 2.0 can be shipped
with clear distinction between plumbing (i.e. git-update-index
and friends) and porcelain (e.g. "gh pull" that only fetches but
with the user friendliness you outlined here), with backward
compatibility wart to help old timers (e.g. "git pull" that
still does "git fetch" followed by "git merge").

Re: Cleaning up git user-interface warts

[Shawn Pearce]

Junio C Hamano <junkio@cox.net> wrote:
> Or even better, have "gh init".

Why gh?  Is Git just Mercurial backwards?  :)

I'm all in favor of this discussion, and in particular of just
breaking the entire UI in 2.0 by using a new frontend command.
I'm just not sure that "Mercurial backwards" describes Git well.

-- 

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Shawn Pearce <spearce@spearce.org> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> Or even better, have "gh init".
>
> Why gh?  Is Git just Mercurial backwards?  :)
>
> I'm all in favor of this discussion, and in particular of just
> breaking the entire UI in 2.0 by using a new frontend command.
> I'm just not sure that "Mercurial backwards" describes Git well.

I do not have any obsession to any name as long as it is
different from "git" to avoid confusion coming from older
documents that would be found by googling.  gh was just
shorthand for "git for humans" (and easy to type with index
fingers).  I think I listed a few other possibilities in my
previous message.

Re: Cleaning up git user-interface warts

[Johannes Schindelin]

Hi,

On Tue, 14 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > 1) make "git init" an alias for "git init-db".
> 
> Or even better, have "gh init".

Please no. It only makes things even more confusing. "git init" is perfect 
as it is. We can always have internal aliases from "init-db" to "init" to 
account for older usages.

> > 2) "pull" and "push" should be symmetrical operations
> 
> I think that makes a lot of sense to have "gh pull" and "gh
> push" as symmetric operations, and make "gh merge" do the
> fast-forward and 3-way merge magic done in the current "git
> pull".  These three words would have a lot saner meaning.

I am really opposed to do "gh pull". Not only because of "gh" being 
completely confusing (we already _have_ "git", and for porcelains 
different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
did not help one wit by insisting on their own interpretation.

Why not do something like "get/put" instead? It is

- easier to remember
- not bogus (AFAICT the meaning is not used in diametrical senses)
- shorter to type than download/upload

As for "git merge": Just by the number of arguments you can discern 
between the original usage and the new usage, so I am all in favour of 
replacing "git pull <blabla>" by "git merge <blabla>". Where "<blabla>" 
can be a branch or a remote or a URL (with cogito style #branchname).

Ciao,
Dscho

Re: Cleaning up git user-interface warts

[Sean]

On Wed, 15 Nov 2006 15:01:47 +0100 (CET)
Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> I am really opposed to do "gh pull". Not only because of "gh" being 
> completely confusing (we already _have_ "git", and for porcelains 
> different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
> did not help one wit by insisting on their own interpretation.

This makes a lot of sense.  The "git" command isn't damaged so bad
that it can't be saved in a backward compatible way, at least for
a transition period.  Adding a new command name seems like a step
backward.
 
> Why not do something like "get/put" instead? It is
> 
> - easier to remember
> - not bogus (AFAICT the meaning is not used in diametrical senses)
> - shorter to type than download/upload
> 
> As for "git merge": Just by the number of arguments you can discern 
> between the original usage and the new usage, so I am all in favour of 
> replacing "git pull <blabla>" by "git merge <blabla>". Where "<blabla>" 
> can be a branch or a remote or a URL (with cogito style #branchname).

Both these ideas sound like a step in the right direction too.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Johannes Schindelin wrote:

> On Tue, 14 Nov 2006, Junio C Hamano wrote:
> 
> > Nicolas Pitre <nico@cam.org> writes:
> > 
> > > 2) "pull" and "push" should be symmetrical operations
> > 
> > I think that makes a lot of sense to have "gh pull" and "gh
> > push" as symmetric operations, and make "gh merge" do the
> > fast-forward and 3-way merge magic done in the current "git
> > pull".  These three words would have a lot saner meaning.
> 
> I am really opposed to do "gh pull". Not only because of "gh" being 
> completely confusing (we already _have_ "git", and for porcelains 
> different TLAs), but "pull" _really_ is confusing by now. And Mercurial 
> did not help one wit by insisting on their own interpretation.

I completely agree that creating yet another command prefix for 
basically the same tools would be a disaster.  We have "git" already so 
let's stick to it and make its usage just more sane.

> Why not do something like "get/put" instead? It is
> 
> - easier to remember
> - not bogus (AFAICT the meaning is not used in diametrical senses)
> - shorter to type than download/upload

Well, of all compromizes this is probably the best one so far.  I would 
have prefered to bite the bullet and fix "pull" instead of adding yet 
more commands.  But if the consensus is that there is no way on earth 
that "pull" can be salvaged then get/put is probably more enjoyable than 
download/upload.  This way pull/fetch/push could still be available 
(albeit burried somewhere out of sight).

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> Why not do something like "get/put" instead? It is
>> 
>> - easier to remember
>> - not bogus (AFAICT the meaning is not used in diametrical senses)
>> - shorter to type than download/upload
>
> Well, of all compromizes this is probably the best one so far.  I would 
> have prefered to bite the bullet and fix "pull" instead of adding yet 
> more commands.  But if the consensus is that there is no way on earth 
> that "pull" can be salvaged then get/put is probably more enjoyable than 
> download/upload.  This way pull/fetch/push could still be available 
> (albeit burried somewhere out of sight).

I still think in the long run you would be better off giving
separate names to Porcelains because I am sure you are going to
find the next command to "fix", you cannot suddenly change the
semantics of the command, and you soon run out of alternative
ways to name the action and you in addition have to explain the
differences between fetch and get to new users.  At least, with
"ig pull", you can dismiss all the broken git-x Porcelain-ish by
saying "Oh, git-x user-level commands had inconsistent semantics
and broken UI so do not use them anymore -- they are still there
only to help old timers transition.  The user level commands are
now called ig-x and ig stands for improved git".

But that's a very minor detail and can be fixed when we hit the
wall, so let's wait and see what happens.  Please consider my
gh/gu/cg/whatever dropped.

I think get/put is much better than suddenly changing what pull
means and is shorter to type than x-load; I am Ok with them.
Although I think these words are tainted by SCCS, I do not think
anybody cares.

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:

> I still think in the long run you would be better off giving
> separate names to Porcelains because I am sure you are going to

The problem I think with that is that the line between plumbing and porcelain 
is not clear.  If you have two names then for the ambiguous ones you are just 
making it more confusing because there is yet another variable to try before 
you get the function you want.



Andy

-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

> On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:
>
>> I still think in the long run you would be better off giving
>> separate names to Porcelains because I am sure you are going to
>
> The problem I think with that is that the line between plumbing and porcelain 
> is not clear.

This is moot because we (at least tentatively) agreed not to do
"gh" or "ig" or whatever, but I do not understand why you feel
so.

If we had a separate Porcelain namespace (say "ng" for "new
git") you would know "ng-commit" is not a Plumbing and when you
are writing a Porcelain script you would stay away from using it
in your script.

In the longer term, when the new Porcelain UI Nico and friends
are designing matures, and if it makes everybody (including
existing users who learned git-* Porcelain-ish during 18-months
process) happy, we could gradually deprecate and eventually
remove the git-* Porcelain-ish over time, at that point we would
have a very clear line between plumbing and porcelain.

But that would not be a flag-day change.  During the transition
period you cannot mechanically tell if git-foo is a plumbing or
a porcelain just like you cannot do so now.

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> If we had a separate Porcelain namespace (say "ng" for "new
> git") you would know "ng-commit" is not a Plumbing and when you
> are writing a Porcelain script you would stay away from using it
> in your script.

There is merit in trying to segregate porcelain vs plumbing... at least 
in theory.  In practice though I don't think this is something we should 
absolutely strive for.

Why? Because something is always going to fail the categorization.  
Sure there are commands that are pure plumbing like git-commit-tree, 
etc.  Some are pure porcelain like git-commit or git-log.  Yet we use 
git-log's output for git-shortlog.  Does it mean that git-log is 
plumbing? Also I have a script here that uses git-commit directly 
because it is so much convenient rather than futzing with the really 
bare plumbing.  I don't think git-commit should be prevented from being 
used within another script even if it is classified as porcelain.

So we have that notion of plumbing vs porcelain but in practice there is 
a whole spectrum between those two poles and I think it is a good thing.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 11:41:20 -0800, Junio C Hamano wrote:
> Andy Parkins <andyparkins@gmail.com> writes:
> > On Wednesday 2006, November 15 18:16, Junio C Hamano wrote:
> >
> >> I still think in the long run you would be better off giving
> >> separate names to Porcelains because I am sure you are going to
> >
> > The problem I think with that is that the line between plumbing and porcelain
> > is not clear.
>
> This is moot because we (at least tentatively) agreed not to do
> "gh" or "ig" or whatever, but I do not understand why you feel
> so.

I'm not the original poster, but I feel the same way about the line
being unclear.

Here's a real-world example from last week.

For cairo I wrote a little script that two revspecs, (or one in
which case its first parent is used), and it goes off and checks out
both versions, builds each, runs a performance test on each, and then
generates a report showing the performance impact.

So now I can do things like:

	# What's the performance impact of my latest change:
	cairo-perf-diff HEAD

	# Have my last few changes helped as much as I'd hoped:
	cairo-perf-diff HEAD~3 HEAD

	# How has performance changed since our last stable release:
	cairo-perf-diff 1.2.6 HEAD

Anyway, when I announced this I also mentioned how easily someone
might generate an entire series of reports for a series of
commits. The command I gave as an example is:

	for rev in $(git rev-list 1.2.6..HEAD); do
	    cairo-perf-diff $rev
	done

I think that's a perfectly legitimate one-liner for users to use, and
it really shows off the easy-scriptability of git. But certainly, no
"new porcelain" author is going to consider rev-list to be porcelain
rather than plumbing, right? So as soon as I start teaching people to
do useful stuff like this, they might have to reach down into the
"scary" git interface.

I think we're much better off just having one "git" namespace for the
standard command-line interface, and then making it as easy to use as
possible.

-Carl


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

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> I'm not the original poster, but I feel the same way about the line
> being unclear.
>
> Here's a real-world example from last week.
>...
> Anyway, when I announced this I also mentioned how easily someone
> might generate an entire series of reports for a series of
> commits. The command I gave as an example is:
>
> 	for rev in $(git rev-list 1.2.6..HEAD); do
> 	    cairo-perf-diff $rev
> 	done
>
> I think that's a perfectly legitimate one-liner for users to use, and
> it really shows off the easy-scriptability of git. But certainly, no
> "new porcelain" author is going to consider rev-list to be porcelain
> rather than plumbing, right? So as soon as I start teaching people to
> do useful stuff like this, they might have to reach down into the
> "scary" git interface.

That is a very fine example, but I do not see why it is a
problem.  I do not think the goal of Porcelain is to make it
totally unnecessary for users to know about the plumbing.

The one-liner is essentially a new Porcelain command that is
useful in the cairo developers' workflow, and implementing it
with a plumbing command makes perfect sense.  The whole point of
git plumbing is to be friendly for scripted use.  If the user
who learns that one-liner from you gets curious why and how that
one-liner works, that would be a good gentle introduction to the
plumbing, but otherwise the user is not forced to know about it.

Also I do not see a problem if some plumbing commands happen to
be also useful by themselves ("[alias] less = -p cat-file -p"
comes to mind for example).

Some plumbing commands may be too deep magic and users do not
have to directly deal with them every day.  Some other plumbing
commands are so low-level and needs combination with others to
be any useful, and it is cumbersome to type the combination
every day.  For the latter kind, we have Porcelain commands that
implement the frequently used combination and the end users do
not have to know about them.

So it is true that by having a rich and usable set of Porcelain,
there is less need for the users to know about all the plumbing
details, but I consider that is a happy consequence.  It does
not have to be the goal of having a good Porcelain to hide the
whole plumbing.

Re: Cleaning up git user-interface warts

[Carl Worth]

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

On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:
> That is a very fine example, but I do not see why it is a
> problem.  I do not think the goal of Porcelain is to make it
> totally unnecessary for users to know about the plumbing.

If not, then the promise of the porcelain fails. If cogito offers
"Here are 40 commands so you don't have to learn git's 140" and then
next says "Oh, and you'll still want to learn all those git commands
too", then its existence only makes the "too much stuff to learn"
problem worse, not better.

But I think you agree with me (for now) that fixing the git UI should
not involve creating a new primary command to replace "git".

-Carl

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

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 11:36:21PM CET, Carl Worth wrote:
> On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:
> > That is a very fine example, but I do not see why it is a
> > problem.  I do not think the goal of Porcelain is to make it
> > totally unnecessary for users to know about the plumbing.
> 
> If not, then the promise of the porcelain fails. If cogito offers
> "Here are 40 commands so you don't have to learn git's 140" and then
> next says "Oh, and you'll still want to learn all those git commands
> too", then its existence only makes the "too much stuff to learn"
> problem worse, not better.

I didn't get this argument before either - why do you need to learn "all
those git commands" too? You'll never have to learn "git add" or even
"git commit". If you want to pick specific git commands later (like "git
bisect", which even seeks in a Cogito-compatible way), that's fine, go
ahead! But you by no means have to learn _other_ commands than those you
need. If you want to bisect, you have to learn no other Git commands
than "git bisect".

Another point is, if using _just_ _git_ requires you to learn "all those
git commands too" from git-commit-tree up (yes it does! if you want your
authorship information to be correct), something is wrong.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Robin Rosenberg]

torsdag 16 november 2006 04:21 skrev Petr Baudis:
> Another point is, if using _just_ _git_ requires you to learn "all those
> git commands too" from git-commit-tree up (yes it does! if you want your
> authorship information to be correct), something is wrong.

When/why do I need git-commit-tree? Isn't git-commit enough?

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 11:09:13AM CET, Robin Rosenberg wrote:
> torsdag 16 november 2006 04:21 skrev Petr Baudis:
> > Another point is, if using _just_ _git_ requires you to learn "all those
> > git commands too" from git-commit-tree up (yes it does! if you want your
> > authorship information to be correct), something is wrong.
> 
> When/why do I need git-commit-tree? Isn't git-commit enough?

As I said, when you need to find out how to setup your authorship
information. It's documented as deep as on the git-commit-tree level.
BTW, the documentation is another important part of the
plumbing/porcelain separation, it's not only about the list of commands
but also that porcelain documentation should be reasonably
self-contained and not require users to peek at plumbing docs in order
to find out many stuff. It's also a consideration I take when
maintaining Cogito documentation.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Junio C Hamano escreveu:
> I still think in the long run you would be better off giving
> separate names to Porcelains because I am sure you are going to
> find the next command to "fix", you cannot suddenly change the

 > "ig pull", you can dismiss all the broken git-x Porcelain-ish by
 > saying "Oh, git-x user-level commands had inconsistent semantics
 > and broken UI so do not use them anymore -- they are still there
 > only to help old timers transition.  The user level commands are
 > now called ig-x and ig stands for improved git".


I think it would be good if there were different commands for 
porcelains. Not because fixing the current commands is too much work, 
but rather because it would clarify the structure of git.  GIT is a 
3-layer approach:

  - index+workdir+refs over
  - a DAG of commits over
  - a file based SHA1 database

at first sight it is difficult to tell for each command on which layer 
it operates. It would help understanding GIT a lot if each layer got 
it's own command, eg.

   git - sha1 content db
   gic - sequences of commits
   giu - UI

(Of course, these names are completely silly, but you get the idea)


> I think get/put is much better than suddenly changing what pull
> means and is shorter to type than x-load; I am Ok with them.
> Although I think these words are tainted by SCCS, I do not think
> anybody cares.

they're also tainted  by darcs, but that's a minor problem, I suppose.


-- 

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:

> OK..... let's pretend this is my follow-up to your "If I were redoing

Personally, I agree with almost everything in this email.  Except the 
implementation of point 3.

> 3) remote branch handling should become more straight forward.

I was completely confused by this origin/master/clone stuff when I started 
with git.  In hindsight, now I understand git a bit more, this is what I 
would have liked:

 * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
distributed system there is no such thing as a true origin.

 * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
special because it is the default to push and pull - it's very nice to have a 
default, but it should therefore be /called/ "default".

 * Whatever git-clone calls the remote, it should be matched by a directory 
in .git/refs/remotes.  So .git/remotes/$name contains "Pull"s to get all the 
remote branches to .git/refs/remotes/$name/*.   This implies that 
git /always/ does --use-separate-remote in clone.  If a branch is practically 
read-only it should be technically read-only too.

 * If clone really wants to have a non-read-only master, then that should 
be .git/refs/heads/master and will initialise 
to .git/refs/remotes/$name/master after cloning.  Personally I think this is 
dangerous because it assumes there is a "master" upstream - which git doesn't 
mandate at all.  Maybe it would be better to take the upstream HEAD and 
create a local branch for /that/ branch rather than require that it is 
called "master".

 * Ensuring we have /all/ upstream branches at a later date is hard, and not 
automatic.  Here is the .git/remotes/default file that should be possible:
    URL: git://host/project.git
    Pull: refs/heads/*:refs/remotes/default/*
   Now, every git-pull would check for new upstream branch refs and sync them 
into the local remotes list.  These are read-only so it'd be perfectly safe 
to delete any locally that no longer exist upstream.

 * git-clone should really just be a small wrapper around
    - git-init-db
    - create .git/remotes/default
    - maybe create specific .git/config
    - git-fetch default
   If git-clone does anything that can't be done with settings in the config 
and the remotes/default file then it's wrong.  The reason I say this is that 
as soon as git-clone has special capabilities (like --shared, --local 
and --reference) then you are prevented from doing magic with existing 
repositories.  For example; how do you create a repository that contains 
branches from two other local repositories that have the objects hard linked?

While I'm writing wishes, I'd like to jump on Junio's integration with other 
fetch-backends wish.  I use git-svn, and it would be fantastic if I could 
replace:

git-svn init --id upstream/trunk svn://host/path/trunk
git-svn fetch --id upstream/trunk
git-svn init --id upstream/stable svn://host/path/branches/stable
git-svn fetch --id upstream/stable

With a .git/remotes/svn
 SVN-URL: svn://host/path
 Pull: trunk:refs/remotes/upstream/trunk
 Pull: branches/stable:refs/remotes/upstream/stable
and
 git fetch svn

Obviously, the syntax is just made up; but you get the idea.  Even better, 
would be if it could cope with my "*" syntax suggested above:
 SVN-URL: svn://host/path
 Pull: trunk:refs/remotes/upstream/trunk
 Pull: branches/*:refs/remotes/upstream/*


There have been lots of "wishlist" posts lately; would it be useful if I tried 
to collect all these suggestions from various people into one place to try 
and get a picture of any consensus?



Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Andy Parkins wrote:

>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.

The remote 'origin' is true origin of the repository: it is repository
we cloned this repository from.

I agree that having branch 'origin', at least in most common multi-branch
(multi-head) repository, is just confusing.

>  * Ensuring we have /all/ upstream branches at a later date is hard, and not 
> automatic.  Here is the .git/remotes/default file that should be possible:
>     URL: git://host/project.git
>     Pull: refs/heads/*:refs/remotes/default/*
>    Now, every git-pull would check for new upstream branch refs and sync them 
> into the local remotes list.  These are read-only so it'd be perfectly safe 
> to delete any locally that no longer exist upstream.

Very nice idea.
 
>  * git-clone should really just be a small wrapper around
>     - git-init-db
>     - create .git/remotes/default
>     - maybe create specific .git/config

I'm not sure about "create .git/remotes/default" part. Isn't git moving from
remotes file to having information about remotes (and branches) in config?

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 09:59, Jakub Narebski wrote:

> >  * Don't use the name "origin" twice.  In fact, don't use it at all.  In
> > a distributed system there is no such thing as a true origin.
>
> The remote 'origin' is true origin of the repository: it is repository
> we cloned this repository from.

But that is not necessarily /the/ original, and "origin" is the absolute 
reference in maths.  It doesn't bother me that much I suppose, it's just that 
as far as unambiguous names go, I'm not wild about it - it's got too 
many "central repository" connotations, which is of course anathema to git.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 11:33:55 +0100, Andy Parkins wrote:

> But that is not necessarily /the/ original, and "origin" is the
> absolute reference in maths. It doesn't bother me that much I
> suppose, it's just that as far as unambiguous names go, I'm not wild
> about it - it's got too many "central repository" connotations,
> which is of course anathema to git.

To me, "origin" just means "where <whatever we're talking about>
originated". If you think of it that way, it's perfectly obvious that
each repository can have its own origin.

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006 November 15 10:48, Karl Hasselström wrote:

> To me, "origin" just means "where <whatever we're talking about>
> originated". If you think of it that way, it's perfectly obvious that
> each repository can have its own origin.

Of course.  I wasn't saying that I didn't understand why origin was chosen.  
It's not a completely crazy name - it does have /a/ meaning.  However, it's 
not an unambiguous meaning.  What if the repository I clone was itself a 
clone?  What if the repository it cloned was pulling from three other 
repositories?  What if those three repositories pull/push from/to each other?

  * -- * -- *
   \   |   / \
    \  |  /  /
     \ | /  / 
       *   /
       |  / 
       | /
       * <--- "origin"
       |
       * <--- cloned repository

The name "origin" is too close to having an "ultimate source" feel to it IMO.  
In a distributed system, it's not the right idea to be pushing.  After the 
clone is complete, the "origin" is no more special than any other repository, 
and if you felt like it you could change the URL for "origin" and it would 
make very little difference to you.

In short: I don't think "origin" is wrong, I just think it's not right.


Andy
-- 
Dr Andy Parkins, M Eng (hons), MIEE

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Andy Parkins wrote:

> On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:
> 
> > OK..... let's pretend this is my follow-up to your "If I were redoing
> 
> Personally, I agree with almost everything in this email.  Except the 
> implementation of point 3.
> 
> > 3) remote branch handling should become more straight forward.
> 
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
> 
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.

I agree, sort of.  Not because"origin" is ambigous as a name.  But 
rather because there is a magic translation from "master" to "origin", 
and I think this is wrong to do that.

As mentioned elsewhere (and let's start using "get" instead of "pull" as 
suggested by Johannes), a "get" should probably always create a branch 
group even if it contains only one branch.  This way the remote branch 
called "master" will still be called "master" locally, under the branch 
group used to represent the remote repository.  And if a local name is 
not provided then let's just call it "default".  This way, amongst the 
remote references, there would be a "default/master" that would be used 
when nothing else is provided by the user. So...

	git get repo.com/time_machine.git

would create a local branch named "remotes/default/master" if the remote 
repo has only a master branch.

Then, a simple:

	git merge

could be the same as

	git merge default

which would be equivalent to

	git merge default/master

Afterwards, because the "default" remote already exists, then:

	git get

would be the same as

	git get default

to get changes for all branches in the "default" remote branches, of 
which "master" might be the only one in the simple case.

But again I think it is important that the URL to use must be a per 
branch attribute i.e. attached to "default/master" and not just 
"default".  This way someone could add all branches of interest into the 
"default" group even if they're from different repositories, and a 
simple  get without any argument would get them all.

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> But again I think it is important that the URL to use must be a per 
> branch attribute i.e. attached to "default/master" and not just 
> "default".  This way someone could add all branches of interest into the 
> "default" group even if they're from different repositories, and a 
> simple  get without any argument would get them all.

I think the "one group per one remote repository" model is a lot
easier to explain.  At least when I read your first "branch
group" proposal that was I thought was going on and I found it
quite sensible (and it maps more or less straightforwardly to
the way existing .git/refs/remotes is set up by default).

Re: Cleaning up git user-interface warts

[Nicolas Pitre]

On Wed, 15 Nov 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > But again I think it is important that the URL to use must be a per 
> > branch attribute i.e. attached to "default/master" and not just 
> > "default".  This way someone could add all branches of interest into the 
> > "default" group even if they're from different repositories, and a 
> > simple  get without any argument would get them all.
> 
> I think the "one group per one remote repository" model is a lot
> easier to explain.  At least when I read your first "branch
> group" proposal that was I thought was going on and I found it
> quite sensible (and it maps more or less straightforwardly to
> the way existing .git/refs/remotes is set up by default).

I think one group per remote repo is how things should be by default 
too.  But we should not limit it to that if possible.

Re: Cleaning up git user-interface warts

[Karl Hasselström]

On 2006-11-15 13:11:36 -0500, Nicolas Pitre wrote:

> On Wed, 15 Nov 2006, Junio C Hamano wrote:
>
> > Nicolas Pitre <nico@cam.org> writes:
> >
> > > But again I think it is important that the URL to use must be a
> > > per branch attribute i.e. attached to "default/master" and not
> > > just "default". This way someone could add all branches of
> > > interest into the "default" group even if they're from different
> > > repositories, and a simple get without any argument would get
> > > them all.
> >
> > I think the "one group per one remote repository" model is a lot
> > easier to explain. At least when I read your first "branch group"
> > proposal that was I thought was going on and I found it quite
> > sensible (and it maps more or less straightforwardly to the way
> > existing .git/refs/remotes is set up by default).
>
> I think one group per remote repo is how things should be by default
> too. But we should not limit it to that if possible.

Without the limitation, we risk name collisions when getting all
branches from the remote repository (that is, including any new
branches we previously didn't know about).

-- 
Karl Hasselström, kha@treskal.com

Re: Cleaning up git user-interface warts

[Alan Chandler]

On Wednesday 15 November 2006 15:41, Nicolas Pitre wrote:
> On Wed, 15 Nov 2006, Andy Parkins wrote:
> >  * Don't use the name "origin" twice.  In fact, don't use it at all.  In
> > a distributed system there is no such thing as a true origin.
>
> I agree, sort of.  Not because"origin" is ambigous as a name.  But
> rather because there is a magic translation from "master" to "origin",
> and I think this is wrong to do that.
>
> As mentioned elsewhere (and let's start using "get" instead of "pull" as
> suggested by Johannes), a "get" should probably always create a branch
> group even if it contains only one branch.  This way the remote branch
> called "master" will still be called "master" locally, under the branch
> group used to represent the remote repository.  And if a local name is
> not provided then let's just call it "default".  This way, amongst the
> remote references, there would be a "default/master" that would be used
> when nothing else is provided by the user. So...
>
> 	git get repo.com/time_machine.git
>
> would create a local branch named "remotes/default/master" if the remote
> repo has only a master branch.

Why not call it remotes/repo.com/time_machine.git/master and have a 
DEFAULT_ORIGIN that is a symref to it in the same way as HEAD is a symref to 
a local branch

-- 
Alan Chandler

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Andy Parkins <andyparkins@gmail.com> writes:

>> 3) remote branch handling should become more straight forward.
>
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
>
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.
>
>  * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
> special because it is the default to push and pull - it's very nice to have a 
> default, but it should therefore be /called/ "default".

I think the naming is just a minor detail and can be overridden
with "clone --origin" already.  Renaming it to default is just
like making separate-remote the default to me -- it is fine as
long as it does not break people's expectations.

>  * If clone really wants to have a non-read-only master, then that should 
> be .git/refs/heads/master and will initialise 
> to .git/refs/remotes/$name/master after cloning.  Personally I think this is 
> dangerous because it assumes there is a "master" upstream - which git doesn't 
> mandate at all.  Maybe it would be better to take the upstream HEAD and 
> create a local branch for /that/ branch rather than require that it is 
> called "master".

I think the latter is what clone has done always; take remote's
HEAD and use that to initialize local master (there is no
confusion coming from multiple peer repositories because you
clone from only one place to initialize the repository -- that
one _is_ the origin), and we even keep the HEAD pointing at the
remote's master or whatever it points at at the remote.  Using
"$name" as an object name uses .git/refs/remotes/$name/HEAD.

>  * git-clone should really just be a small wrapper around
>...
> If git-clone does anything that can't be done with settings in the config 
> and the remotes/default file then it's wrong.  The reason I say this is that 
> as soon as git-clone has special capabilities (like --shared, --local 
> and --reference) then you are prevented from doing magic with existing 
> repositories.

That is not entirely true.  clone has convenience because people
asked.  It does not have to mean you are not allowed to give
similar convenience to other commands.  Patches?

> branches from two other local repositories that have the objects hard linked?

fetch by second local repository with git-local-fetch perhaps.

> There have been lots of "wishlist" posts lately; would it be
> useful if I tried to collect all these suggestions from
> various people into one place to try and get a picture of any
> consensus?

A list of common things wished by people certainly is a handy
thing to have.

A consensus would not write code and it generally does not take
technology into account to tell what is realistic and what is
not, so the result needs to be take with a grain of salt,
though.

Re: Cleaning up git user-interface warts

[Andy Parkins]

On Wednesday 2006, November 15 17:55, Junio C Hamano wrote:

> I think the latter is what clone has done always; take remote's
> HEAD and use that to initialize local master (there is no

It's this sort of thing that is confusing though - the remote HEAD branch 
could be anything, and yet that is made to be origin locally as a tracking 
branch and then master as the writable branch.  What if upstream /has/ a 
master but "next" is its HEAD?  You'd then get

 next:remotes/origin
 master:remotes/master

Then a local master which is actually upstream next!  Oh dear.

I may well have misunderstood what you've said above above clone always 
initialising master from remote's HEAD; if so please disregard what I'm 
saying.

> > that as soon as git-clone has special capabilities (like --shared,
> > --local and --reference) then you are prevented from doing magic with
> > existing repositories.
>
> That is not entirely true.  clone has convenience because people
> asked.  It does not have to mean you are not allowed to give
> similar convenience to other commands.  Patches?

Absolutely, that was why I said clone shouldn't have special abilities.  In 
fact, if you're willing you don't need clone at all; you just need 
git-init-db and to write the correct remotes file.  

> > branches from two other local repositories that have the objects hard
> > linked?
>
> fetch by second local repository with git-local-fetch perhaps.

Is that not plumbing?  I thought this was about porcelain.

> A consensus would not write code and it generally does not take
> technology into account to tell what is realistic and what is
> not, so the result needs to be take with a grain of salt,
> though.

Of course, I only suggested it because the same suggestions were popping up 
multiple times.  Anyway; I put it in the GitWiki at 
http://git.or.cz/gitwiki/Wishlist

Andy

-- 
Dr Andrew Parkins, M Eng (Hons), AMIEE

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 10:17:22AM CET, Andy Parkins wrote:
> On Wednesday 2006 November 15 04:32, Nicolas Pitre wrote:
> 
> > 3) remote branch handling should become more straight forward.
> 
> I was completely confused by this origin/master/clone stuff when I started 
> with git.  In hindsight, now I understand git a bit more, this is what I 
> would have liked:
> 
>  * Don't use the name "origin" twice.  In fact, don't use it at all.  In a 
> distributed system there is no such thing as a true origin.
> 
>  * .git/remotes/origin should be ".git/remotes/default".   "origin" is only 
> special because it is the default to push and pull - it's very nice to have a 
> default, but it should therefore be /called/ "default".

  But "default" is way too generic a name, it's much more confusing I
think. As the one guilty of inventing master and origin, I agree that
they are somewhat silly, but if I would have to pick which one to
replace with something "better", I'd much rather pick master.

  Yes, Git can operate in a completely distributed manner. People do use
it as it. And there are also people that have no origin branch in their
repository. But the vast (overwhelming!) majority of people _does_ work
in some kind of hierarchical setup, and for them origin does have a
meaning. And origin URL can even change over time!

>  * git-clone should really just be a small wrapper around
>     - git-init-db
>     - create .git/remotes/default
>     - maybe create specific .git/config
>     - git-fetch default
>    If git-clone does anything that can't be done with settings in the config 
> and the remotes/default file then it's wrong.  The reason I say this is that 
> as soon as git-clone has special capabilities (like --shared, --local 
> and --reference) then you are prevented from doing magic with existing 
> repositories.  For example; how do you create a repository that contains 
> branches from two other local repositories that have the objects hard linked?

  Here I think that modulo the lack of remotes support (which is not a
fundamental thing here), the general setup of how Cogito does stuff is
much more saner than the current Git mess. It does basically exactly
what you've said above, and even the fetching itself is IMHO written
much more cleanly than in Git. In an ideal world, Git would just take
Cogito's code here. :-)

> While I'm writing wishes, I'd like to jump on Junio's integration with other 
> fetch-backends wish.  I use git-svn, and it would be fantastic if I could 
> replace:
> 
> git-svn init --id upstream/trunk svn://host/path/trunk
> git-svn fetch --id upstream/trunk
> git-svn init --id upstream/stable svn://host/path/branches/stable
> git-svn fetch --id upstream/stable
> 
> With a .git/remotes/svn
>  SVN-URL: svn://host/path
>  Pull: trunk:refs/remotes/upstream/trunk
>  Pull: branches/stable:refs/remotes/upstream/stable
> and
>  git fetch svn
> 
> Obviously, the syntax is just made up; but you get the idea.  Even better, 
> would be if it could cope with my "*" syntax suggested above:
>  SVN-URL: svn://host/path
>  Pull: trunk:refs/remotes/upstream/trunk
>  Pull: branches/*:refs/remotes/upstream/*

  It shouldn't be hard to do at all. Have the porcelain call "protocol
drivers" based on protocol in some generic way, like
/usr/lib/git/protocol/$proto.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Andreas Ericsson]

Nicolas Pitre wrote:

[ axed a lot of stuff that I didn't fully grok ]

> 
> This becomes formalized as:
> 
> 	git_pull [<URL>] [<local_name>]
> 
> If <URL> includes a branch name then <local_name> is a single branch 
> name.  If <URL> doesn't include any branch name then <local_name> 
> becomes a local branch group name containing all branches in the remote 
> repository.

I would change that so "local_name" is always a branch group name, but 
branch group names can be used as refs. That is,

git pull startrek.com/kirk.git:master kirk

would always create the branch-head .git/refs/remote/kirk/master which 
for short can be referenced as just "kirk" (barring clashes ofc), so 
long as it only has one branch tracked.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Cleaning up git user-interface warts

[Jakub Narebski]

Andreas Ericsson wrote:

> Nicolas Pitre wrote:
> 
> [ axed a lot of stuff that I didn't fully grok ]
> 
>> 
>> This becomes formalized as:
>> 
>>      git_pull [<URL>] [<local_name>]
>> 
>> If <URL> includes a branch name then <local_name> is a single branch 
>> name.  If <URL> doesn't include any branch name then <local_name> 
>> becomes a local branch group name containing all branches in the remote 
>> repository.
> 
> I would change that so "local_name" is always a branch group name, but 
> branch group names can be used as refs. That is,
> 
> git pull startrek.com/kirk.git:master kirk

I'd rather use Cogito (not gitweb) notation startrek.com/kirk.git#master
This way we can change the name of local branch
   startrek.com/kirk.git#master:kirk
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Wed, Nov 15, 2006 at 05:32:06AM CET, Nicolas Pitre wrote:
> 1) make "git init" an alias for "git init-db".
> 
> What's the point of "-db"?  Sure we're initializing the GIT database.  
> But who cares?  The user doesn't care if GIT uses a "database" or 
> whatever.  And according to some people's definition of a "database" it 
> could be argued that GIT doesn't use a database at all in the purist 
> sense of it. What the user wants is to get started and "init" (without 
> the "-db" is so much more to the point. Doesn't matter if incidentally 
> it happens to be the same keyword HG uses for the same operation because 
> we are not afflicted by the NIH disease, right? And it has 3 chars less 
> to type which is for sure a premium improvement to the very first GIT 
> user experience!

(This is somewhat related to the HEAD issue, e.g.
<7v1wo3d6g4.fsf@assigned-by-dhcp.cox.net>, by virtue of basically
eliminating it.)

Let's see. If you are adding the alias, you can as well add some
porcelain stuffing in it, too.

What are the 99% of use cases when doing "init"?

(a) You are going to do an initial commit right away; the repository is
at this point basically useless for anything but initial commit. So you
might have "init" well just perform it for you right away.

(b) You are setting up a bare repository on a server and you will push
to it in a minute. Cogito has a separate cg-admin-setuprepo command for
it, which will also prepare it for usage by dumb servers and optionally
for shared usage in a group of users. Git could have something similar.


> 2) "pull" and "push" should be symmetrical operations
..snip..
> Conclusion:  git-pull must not perform any merge.  It is the symmetrical 
> operation of a push meaning that it pulls content from a remote branch 
> and does no more.  People understands that pretty well, .  This makes 
> git-fetch redundant (or an alias to git-pull) in that case, and again we 
> don't mind it becoming similar to in HG because we admit HG was right 
> about it.

If you _really_ want to do it in Git, the only sensible way to do it is
to stop using the "pull" verb for a command name altogether for at least
some rather long period of time, otherwise that's a blatant backwards
compatibility breakage.

> 3) remote branch handling should become more straight forward.
> 
> OK! Now that we've solved the pull issue and that everybody agrees with 
> me (how can't you all agree with me anyway) let's have a look at remote 
> branches.  It should be simple:
..snip..

By the way, due to the way you describe it, it's not all that clear to
me how is this (in)compatible with the current way we do it, on other
than the usage and git-pull's auto-creation magic level.

Is it that what you are describing _is_ in fact what we do support now,
with "branch groups" meaning "remotes" etc, and you are only proposing
some enhancements to automatically create remotes in git-pull, or are
there some other differences I've missed?

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Tue, Nov 14, 2006 at 11:36:19PM CET, Junio C Hamano wrote:
> Commenting on the messages in this thread:
> 
>  - "resolve / resolved" are both confusing, when you are talking
>    about "mark-resolved" operation.

Well that's what "resolved" is saying. But speaking of which, it took me
_weeks_ of regular (though not extensive) usage to train my fingers to
write "stg resolved" and not "stg resolve".

>  - "pull/push/fetch" have undesired confusion depending on where
>    people learned the term.  I'd perhaps vote for replacing
>    fetch with download and push with upload.

It's too long. :-(

I think if some people have a real problem with something it's "pull",
not push or fetch. Without "pull" name, there's no confusion about
merging or not merging; and without it, there's also no confusion about
"push" and the fetch/push duality. I'm not saying that this is enough an
argument to ditch pull from Git at this point.

>  - I think it would be sensible to make remote tracking branches
>    less visible.  For example:
> 
> 	git diff origin
> 
>    where origin is the shorthand for your upstream (e.g. you
>    have .git/remotes/origin that records the URL and the branch
>    you are tracking) should be easier to understand than
> 
>    	git diff remotes/origin/HEAD
> 
>    The latter is an implementation detail.

Hmm, wait. I didn't start using refs/remotes/ yet for obvious reasons,
but wasn't it generally agreed when implementing them that what you
wrote above would work? (That a ref not found in refs/{heads,tags}/ is
looked up in remotes and if it's a directory, /HEAD is appended.) So it
doesn't for some reason?

>    I could imagine we might even want to allow
> 
> 	git diff origin#next
> 
>    to name the branch of the remote repository.  The notion of
>    "where the tips of remote repository's branches are" is
>    probably be updated by "git download" (in other words, the
>    above "git diff" does not automatically initiate network
>    transfer).

Yes, that little syntax extension would be cute to have.

> Of course, it could even be "cg" ;-).

So, here is an arbitrary list of random reasons why cg commands are not
part of git yet:

(i) Naming issues. Example: "pull" vs. "update".

(ii) Namespace issues. Big selling point of Cogito is that it's
_simple_. A very important part of that is that your command set is
limited, so that even someone who wants to fully grok Cogito is not
overwhelmed and has just few commands in front of him. I think we're
doing pretty good here, and I very carefully weight adding another
command to the set (I'm actually pondering removing some now). The
similar applies to actual commands' usage, though certainly not so
heavily; and there are few warts here.

But overally, I think this point is pretty much unsolvable and this is
where I actually think the main "incompatibleness" of Cogito and Git
with its free mix of high- and mid- and low- level commands lies. I
don't think the thread provided any solution to this either.

(ii) Behaviour issues. Example: Cogito tries to deal with uncommitted
local changes in your repository when doing stuff. It didn't shine at it
before recent improvements (post-v0.18), but it tried to preserve your
local uncommitted changes during various operations (merging,
fast-forwarding, switching branches, seeking, ...). I think historically
Git's stance to this was negative (it'd rather block the operation), I'm
not sure what the current situation is, though.

(iii) Output format issues. Example: "status" in Git and Cogito
has a completely different format in both. I'm a die-hard fan of
Cogito's format but there're surely die-hard fans of Git's.

(iv) Control issues. I'm reluctant to give up a final word on how the UI
looks like, mostly for the reason of enforcing (ii) and proper
documentation. But this is not a blocker point.

(v) Library issues. Cogito has a pretty neat shell library which it
prices; but that could be carried around. Also, Cogito requires
/bin/bash, but mostly for performance reasons (using builtins instead of
forking for external commands at some points); Git has the advantage of
simply putting that part in C, which is though something I should've
been doing more frequently too.

(vi) Coding issues. This is probably very subjective, but a blocker for
me. I have no issues about C here, but about the shell part of Git.
Well, how to say it... It's just fundamentally incompatible with me. I
*could* do things in/with it, but it's certainly something I wouldn't
_enjoy_ doing _at all_, on a deep level. I think the current shell code
is really hard to read, the ancient constructs are frequently strange at
best, etc. It's surely fine code at functional level and there'll be
people who hate _my_ style of coding and my shell code which isn't
perfect either, but it's just how it is with me.


Now, it would be absolutely awesome if we could start to bridge at least
some of these points, shuffle some functionality around and overally
reduce the code duplication, increase features count and improve general
level of world happiness.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> (v) Library issues...
> Git has the advantage of
> simply putting that part in C, which is though something I should've
> been doing more frequently too.

It should be stressed that git-core plumbing written in C is not
just for git Porcelain-ish, and it will continue to be shared
service.  We would add core support for what Porcelains need and
we would try hard to keep them generic enough so that other
Porcelains can use them.  Keeping the core and Porcelain-ish in
the same project has made it easier to keep them in sync and to
find and add missing features that would benefit Porcelains (not
limited to git Porcelain-ish).  But that should not be mistaken
as plumbing somehow belongs more to git Porcelain-ish than to
Cogito or others.

I also think you should take credit for some core improvements
you did yourself (e.g "ls-files -t" format was originally added
for the sole purpose of helping Cogito, but now others use it,
too).

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 11:45:46AM CET, Junio C Hamano wrote:
> Petr Baudis <pasky@suse.cz> writes:
> 
> > (v) Library issues...
> > Git has the advantage of
> > simply putting that part in C, which is though something I should've
> > been doing more frequently too.
> 
> It should be stressed that git-core plumbing written in C is not
> just for git Porcelain-ish, and it will continue to be shared
> service.  We would add core support for what Porcelains need and
> we would try hard to keep them generic enough so that other
> Porcelains can use them.  Keeping the core and Porcelain-ish in
> the same project has made it easier to keep them in sync and to
> find and add missing features that would benefit Porcelains (not
> limited to git Porcelain-ish).  But that should not be mistaken
> as plumbing somehow belongs more to git Porcelain-ish than to
> Cogito or others.

  Of course, I didn't mean to say that. I should do more often things
like adding --stdin to the fetchers. From one part, I'm used to work
with a fixed set of system tools and extending Git with the
functionality I want means changing my thinking mode and "jumping out of
the system" a bit. The other part is that I cannot use the improvements
in Cogito right away (at least not in the main branch) but I have to
wait for the next Git release; but this is mostly just an excuse. :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> (vi) Coding issues. This is probably very subjective, but a blocker for
> me. I have no issues about C here, but about the shell part of Git.
> Well, how to say it... It's just fundamentally incompatible with me. I
> *could* do things in/with it, but it's certainly something I wouldn't
> _enjoy_ doing _at all_, on a deep level. I think the current shell code
> is really hard to read, the ancient constructs are frequently strange at
> best, etc. It's surely fine code at functional level and there'll be
> people who hate _my_ style of coding and my shell code which isn't
> perfect either, but it's just how it is with me.

I've been thinking about revamping the style of shell scripts in
git-core Porcelain-ish for some time, and I have a feeling that
now may be a good time to do so, after one feature release is
out and the list is discussing UI improvements.

But before mentioning the specifics, let me mention one tangent.
I recently installed an OpenBSD bochs (it was actually a qemu
image) without knowing much about the way of the land, and after
adjusting myself to necessary glitches (like "make" being called
"gmake" there), I saw git properly built and pass its selftest.
I was pleasantly surprised when I noticed there was no 'bash' on
the system after all that.

I would like to keep it that way.

I'll list things I would want to and not want to change.
Comments from the list are very appreciated.  You can say things
in two ways:

 * I guarantee that the _default_ shell on all sane platforms we
   care about handle this construct correctly, although it was
   not in the original Bourne.  There is no reason to stay away
   from it these days.

or

 * You've stayed away from this construct but now you say you
   feel it is Ok to use it.  Don't.  It would break with the
   shell on my platform (or "it is a bad practice because of
   such and such reasons").

I do not think many people can say the former with authority
unless you have a portability lab (the company I work for used
to be like that and it was an interesting experience to learn
all about irritating implementation differences).  And "POSIX
says shell should behave that way" is _not_ what I want to hear
about.

But the latter should be a lot easier to say, and would be
appreciated because it would help us avoid regressions.

Things I would want to change:

 - One indent level is one tab and the tab-width is eight
   columns.  Some of our scripts tend to use less than eight
   spaces for indentation to avoid line wrapping.

 - More use of shell functions are fine.   Especially if the
   above change makes lines too long, the logic should be
   refactored.

 - It is so 80-ish to follow certain portability and performance
   wisdom.  The following should go:

   . Use "case" when you do not have to use "if test".

   . Avoid ${parameter##word} and friends and use `expr` instead
     to pick a string apart.

   . Avoid "export name=word", write "name=word; export name"
     instead.

   . Avoid ${parameter:-word} and friends when ${parameter-word}
     would do.

Things I do not want to change:

 - The shell scripts should start with #!/bin/sh, not
   #!/bin/bash (nor even worse "#!/usr/bin/env sh").

 - Shell functions are written as "name () { ... }" without 
   "function" noiseword.

 - 'foo && bar || exit' exits with the error code of what
   failed; no need to say 'exit $?'.

 - String equality check for "test" is a single =, not ==. 

 - Do not use locals.

 - Do not use shell arrays.

 - In general, if something does not behave the same way in ksh,
   bash and dash, don't use it (that does not mean these three
   are special; it just means if something is not even portable
   across these three, it is a definite no-no).

I do not think I need to list other common-sense shell idioms in
the latter category (e.g. 'using "test z$name = zexpected" when
we do not know what $name contains' falls into that).

Re: Cleaning up git user-interface warts

[Petr Baudis]

On Thu, Nov 16, 2006 at 10:49:36PM CET, Junio C Hamano wrote:
> I would like to keep it that way.

I agree - I certainly don't want to infect Git with bash dependency.

> And "POSIX says shell should behave that way" is _not_ what I want to
> hear about.

Actually, which sane platforms we care about have /bin/sh that is NOT
POSIX compatible?

> Things I would want to change:

What about [ instead of test? And

	if foo; then

instead of

	if foo
	then

?


Am I the only one who hates

case "$log_given" in
tt*)
        die "Only one of -c/-C/-F can be used." ;;
*tm*|*mt*)
        die "Option -m cannot be combined with -c/-C/-F." ;;
esac

instead of having this stuff in explicit variables and writing out some
explicit boolean expressions? (There _are_ few cases where the case is
cool, but they are rare.)


It would be really great if Git would have something alike the Cogito's
optparse infrastructure. I'm not sure if you can implement it in Bourne
sh with reasonable performance, though...


I think addressing these three particular points would make the scripts
hugely more coder-friendly. (And well, I usually say that coding style
is not *that* important and is frequently overemphasised. But that holds
only to a certain point. ;-)


> Things I do not want to change:
..snip all those I agree with..
>  - Do not use locals.

It's a pity. :-( Which shell doesn't support them?

It's not that huge a deal, though.

>  - Do not use shell arrays.

This is quite a larger deal, I think; but the portability concerns are
very real, I guess. :|

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: Cleaning up git user-interface warts

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

You already said this kind of details are subjective so I'd omit
the usual "I would think" and answer them without worrying about
a big style flamewar.  People, please be civil ;-).

> What about [ instead of test?

[ ] is not more readable.

> 	if foo; then
>
> instead of
>
> 	if foo
> 	then

Having "then" on the beginning of line is much more readable.

> Am I the only one who hates
>
> case "$log_given" in
> tt*)
>         die "Only one of -c/-C/-F can be used." ;;
> *tm*|*mt*)
>         die "Option -m cannot be combined with -c/-C/-F." ;;
> esac

This is much more readable without "case".  "abandon the old
rule that told us to avoid if when case would do" applies.
Although it is about multiple possibility switch (so a case can
be made that "case" is appropriate here), we should reduce the
use of "case" to cases like the outermost big "case" you find in
git-merge-one-file-script.

> It would be really great if Git would have something alike the Cogito's
> optparse infrastructure. I'm not sure if you can implement it in Bourne
> sh with reasonable performance, though...

getopt(1) is fine, unless somebody screams that it is not
available on his platform.

Re: Cleaning up git user-interface warts

[Han-Wen Nienhuys]

Petr Baudis escreveu:
> (vi) Coding issues. This is probably very subjective, but a blocker for
> me. I have no issues about C here, but about the shell part of Git.
> Well, how to say it... It's just fundamentally incompatible with me. I

(on a tangent)

I concur, but probably in a different way.

some 10 years ago I vowed never to write perl code again, and some 5
years ago, I made the same pledge for shell scripts, because I spent
inordinate amounts of time debugging them.

When I see the GIT shell scripts, my hands start to itch to make a
nice object oriented Python wrapper for it.

-- 

Re: Cleaning up git user-interface warts

[Alan Chandler]

On Tuesday 14 November 2006 22:36, Junio C Hamano wrote:
...
>
> And I agree with Pasky that fixing UI is hard unless you are
> willing to get rid of historical warts.  Syntax of the command
> line arguments the current set of Porcelain-ish takes are
> sometimes just horrible.  It may not be a bad idea to start
> building the fixed UI from scratch, using different prefix than
> "git" (say "gu" that stands for "git UI" or "gh" that stands for
> "git for humans").
>
> Of course, it could even be "cg" ;-).

I have been away on business last week and have been following this thread 
from the archives.  There is a comment I want to make about split of 
Porcelain and Plumbing namespaces that is not particularly an answer to this 
particular post, but it does seem an appropriate place to insert it.

I think there were three (historic) mistakes in the development of git
	- to split git and cogito so that some of the commands started git and some 
cg (aided and abetted by putting them in separate repositories).
	- to try and make the distinction between plumbing and porcelein a line in 
the sand (after all this is exactly why git and cg separated) when in 
practice it isn't that straight forward
	- for cogito to (initially) not support the internal branches, but in fact 
deal with them via cloned repositories

On the other hand, it was a good move to bring gitk and gitweb into the core 
repository.

These were not technical mistakes, but social ones.

Much of the discussion on UI warts doesn't exist in the cogito world (not that 
I use it at all anymore, despite its more user friendly interface - just 
because I didn't want to learn two parallel sets of commands and I prefered 
git's branch model so stuck with the slightly less friendly git command set) 
but if you look at any of the SCM comparison discussions that happen now, 
they are always comparing the core git with the other SCM, not git plus all 
its porcelains.

So I think it would be a mistake (which hopefully does seem to be the 
concensus reached in the list) to try and introduce new namespaces to the 
command set.
-- 
Alan Chandler

Re: [PATCH] commit: Steer new users toward "git commit -a" rather than update-index

[Junio C Hamano]

Andy Whitcroft <apw@shadowen.org> writes:

> Are we sure this isn't porcelain-ish?  We need to use it in merge
> conflict correction and the like?  You can't use git-commit there as a
> replacement.  I'd expect it to be 'git update-index' rather than
> 'git-update-index' of course.

I think status should be taken as Porcelain-ish so it should
notice more about the environment to see why the user has
changed but not updated files and recommend the possible action
depending on the context.

For that, you would need to enumerate what kind of 'context'
there could be with the current set of tools.  Here is a
strawman.

 1. None of the below.
 2. A merge was attempted and resulted in a conflict.
 3. An am or rebase without --merge was attempted and
    resulted in a conflict or patch rejection.
 4. A "rebase --merge was attempted and resulted in a conflict.

In the normal case, the next user action would be:

 1-1. The user wants that change in the next commit, and should
      run "git update-index $that_path" to prepare the index for
      partial commit, or "git commit -a" to commit all the
      changes made to the working tree so far.  Carl's patch
      helps the user in this case.

 1-2. The user realizes that the some of the changes in the
      working tree were not desirable, and "git checkout --
      $that_path" to revert them before continuing.  Before
      deciding to revert, the user may want to check what the
      difference is by running "git diff -- $that_path" so
      suggesting these two might also be helpful.

 1-3. The user wants to keep that change a strictly local change
      in the working tree (this is often very useful and making
      "commit -a" the default will not be acceptable unless
      there is a very compelling reason to do so).  This means
      the suggestion we would make should clearly be
      _suggestion_.

The earlier wording was bad in that it suggested to use a
Plumbing command update-index, but was attempting to convey that
it was merely a conditional suggestion by saying "use it TO MARK
FOR COMMIT", implying that if the user does not want to mark
them for commit, it is Ok not to use update-index.

When a merge is in progress, we would have .git/MERGE_HEAD and
that would be the way to tell case 2.  In that case, the next
user action would be:

 2-1. The user resolves conflicts and marks them as resolved,
      with update-index (or "git mark-resolved"), to prepare the
      index for the merge commit.  But this is not done for
      "Changed but not updated" files but "unmerged" files.  We
      should strongly suggest not to do _anything_ to "Changed
      but not updated" files here.

 2-2. The user decides this conflict is too much to handle right
      now, and abandones the change by "git reset --hard".  This
      would lose the local changes ("Changed but not updated"),
      so we should suggest to save the change before doing so.

	If you are going to abandone this merge with "reset
	--hard", your changes to these files will be lost.  You
	can save them with "git diff HEAD -- $this_path
	$that_path..."

      which is probably too long for that part of the output but
      that is what we would want to say if we want to be
      helpful.

When either rebase without --merge or am is in progress, there
would be .dotest/ directory (whose name could be changed but I
think this was a mistake and we would be better off using fixed
names for this kind of application) for git-status to notice.
The next user action would be:

 3-1. The user resolves the conflict or manually apply the
      patch, update-index the paths involved and proceeds with
      "rebase --continue" or "am --resolved".  "Changed but not
      updated" paths should not be touched in this case,
      similarly to 2-1.

 3-2. The user gives up.  Same as 2-2.

Designing for the "rebase --merge" case and coming up with other
cases are left as exercise to the list for further discussion.

Git 1.0 Synopis (Draft v2)

[Ryan Anderson]

[This is still a draft, but I think I incorporated the suggestons from
the last attempt.]

Source Code Management with Git

Git, sometimes called "global information tracker", is a "directory
content manager".  Git has been designed to handle absolutely massive
projects with speed and efficiency, and the release of the 2.6.12 and
(soon) the 2.6.13 version of the Linux kernel would indicate that it
does this task well.

Git falls into the category of distributed source code management tools,
similar to Arch or Darcs (or, in the commercial world, BitKeeper).  Every Git
working directory is a full-fledged repository with full revision tracking
capabilities, not dependent on network access to a central server.

Git uses the SHA1 hash algorithm to provide a content-addressable pseudo
filesystem, complete with its own version of fsck.
  o Speed of use, both for the project maintainer, and the end-users, is
    a key development principle.
  o The history is stored as a directed acyclic graph, making long-lived
    branches and repeated merging simple.
  o A collection of related projects are building on the core Git project,
    either to provide an easier to use interface on top (StGit, Cogito, qgit,
    gitk, gitweb), or to take some of the underlying concepts and reimplement
    them directly into another system (Arch 2.0, Darcs-git).
  o Two, interchangeable, on-disk formats are used:
    o An efficient, packed format that saves spaced and network
      bandwidth.
    o An unpacked format, optimized for fast writes and incremental
      work.

To get a copy of Git:
	Daily snapshots are available at:
	http://www.codemonkey.org.uk/projects/git-snapshots/git/
	(Thanks to Dave Jones)

	Source tarballs and RPMs at:
	http://www.kernel.org/pub/software/scm/git/

	Deb packages at:
	<insert url here>

	Or via Git itself:
	git clone http://www.kernel.org/pub/scm/git/git.git/
	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/
	(rsync is generally faster for an initial pull)

Git distributions contain a tutorial in the Documentation subdirectory.
Additionally, the Kernel-Hacker's Git Tutorial at
http://linux.yyz.us/git-howto.html may be useful.  (Thanks to Jeff Garzik for
that document)

Git development takes place on the Git mailing list.  To subscribe, send an
email with just "subscribe git" in the body to majordomo@vger.kernel.org.
Mailing list archives are available at http://marc.theaimsgroup.com/?l=git

Git results from the inspiration and frustration of Linus Torvalds, and
the enthusiastic help of over 300 participants on the development
mailing list.[1]  It is maintained by Junio C Hamano <junkio@cox.net>.

1 - Generated with the following, in a maildir folder:
        find . -type f | xargs grep -h "^From:" | perl -ne \
        'tr#A-Z#a-z#; m#<(.*)># && print $1,"\n";' | sort -u | wc -l

(This summary written by Ryan Anderson <ryan@michonline.com>.  Please bug him
with any corrections or complaints.)




-- 

Ryan Anderson
  sometimes Pug Majere

Re: Git 1.0 Synopis (Draft v2)

[Junio C Hamano]

Ryan Anderson <ryan@michonline.com> writes:

> Source Code Management with Git

Thanks for doing this.  Generally looks excellent.

>   o Two, interchangeable, on-disk formats are used:
>     o An efficient, packed format that saves spaced and network
>       bandwidth.

??? "spaced" ???

> 	Or via Git itself:
> 	git clone http://www.kernel.org/pub/scm/git/git.git/
> 	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/
> 	(rsync is generally faster for an initial pull)

These need a target directory name to create, like this:

    git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ $new_dir
    git clone http://www.kernel.org/pub/scm/git/git.git/ $new_dir

> Git results from the inspiration and frustration of Linus Torvalds, and
> the enthusiastic help of over 300 participants on the development
> mailing list.[1]  It is maintained by Junio C Hamano <junkio@cox.net>.

Please drop the e-mail address here; you mention nobody else's.

Well, dropping "the current maintainer" information altogether
might be even better; the above to a casual reader sounds like
Linus was frustrated and I wrote it for him, which is definitely
not what we would like to say.  I suspect it still has more code
by Linus than anybody else (I stopped counting some time ago).

Re: Git 1.0 Synopis (Draft v2)

[Ryan Anderson]

On Wed, Jul 27, 2005 at 03:13:18PM -0700, Junio C Hamano wrote:
> > Git results from the inspiration and frustration of Linus Torvalds, and
> > the enthusiastic help of over 300 participants on the development
> > mailing list.[1]  It is maintained by Junio C Hamano <junkio@cox.net>.
> 
> Please drop the e-mail address here; you mention nobody else's.
> 
> Well, dropping "the current maintainer" information altogether
> might be even better; the above to a casual reader sounds like
> Linus was frustrated and I wrote it for him, which is definitely
> not what we would like to say.  I suspect it still has more code
> by Linus than anybody else (I stopped counting some time ago).

Ok.  I was thinking I could add "current" into that description.  Or,
something like, "Linus has since returned his focus to the kernel, and
passed maintainership to ...".

-- 

Ryan Anderson
  sometimes Pug Majere

Git 1.0 Synopis (Draft v3

[Ryan Anderson]

Source Code Management with Git

"git" can mean anything, depending on your mood.

 - random three-letter combination that is pronounceable, and not
   actually used by any common UNIX command.  The fact that it is a
   mispronunciation of "get" may or may not be relevant.
 - stupid. contemptible and despicable. simple. Take your pick from the
   dictionary of slang.
 - "global information tracker": you're in a good mood, and it actually
   works for you. Angels sing, and a light suddenly fills the room. 
 - "goddamn idiotic truckload of sh*t": when it breaks

Git is a "directory content manager".  Git has been designed to handle
absolutely massive projects with speed and efficiency, and the release of the
2.6.12 and (soon) the 2.6.13 version of the Linux kernel would indicate that it
does this task well.

Git falls into the category of distributed source code management tools,
similar to Arch or Darcs (or, in the commercial world, BitKeeper).  Every Git
working directory is a full-fledged repository with full revision tracking
capabilities, not dependent on network access to a central server.

Git provides a content-addressable pseudo filesystem, complete with its own
version of fsck.

  o Speed of use, both for the project maintainer, and the end-users, is
    a key development principle.

  o The history is stored as a directed acyclic graph, making long-lived
    branches and repeated merging simple.

  o The core Git project considers itself to provide "plumbing" for other
     projects, as well as to serve to arbitrate for compatibility between them.
     The project built on top of the core Git are referred to as "porcelain".
     StGit, Cogito, qgit, gitk and gitweb are all building upon the core Git
     tools, and providing an easy to use interface to various pieces of
     functionality.

  o Some other projects have taken the concepts from the core Git project, and
    are either porting an existing toolset to use the Git tools, or
    reimplementing the concepts internally, to benefit from the performance
     improvements.  This includes both Arch 2.0, and Darcs-git.
  
  o Two, interchangeable, on-disk formats are used:
    o An efficient, packed format that saves space and network
      bandwidth.
    o An unpacked format, optimized for fast writes and incremental
      work.

To get a copy of Git:
	Daily snapshots are available at:
	http://www.codemonkey.org.uk/projects/git-snapshots/git/
	(Thanks to Dave Jones)

	Source tarballs and RPMs at:
	http://www.kernel.org/pub/software/scm/git/

	Deb packages at:
	<insert url here>

	Or via Git itself:
	git clone http://www.kernel.org/pub/scm/git/git.git/ <local directory>
	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ <local directory>

	(rsync is generally faster for an initial clone, you can switch later
	by editing .git/branches/origin and changing the url)

To get the 'Porcelain' tools mentioned above:
	SCM Interface layers:
	cogito - http://www.kernel.org/pub/software/scm/cogito/
	StGIT - http://www.procode.org/stgit/

	History Visualization:
	gitk - http://ozlabs.org/~paulus/gitk/
	gitweb - http://www.kernel.org/pub/software/scm/gitweb/
	qgit - http://sourceforge.net/projects/qgit


Git distributions contain a tutorial in the Documentation subdirectory.
Additionally, the Kernel-Hacker's Git Tutorial at
http://linux.yyz.us/git-howto.html may be useful.  (Thanks to Jeff Garzik for
that document)

Git development takes place on the Git mailing list.  To subscribe, send an
email with just "subscribe git" in the body to majordomo@vger.kernel.org.
Mailing list archives are available at http://marc.theaimsgroup.com/?l=git

(This summary written by Ryan Anderson <ryan@michonline.com>.  Please bug him
with any corrections or complaints.)

Re: Git 1.0 Synopis (Draft v3

[Johannes Schindelin]

I like it!

Ciao,
Dscho

Re: Git 1.0 Synopis (Draft v3

[Sam Ravnborg]

On Fri, Jul 29, 2005 at 04:29:41AM -0400, Ryan Anderson wrote:
> Source Code Management with Git
....

The article should include a HOWTO part alos. So people can see how to
edit a file, pull from a remote repository etc.
Since you have introduced core and porcelains it would be most logical
to use one of the porcelains in these examples, maybe accompanied by the
raw git commands being executed.

	Sam

Re: Git 1.0 Synopis (Draft v3

[Horst von Brand]

Sam Ravnborg <sam@ravnborg.org> wrote:
> On Fri, Jul 29, 2005 at 04:29:41AM -0400, Ryan Anderson wrote:
> > Source Code Management with Git
> ....

> The article should include a HOWTO part alos.

I'd vote for a separate file.

>                                               So people can see how to
> edit a file, pull from a remote repository etc.

Exactly.

> Since you have introduced core and porcelains it would be most logical
> to use one of the porcelains in these examples, maybe accompanied by the
> raw git commands being executed.

Better leave the Porcelain-HOWTO to individual Porcelain. Perhaps the
Plumbing-HOWTO should include a section on interfacing to Porcelain (or it
should be yet another file).
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Git 1.0 Synopis (Draft v3

[Horst von Brand]

Ryan Anderson <ryan@michonline.com> wrote:
> Source Code Management with Git

More bugging...

- Either stay with your idea of "Git is the idea, git the implementation"
  (iff blessed by the Git Powers That Be) and be consistent about it, or
  just use "git" throughout.

- Attribute the meaning appropiately, say by:

In Linus' own words as the inventor of git:

> "git" can mean anything, depending on your mood.
> 
>  - random three-letter combination that is pronounceable, and not
>    actually used by any common UNIX command.  The fact that it is a
>    mispronunciation of "get" may or may not be relevant.
>  - stupid. contemptible and despicable. simple. Take your pick from the
>    dictionary of slang.
>  - "global information tracker": you're in a good mood, and it actually
>    works for you. Angels sing, and a light suddenly fills the room. 
>  - "goddamn idiotic truckload of sh*t": when it breaks
[...]

> To get a copy of Git:
> 	Daily snapshots are available at:
> 	http://www.codemonkey.org.uk/projects/git-snapshots/git/
> 	(Thanks to Dave Jones)
> 
> 	Source tarballs and RPMs at:
> 	http://www.kernel.org/pub/software/scm/git/
> 
> 	Deb packages at:
> 	<insert url here>
> 
> 	Or via Git itself:
> 	git clone http://www.kernel.org/pub/scm/git/git.git/ <local directory>
> 	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ <local directory>
> 
> 	(rsync is generally faster for an initial clone, you can switch later
> 	by editing .git/branches/origin and changing the url)
> 
> To get the 'Porcelain' tools mentioned above:
> 	SCM Interface layers:
> 	cogito - http://www.kernel.org/pub/software/scm/cogito/
> 	StGIT - http://www.procode.org/stgit/

At least cogito includes a (slightly old) version of git. Dunno about
StGIT. And git and cogito have a gitk inside too. This should be mentioned,
i.e., look at the package(s) you are interested and see what else they
carry or require and keep in mind that (for now?) getting git as part of
one package is /not/ guaranteed to be compatible with another or standard
git.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Git 1.0 Synopis (Draft v3

[Horst von Brand]

[Yes, I know it is considered odd when you speak to yourself in public...]

Horst von Brand <vonbrand@inf.utfsm.cl> wrote:
> Ryan Anderson <ryan@michonline.com> wrote:
> > Source Code Management with Git

> More bugging...

And then some.

> > To get the 'Porcelain' tools mentioned above:
> > 	SCM Interface layers:
> > 	cogito - http://www.kernel.org/pub/software/scm/cogito/
> > 	StGIT - http://www.procode.org/stgit/
> 
> At least cogito includes a (slightly old) version of git. Dunno about
> StGIT. And git and cogito have a gitk inside too. This should be mentioned,
> i.e., look at the package(s) you are interested and see what else they
> carry or require and keep in mind that (for now?) getting git as part of
> one package is /not/ guaranteed to be compatible with another or standard
> git.

Also note that StGIT is /not/ a SCM (as cogito is), it is a tool to shuffle
patches that uses git as a backend/target.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Git 1.0 Synopis (Draft v4)

[Ryan Anderson]

On Sun, Jul 31, 2005 at 06:15:40PM -0400, Horst von Brand wrote:
> Ryan Anderson <ryan@michonline.com> wrote:
> > Source Code Management with Git
> 
> More bugging...

Ok, I think I've got all this addressed (plus the other email).

It just took me a lot longer to get to it than I planned.

Junio, do you want to pull this into the git tree?  (I'll reply with a
patch)

==========

Source Code Management with git

In Linus's own words as the creator of git:
"git" can mean anything, depending on your mood.

 - random three-letter combination that is pronounceable, and not
   actually used by any common UNIX command.  The fact that it is a
   mispronunciation of "get" may or may not be relevant.
 - stupid. contemptible and despicable. simple. Take your pick from the
   dictionary of slang.
 - "global information tracker": you're in a good mood, and it actually
   works for you. Angels sing, and a light suddenly fills the room. 
 - "goddamn idiotic truckload of sh*t": when it breaks

git is a "directory content manager".  git has been designed to handle
absolutely massive projects with speed and efficiency, and the release of the
2.6.12 and (soon) the 2.6.13 version of the Linux kernel would indicate that it
does this task well.

git falls into the category of distributed source code management tools,
similar to Arch or Darcs (or, in the commercial world, BitKeeper).  Every git
working directory is a full-fledged repository with full revision tracking
capabilities, not dependent on network access to a central server.

git provides a content-addressable pseudo filesystem, complete with its own
version of fsck.

  o Speed of use, both for the project maintainer, and the end-users, is
    a key development principle.

  o The history is stored as a directed acyclic graph, making long-lived
    branches and repeated merging simple.

  o The core git project considers itself to provide "plumbing" for other
     projects, as well as to serve to arbitrate for compatibility between them.
     The project built on top of the core git are referred to as "porcelain".
     Stgit, Cogito, qgit, gitk and gitweb are all building upon the core git
     tools, and providing an easy to use interface to various pieces of
     functionality.

  o Some other projects have taken the concepts from the core git project, and
    are either porting an existing toolset to use the git tools, or
    reimplementing the concepts internally, to benefit from the performance
     improvements.  This includes both Arch 2.0, and Darcs-git.
  
  o Two, interchangeable, on-disk formats are used:
    o An efficient, packed format that saves space and network
      bandwidth.
    o An unpacked format, optimized for fast writes and incremental
      work.

To get a copy of git:
	Daily snapshots are available at:
	http://www.codemonkey.org.uk/projects/git-snapshots/git/
	(Thanks to Dave Jones)

	Source tarballs and RPMs at:
	http://www.kernel.org/pub/software/scm/git/

	Debian packages should be availabe in unstable (sid) as "git-core"

	Or via git itself:
	git clone http://www.kernel.org/pub/scm/git/git.git/ <local directory>
	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ <local directory>

	(rsync is generally faster for an initial clone, you can switch later
	by editing .git/branches/origin and changing the url)

To get the 'Porcelain' tools mentioned above:
	SCM Interface layers:
	cogito - http://www.kernel.org/pub/software/scm/cogito/

	Patch Management (similar to Quilt):
	StGIT - http://www.procode.org/stgit/

	History Visualization:
	gitk - http://ozlabs.org/~paulus/gitk/ (Included in the standard git
		distribution)
	gitweb - http://www.kernel.org/pub/software/scm/gitweb/
	qgit - http://sourceforge.net/projects/qgit


git distributions contain a tutorial in the Documentation subdirectory.
Additionally, the Kernel-Hacker's git Tutorial at
http://linux.yyz.us/git-howto.html may be useful.  (Thanks to Jeff Garzik for
that document)

git development takes place on the git mailing list.  To subscribe, send an
email with just "subscribe git" in the body to majordomo@vger.kernel.org.
Mailing list archives are available at http://marc.theaimsgroup.com/?l=git

(This summary written by Ryan Anderson <ryan@michonline.com>.  Please bug him
with any corrections or complaints.)


-- 

Ryan Anderson
  sometimes Pug Majere

Re: Git 1.0 Synopis (Draft v4)

[Ryan Anderson]

Add a SYNOPSIS/release summary to the tree.

Signed-off-by: Ryan Anderson <ryan@michonline.com>

diff --git a/SYNOPSIS b/SYNOPSIS
new file mode 100644
--- /dev/null
+++ b/SYNOPSIS
@@ -0,0 +1,93 @@
+Source Code Management with git
+
+In Linus's own words as the creator of git:
+"git" can mean anything, depending on your mood.
+
+ - random three-letter combination that is pronounceable, and not
+   actually used by any common UNIX command.  The fact that it is a
+   mispronunciation of "get" may or may not be relevant.
+ - stupid. contemptible and despicable. simple. Take your pick from the
+   dictionary of slang.
+ - "global information tracker": you're in a good mood, and it actually
+   works for you. Angels sing, and a light suddenly fills the room. 
+ - "goddamn idiotic truckload of sh*t": when it breaks
+
+git is a "directory content manager".  git has been designed to handle
+absolutely massive projects with speed and efficiency, and the release of the
+2.6.12 and (soon) the 2.6.13 version of the Linux kernel would indicate that it
+does this task well.
+
+git falls into the category of distributed source code management tools,
+similar to Arch or Darcs (or, in the commercial world, BitKeeper).  Every git
+working directory is a full-fledged repository with full revision tracking
+capabilities, not dependent on network access to a central server.
+
+git provides a content-addressable pseudo filesystem, complete with its own
+version of fsck.
+
+  o Speed of use, both for the project maintainer, and the end-users, is
+    a key development principle.
+
+  o The history is stored as a directed acyclic graph, making long-lived
+    branches and repeated merging simple.
+
+  o The core git project considers itself to provide "plumbing" for other
+     projects, as well as to serve to arbitrate for compatibility between them.
+     The project built on top of the core git are referred to as "porcelain".
+     Stgit, Cogito, qgit, gitk and gitweb are all building upon the core git
+     tools, and providing an easy to use interface to various pieces of
+     functionality.
+
+  o Some other projects have taken the concepts from the core git project, and
+    are either porting an existing toolset to use the git tools, or
+    reimplementing the concepts internally, to benefit from the performance
+     improvements.  This includes both Arch 2.0, and Darcs-git.
+  
+  o Two, interchangeable, on-disk formats are used:
+    o An efficient, packed format that saves space and network
+      bandwidth.
+    o An unpacked format, optimized for fast writes and incremental
+      work.
+
+To get a copy of git:
+	Daily snapshots are available at:
+	http://www.codemonkey.org.uk/projects/git-snapshots/git/
+	(Thanks to Dave Jones)
+
+	Source tarballs and RPMs at:
+	http://www.kernel.org/pub/software/scm/git/
+
+	Debian packages should be availabe in unstable (sid) as "git-core"
+
+	Or via git itself:
+	git clone http://www.kernel.org/pub/scm/git/git.git/ <local directory>
+	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ <local directory>
+
+	(rsync is generally faster for an initial clone, you can switch later
+	by editing .git/branches/origin and changing the url)
+
+To get the 'Porcelain' tools mentioned above:
+	SCM Interface layers:
+	cogito - http://www.kernel.org/pub/software/scm/cogito/
+
+	Patch Management (similar to Quilt):
+	StGIT - http://www.procode.org/stgit/
+
+	History Visualization:
+	gitk - http://ozlabs.org/~paulus/gitk/ (Included in the standard git
+		distribution)
+	gitweb - http://www.kernel.org/pub/software/scm/gitweb/
+	qgit - http://sourceforge.net/projects/qgit
+
+
+git distributions contain a tutorial in the Documentation subdirectory.
+Additionally, the Kernel-Hacker's git Tutorial at
+http://linux.yyz.us/git-howto.html may be useful.  (Thanks to Jeff Garzik for
+that document)
+
+git development takes place on the git mailing list.  To subscribe, send an
+email with just "subscribe git" in the body to majordomo@vger.kernel.org.
+Mailing list archives are available at http://marc.theaimsgroup.com/?l=git
+
+(This summary written by Ryan Anderson <ryan@michonline.com>.  Please bug him
+with any corrections or complaints.)

-- 

Ryan Anderson
  sometimes Pug Majere

Re: Git 1.0 Synopis (Draft v4)

[Junio C Hamano]

Ryan Anderson <ryan@michonline.com> writes:

> Junio, do you want to pull this into the git tree?

Yes, but I have been wondering where it should go.  Should it go
under Documentation/ and made into html via asciidoc along with
other tools?

Re: Git 1.0 Synopis (Draft v4)

[Ryan Anderson]

On Sun, Aug 14, 2005 at 10:19:18PM -0700, Junio C Hamano wrote:
> Ryan Anderson <ryan@michonline.com> writes:
> 
> > Junio, do you want to pull this into the git tree?
> 
> Yes, but I have been wondering where it should go.  Should it go
> under Documentation/ and made into html via asciidoc along with
> other tools?

I was somewhat thinking it should go in the main directory, and be a
useful introduction to the project for people.... but it's not really
aimed at that very well, now that I think about it.

To be fair, it's not really aimed well at being documentation for people
that already have git, either.  I've been writing it with the idea of
"something to send to LWN when 1.0 happens so they can post it mostly
verbatim."

I guess this means, "I dunno, either place works for me."

-- 

Ryan Anderson
  sometimes Pug Majere

Re: Git 1.0 Synopis (Draft v4)

[Junio C Hamano]

Ryan Anderson <ryan@michonline.com> writes:

> I guess this means, "I dunno, either place works for me."

I was hoping it means to "Oh, come to think of it, maybe I
should send this to corbet@lwn.net" ;-).

I agree with you that this may be a lot more suitable for people
_before_ they get the git sources, which is to say it may make
more sense not to include in core-git tarball but is made into a
patch to Pasky's introduction website.

Re: Git 1.0 Synopis (Draft v4)

[Ryan Anderson]

On Mon, Aug 15, 2005 at 12:17:46AM -0700, Junio C Hamano wrote:
> Ryan Anderson <ryan@michonline.com> writes:
> 
> > I guess this means, "I dunno, either place works for me."
> 
> I was hoping it means to "Oh, come to think of it, maybe I
> should send this to corbet@lwn.net" ;-).

I was waiting until you said, "Ok, 1.00 tomorrow morning"

> I agree with you that this may be a lot more suitable for people
> _before_ they get the git sources, which is to say it may make
> more sense not to include in core-git tarball but is made into a
> patch to Pasky's introduction website.

Good point.

It's already there (now that I found the site.)

-- 

Ryan Anderson
  sometimes Pug Majere

Re: Git 1.0 Synopis (Draft v4)

[Junio C Hamano]

Ryan Anderson <ryan@michonline.com> writes:

> I was waiting until you said, "Ok, 1.00 tomorrow morning"

Makes sense.  There would be some weeks until that happens I am
afraid.

Re: Git 1.0 Synopis (Draft v4)

[Daniel Barkalow]

On Mon, 15 Aug 2005, Junio C Hamano wrote:

> Ryan Anderson <ryan@michonline.com> writes:
> 
> > I was waiting until you said, "Ok, 1.00 tomorrow morning"
> 
> Makes sense.  There would be some weeks until that happens I am
> afraid.

It might be worth putting the list of things left to do before 1.0 in the 
tree (since they clearly covary), and it would be useful to know what 
you're thinking of as preventing the release at any particular stage.

	-Daniel
*This .sig left intentionally blank*

Re: Git 1.0 Synopis (Draft v4)

[Junio C Hamano]

Daniel Barkalow <barkalow@iabervon.org> writes:

> It might be worth putting the list of things left to do before 1.0 in the 
> tree (since they clearly covary), and it would be useful to know what 
> you're thinking of as preventing the release at any particular stage.

Yeah, yeah.  Call me lazy.

Excerpts from my "last mile to 1.0", my Itchlist, and pieces from
random other messages since then.

- Documentation. [I really need help here --- among ~7000 lines
  there, I've written around 2500 lines, David Greaves another
  2500, and Linus 1400.  And it is not very easy to proofread
  what you wrote yourself.]

  - Are all the core commands described in Documentation/
    directory?

  - Many files under Documentation/ directory have become stale.
    I've tried to do one pass of full sweep recently [and
    another since I wrote the original "last mile" message], but
    I'd like somebody else to make another pass to make sure
    that the usage strings in programs, what the programs do,
    and what Documentation says they do match.  Also, the
    spelling and grammar fixes, which I am very bad at and have
    not done any attempt, needs to be done.

    Volunteers?

  - Are all the files in Documentation/ reachable from git(7)
    or otherwise made into a standalone document using asciidoc
    by the Makefile?  I haven't looked into documentation
    generation myself (I use only the text files as they are);
    help to update the Makefile by somebody handy with asciidoc
    suite is greatly appreciated here.

    Volunteers?

  - We may want to describe more Best Current Practices, along
    the lines of "Working with Others" section in the tutorial.
    Please write on your faviorite topic and send patches in
    ;-)) [ryan started collecting Documentation/howto which
    would greatly help in this area].

  - Glossary documentation Johannes Schindelin is working on.

    I think coming up with the concensus of terms would come
    fairly quickly on the list.  Updating docs to match the
    concensus may take some time.  Help is greatly appreciated.

  - Maybe doing another pass at tutorial.  Could somebody run
    (or preferably, find a friend who has never touched git and
    have her run) the tutorial examples from the beginning to
    the end, and find rooms of improvements?  Does the order of
    materials presented make sense?  Do we talk about things
    assuming that the user knows something else that we have not
    talked about?  Have we introduced better way of doing the
    same thing since the tutorial was written?

    I've done that once with the text that is currently in the
    head of the master branch, but that is getting rather stale,
    and also I did that myself so I am sure I've sidestepped
    pitfalls without even realizing.

The above does not have to be all there in 0.99.5, but I
consider that lack of any of the above to block 1.0.

- Commit walker downloading from packed repository is finally
  complete.  Thanks, Daniel!

- Teach fetch-pack reference renaming.

  On the push side, send-pack now knows updating arbitrary
  remote references from local references.  We need something
  similar for fetching [since then I outlined the design of the
  new shorthand file format and semantics but have not got
  around to actually do it.  Maybe on my next GIT day...].  This
  is scheduled for 0.99.5.

- commit template filler discussed with Pasky some time ago,
  with perhaps pre-commit and post-commit hooks.  Somehow the
  discussion died out but that does not mean _I_ forgot about
  it.

- Binary packaging.  Should _I_ worry about "/usr/bin/git" stay
  there myself --- I think not.  But I _do_ want to help Debian
  packaging folks if that path is causing problems in their
  effort to push git-core into the official Debian archive.

  As Linus mentioned earlier, this seems to be a Debian specific
  problem, and will not block 1.0 --- if Debian heavyweights do
  not want to stay compatible with the rest of the world, so be
  it.

- I have not heard from Darwin or BSD people for some time.  Is
  your portfile up to date?  Do you have updates you want me to
  include?  Have we introduced non-Linux non-GNU
  incompatibilities lately that you want to see fixed and/or
  worked around?

  Again, I consider binary packaging issue independent from our
  release schedule; it is a distribution local issue, so this
  would not block 1.0 in any way.  But I _am_ willing to help
  them.

- Oh, another itch I did not list in the previous message.  Is
  anybody interested in doing an Emacs VC back-end for GIT?

- git prune and git fsck-cache; think about their interactions
  with an object database that borrows from another.  This
  includes the case where .git/objects itself is symlinked to
  somewhere else (i.e. running "git prune" that somewhere else
  without consulting this repository would lose objects), and
  alternates pointing at somewhere else (i.e. ditto).

  My personal feeling is that we should just warn users about
  doing .git/objects symlinking and/or alternates pointing ---
  do not do it unless you have an off-line arrangement with the
  owner of the repository you are borrowing from.  Even if that
  would become our official position to take, it needs to be
  documented clearly before we declare this issue to have been
  "dealt with".

I am sure I am forgetting something, but the above would be a
good start.

Re: Git 1.0 Synopis (Draft v4)

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 978 bytes --]

Hi,

On Tue, 16 Aug 2005, Junio C Hamano wrote:

>   - Glossary documentation Johannes Schindelin is working on.

Yeah, yeah. Call _me_ lazy :-) I'll try to come up with a discussable item 
today.

> - git prune and git fsck-cache; think about their interactions
>   with an object database that borrows from another.  This
>   includes the case where .git/objects itself is symlinked to
>   somewhere else (i.e. running "git prune" that somewhere else
>   without consulting this repository would lose objects), and
>   alternates pointing at somewhere else (i.e. ditto).

I don´t see how git could help in the case you are pruning a repository 
which another repository points to. After all, the first repository 
doesn´t know about being used by the second.

> I am sure I am forgetting something, but the above would be a
> good start.

Maybe your $GIT_DIR/remotes idea? Along with a "--store <remotename>" flag 
to git-pull-script?

Ciao,
Dscho

Re: Git 1.0 Synopis (Draft v4)

[Dongsheng Song]

Hi,

Is there any guide or advise for deploy git server ? 

How do I set repository permissions correctly?

cauchy

about git server & permissions

[Dongsheng Song]

Hi,

Is there any guide or advise for deploy git server ? Especially
http/https/ssh server.

How do I set repository permissions correctly?

cauchy

Re: Git 1.0 Synopis (Draft v4)

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1072 bytes --]

Hi,

On Tue, 16 Aug 2005, Junio C Hamano wrote:

>   - Are all the files in Documentation/ reachable from git(7)
>     or otherwise made into a standalone document using asciidoc
>     by the Makefile?  I haven't looked into documentation
>     generation myself (I use only the text files as they are);
>     help to update the Makefile by somebody handy with asciidoc
>     suite is greatly appreciated here.
> 
>     Volunteers?

The attached script reveals:

git-unpack-objects.txt is not reachable from git.txt
git-cvsimport-script.txt is not reachable from git.txt
git-send-email-script.txt is not reachable from git.txt
git-rename-script.txt is not reachable from git.txt
tutorial.txt is not reachable from git.txt
git-show-index.txt is not reachable from git.txt
cvs-migration.txt is not reachable from git.txt
diffcore.txt is not reachable from git.txt
git-ls-remote-script.txt is not reachable from git.txt
git-apply.txt is not reachable from git.txt
git-diff-stages.txt is not reachable from git.txt
pack-protocol.txt is not reachable from git.txt

Ciao,
Dscho

[-- Attachment #2: Type: APPLICATION/x-perl, Size: 1215 bytes --]

Re: Git 1.0 Synopis (Draft v4)

[Daniel Barkalow]

On Tue, 16 Aug 2005, Johannes Schindelin wrote:

> Hi,
>
> On Tue, 16 Aug 2005, Junio C Hamano wrote:
>
> >   - Are all the files in Documentation/ reachable from git(7)
> >     or otherwise made into a standalone document using asciidoc
> >     by the Makefile?  I haven't looked into documentation
> >     generation myself (I use only the text files as they are);
> >     help to update the Makefile by somebody handy with asciidoc
> >     suite is greatly appreciated here.
> >
> >     Volunteers?
>
> The attached script reveals:
>
> git-unpack-objects.txt is not reachable from git.txt
> git-cvsimport-script.txt is not reachable from git.txt
> git-send-email-script.txt is not reachable from git.txt
> git-rename-script.txt is not reachable from git.txt
> tutorial.txt is not reachable from git.txt
> git-show-index.txt is not reachable from git.txt
> cvs-migration.txt is not reachable from git.txt
> diffcore.txt is not reachable from git.txt
> git-ls-remote-script.txt is not reachable from git.txt
> git-apply.txt is not reachable from git.txt
> git-diff-stages.txt is not reachable from git.txt
> pack-protocol.txt is not reachable from git.txt

The ones that don't start with git probably don't belong in the same set;
perhaps there should be a "technical" (or something similar but shorter)
subdirectory for developer documentation instead of user documentation?
(And tutorial and cvs-migration can move to howto)

	-Daniel
*This .sig left intentionally blank*

Re: Git 1.0 Synopis (Draft v4)

[Daniel Barkalow]

On Tue, 16 Aug 2005, Junio C Hamano wrote:

> Daniel Barkalow <barkalow@iabervon.org> writes:
>
> > It might be worth putting the list of things left to do before 1.0 in the
> > tree (since they clearly covary), and it would be useful to know what
> > you're thinking of as preventing the release at any particular stage.
>
> Yeah, yeah.  Call me lazy.
>
> Excerpts from my "last mile to 1.0", my Itchlist, and pieces from
> random other messages since then.
>
> - Documentation. [I really need help here --- among ~7000 lines
>   there, I've written around 2500 lines, David Greaves another
>   2500, and Linus 1400.  And it is not very easy to proofread
>   what you wrote yourself.]

I'm not sure how done this can actually get before some sort of feature
freeze; the best ways to do things keeps changing as more convenient ways
are added. Once the new stuff is diverted to post-1.0, I'd be interested
in going through it.

> - git prune and git fsck-cache; think about their interactions
>   with an object database that borrows from another.  This
>   includes the case where .git/objects itself is symlinked to
>   somewhere else (i.e. running "git prune" that somewhere else
>   without consulting this repository would lose objects), and
>   alternates pointing at somewhere else (i.e. ditto).

It should be fine, but only if .git/refs is symlinked to the matching
place; this gives you the same repository with multiple working trees.
Having refs/ and objects/ directories that aren't always together would be
much less safe.

	-Daniel
*This .sig left intentionally blank*

Re: Git 1.0 Synopis (Draft v4)

[Horst von Brand]

Junio C Hamano <junkio@cox.net> wrote:

[...]

> - Oh, another itch I did not list in the previous message.  Is
>   anybody interested in doing an Emacs VC back-end for GIT?

And teach make(1) about checking out files from git... or just create a
co(1) command for git.
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: Git 1.0 Synopis (Draft v4)

[Johannes Schindelin]

Hi,

On Tue, 16 Aug 2005, Horst von Brand wrote:

> And teach make(1) about checking out files from git... or just create a
> co(1) command for git.

How about "git-checkout-script", optionally with the "-f" flag to ignore 
changes since the last checkout/checkin?

Ciao,
Dscho

Re: Git 1.0 Synopis (Draft v4)

[Matthias Urlichs]

Hi, Horst von Brand wrote:

> And teach make(1) about checking out files from git... or just create a
> co(1) command for git.

Ummm... why?

make's SCCS support depends on the presence of a SCCS/s.<name> file
for each <name>. We don't have that. Teaching make about git would be
equivalent to teaching it about parsing the index file.

Technically, that would require a stable libgit.so or so.
In reality, however, I don't know when I last had a tree which wasn't
fully populated, but it's been a while, and it's something that can be
readily fixed by "git-checkout-cache -a".

-- 
Matthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  smurf@smurf.noris.de
Disclaimer: The quote was selected randomly. Really. | http://smurf.noris.de
 - -
One possible reason that things aren't going according to plan
is that there never was a plan in the first place.