Deprecation/Removal schedule

We seem to have accumulated some crufts, duplicated and/or disused features. I think we should start planning deprecation and removal.

Here are potential candidates we might want to mark as "scheduled for removal". Note that I threw in a bit more than what I seriously consider bloat, so your favorite may appear in the list.

* git-applymbox and git-applypatch

  Does anybody rely on them?  I think new users are all using
  git-am (this is just what _I_ think -- please consider this
  message as a poll to voice your objection).

* git-whatchanged

  This has been identical to git-log with different default
  options.

* git-p4import, git-quiltimport and contrib/gitview

  These have seen almost no activity since their appearance.  It
  could be that they are already perfect and many people are
  using them happily, but I find it a bit hard to believe.

* git-diff-stages

  Judging from the fact that nobody complained what it does is
  not accessible from "git diff" wrapper, I suspect nobody is
  interested in comparing the stages while merging (I certainly
  do not use it myself).

* git-lost-found

  Although it has served us well, I think it is about to outlive
  its usefulness, thanks to the recent "reflog by default"
  change.

* git-local-fetch, git-ssh-fetch and git-ssh-upload

  In-tree git-fetch does not use these commit walkers as the
  backend.  They might be used by Cogito and people's scripts so
  I am not seriously pushing for their removal.  http-fetch is
  here to stay so it's not like removing them would reduce the
  burden to maintain the commit walkers anyway.

* contrib/colordiff

  This has long outlived its usefulness.

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

I'm OK with everything on the list going away. But that's because I don't ever use them. :)

I'd think we also want to remove the following older aliases:

  annotate
  init-db
  fsck-objects
  repo-config

1 year after 1.5.0 final ships. That should give people a chance to upgrade their other tools (StGit, qgit, etc.).

Junio C Hamano wrote:

If I remember correctly there are here because Linus is used to their interface and prefers git-applymbox to git-am. I'm not sure for example if git-am --interactive is on the par of git-applymbox -q option (BTW. if we remove git-applymbox, we would have to remove reference to it in git-am(1): "--interactive: Run interactively, just like git-applymbox"). git-am also lack all git-applymbox signoff options.

I agree. Perhaps we should add in the documentation of git-log, or/and in documentation of git-config, an example of "whatchanged" alias...

I agree with removal of gitview; I'd rather leave importers, even if they haven's seen any activity. If they import correctly, what is to work on more?

I think you can always use "git diff <stage1>:<file> <stage2>:<file>". I'm not sure if it is useful or not (perhaps it is not advertised).

I agree. If it is needed, perhaps this functionality should be made as an option to git-fsck.

I agree.

Jakub Narebski wrote:

An alternative for importers would be to move them into contrib area (I think unmaintained but not obsolete programs can be there in contrib).

Jakub Narebski <jnareb@gmail.com> wrote:

Sure, but we don't want to promote carrying around unmaintained programs in core Git. Its additional code which must still be tested or fixed when changes get made, like the final removal of the fsck-objects alias. Hence, its never really unmaintained... someone must do the work.

Having a maintainer means there are one or more persons in the community who are making sure that chunk of code stays current when changes are made, and bugs are being fixed when identified. It also implies the code has some use, as it is unreasonable to expect a maintainer to invest time in something which has no value.

Things that are really central in Git have at least 3 or 4 maintainers who seem to rotate the workload fairly well. But as you get closer to the outer (higher) layers it seems to fall on Junio and a much smaller group. I'd hate to see Junio spend lots of time working on things nobody uses.

Importers are especially problematic. They aren't the most heavily used programs, as people tend to convert to Git once and then don't look back. But they are also one of the first things a user has experience with as they testdrive Git on a copy of their own project. So any importers we ship `out of the box' need to Just Work Danngit(tm). Unfortunately they are also get the least amount of testing.

On 2/5/07, Jakub Narebski <jnareb@gmail.com> wrote:

I have reflog off by default (and never missed it yet), so leave it at least as option to git-fsck, please. Besides, how do you find lost objects which were not mentioned in any reflog? (because of a bug someone made in reflog code, for example)

Alex Riesen <raa.lkml@gmail.com> wrote:

Learn to love reflog.  :-)

I use it daily. Mainly `git log origin/master@{1}..origin/master` to see what has come in from Junio since my last fetch. The @{n} syntax has (for me) been one of its best features. (Thanks Junio!)

Repeat after me:

  There aren't any bugs in the reflog code.
  They have not been any bugs in the reflog code.
  There will never be any bugs in the reflog code.

I don't think we've had a case where a commit wasn't recorded in a reflog when it should have been. Perhaps *very* early in reflog development a couple of commands bypassed the reflog code, but that has certainly since been fixed. The last one was git-receive-pack, which we finished in early December.

If the reflog code did fail to record something, and you needed it, and you hadn't git-prune'd yet, git-fsck would list the dangling commit. And a copy-n-paste session with `git-log -p D --not --all` in another xterm would help you navigate what the dangling commits were.

On 2/5/07, Shawn O. Pearce <spearce@spearce.org> wrote:

It looks and smells like a useful feature. I just haven't found any use for it yet. Besides all the good, it's another part of a repo needing maintenance (constantly growing thing, like /var/log).

Yes, of course. I somehow missed it. Shows how often one does git-fsck in cygwin, doesn't it?

Alex Riesen <raa.lkml@gmail.com> wrote:

`git gc` is your friend. It automatically trims the reflogs, keeping only the last 90 days worth of entries. You can tune this with the `gc.reflogexpire` configuration parameter. Seeing as how `git gc` also invokes `git repack -a -d`, `git pack-refs --prune`, etc., one would have to wonder why use anything else.

So its not a constantly growing thing; you can at least bound it
by time.
 

:-)

Actually I have need for git-fsck too often on Cygwin; one of my coworkers looses objects all of the time in his repository. I think his harddrive is failed. The zlib CRC checking we put into pack-objects saved his bacon when it failed to repack his repository with corrupt objects.

On 2/5/07, Shawn O. Pearce <spearce@spearce.org> wrote:

git gc (repack -d of it) is too dangerous in a shared repo: it breaks the repos which depend on the master repository, have sent (by some means) some objects over to the master, and accidentally removed the reference, and were pruned afterwards. I'm not saying git gc is bad, I'm just saying you can't use it whenever and wherever you want. Sometimes you'd prefer to only expire logs, only pack refs or only repack. And if I have no logs, I can't forget to trim them.

No, I can't. git gc and reflog --expire can. I have to call them. And I don't think trimming the logs automatically is a good idea: 90 days of commits can be a very long file on a busy repository. Add to that slow disks and stupid OS (the worst case, which matters), and you get a very annoyed user (if he was just angry before, having to use the drive and OS, he'll definitely go berserk now).

Never had that, can be hardware problem.

What I meant is that it takes too long and I just avoid running fsck unless I am forced to.

Hi,

On Tue, 6 Feb 2007, Alex Riesen wrote:

We no longer call git-prune automatically in git-gc. You have to say "git-gc --prune" to trigger that behaviour.

Happy?

Ciao, Dscho

On Tue, Feb 06, 2007 at 11:45:24AM +0100, Johannes Schindelin wrote:

repack -d can lose objects, too:

# fully packed test repo with 2 commits mkdir repo && cd repo git init touch foo git add foo git commit -m foo echo bar >foo git commit -a -m bar git repack -a -d

# remember the latest commit commit=`git rev-parse HEAD`

# now make it dangling git reset --hard HEAD^ sleep 1 git reflog expire --expire=0 HEAD refs/heads/master

# now repack git repack -a -d

# and it's gone git-show $commit

-Peff

Hi,

On Tue, 6 Feb 2007, Jeff King wrote:

This is the culprit.

The solution is very easy: do not --reference a repository which resets or deletes branches. IMHO this is all too obvious.

Ciao, Dscho

On 2/6/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Or just do no repack in the referenced repo.

Anyway, the discussion outlived its usefulness. I have what I wanted (git fsck --unreachable), and nobody can force me to repack my shared repo, so the issue does not exist for the original poster.

Hi,

On Tue, 6 Feb 2007, Alex Riesen wrote:

That is not the solution.

The error in your setup is to _rely_ on data which just _might go away_!

IOW do _not_ use an unreliable repository for --reference!

Well, I think unless you understand that you do something really fragile, the discussion did not yet outlive its usefulness.

Ciao, Dscho

On 2/6/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

The data cannot "just" go away. I'll have to "go the data away" manually.

Well, that being an accident, I see no way to follow your advice.

Yes, preacher.

On 2/6/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

no. You'd have to stop calling repack as well.

I mean the objects that generally have to be removed and just accidentally was not pinned in the shared repo. Or did you mean that repack will leave unreferenced objects behind in objects/??/files?

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

My fingers still type `whatchanged', but I can train them. Besides, it could easily be done with an alias.

I may have a use for p4import, if the company I work for switches to Perforce. If it doesn't work, I'll probably end up fixing it or replacing it with something based on Shawn's fastimport, but either way I'm not sure it's dead yet.

-- [mdw]

Hi,

On Sun, 4 Feb 2007, Junio C Hamano wrote:

Would it really be so bad if we just kept this alias indefinitely? We can stop advertising it, but it is not expensive to carry that small part of the code around.

Same goes for repo-config, fsck-objects, init-db.

Ciao, Dscho

On 2/5/07, Junio C Hamano <junkio@cox.net> wrote:

Why not leave the importers as examples? They could be useful to someone.

On Sun, 4 Feb 2007, Junio C Hamano wrote:

Somebody should at least document the differences before it's depracated.

I think git-whatchanged ends up being equivalent to

	git log --full-history --raw -r

but I didn't really check if there's something else.

Same goes for "git-am". I use "git-applymbox", and I'll happily switch to git-am, but I'd like somebody who knows to document the differences when it gets deprecated. I use "git-applymbox -u", and I guess I just should change that to "git-am --utf8".

I think they're useful to keep around, if for no other reason than as starting points for others.

That said, I probably agree with your other examples:

Although the git-ssh-fetch thing might be useful if you try to fix a tree that got corrupted and is missing an object (the native git protocol won't help you, since it assumes both trees are complete, while the stupid object fetching can pick out individual missing objects, I think).

That said, I don't think anybody would really ever fix their trees that way. It's more likely that you'd just fetch the whole repo and add the missing objects that way (ie do a clone, copy the pack-file, and repack the resulting mess to get a nice clean and working repository again).

		Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

True; by the way, for "am", -u is the default these days by popular demand. I do not offhand remember if "applymbox" got corresponding changes (I think it did).

I strongly agree with the starting-points arguments. I was hoping to hear the list to form a consensus to move useful starting-point examples to contrib/.

If the series of patches you are applying via git-am was based in a different directory there was no way to strip the directory (as you would with git-apply).

This patch adds a --patchdepth option to git-am.sh whose argument is passed as a "-p" option to git-apply.

Signed-off-by: Andy Parkins <andyparkins@gmail.com>
---
I know git-apply isn't going anywhere, but git-applypatch is.  However, all
this talk of it made me remember this patch.

 git-am.sh |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)

Andy Parkins <andyparkins@gmail.com> wrote:

Is there something wrong with -p<n>? Looking at git-am, -p is not currently accepted as an option. Its universally considered the depth parameter to standard `patch`, which is why git-apply also accepts it over --patchdepth.

I'd rather see git-am use the same arguments (when possible) as git-apply.

Andy Parkins <andyparkins@gmail.com> writes:

I do not understand this remark, as applypatch does not have -p either. If we were to do this, I agree with others that this should simply be called -p (we do not have name crash with existing options, do we?).

I am not sure how useful applying a patch though git-am with -p would be. I can understand,

After seeing that a patch does not apply because the patch was generated at the wrong level, it would be very natural to use "git apply -p0 --index .dotest/patch" and then continue with "git am --resolved". So obviously, -p to git-apply is very useful, but -p given to "am" means all of the patches in your mailbox has uniformly wrong patch depth. I wonder how common would that be in practice.

But other than that "how useful would that be in practice?" issue, I do not think the patch is too bad, except one hunk:

This is wrong if you do not use any $patchdepth.

Junio C Hamano wrote:

[...]

Perhaps options should be -p as short version, and --patchdepth (or --strip as in GNU patch) as long version?

On Wednesday 2007 February 07 08:27, Junio C Hamano wrote:

Oh. That /would/ make it confusing. I didn't realise they both didn't have it (I thought I had used it at some point in the past, my swiss cheese memory). In that case, the patch is a lot more relevant.

I have no problem with it being "-p"; I just don't like to take valuable single letter namespace unilaterally.

I added it because I had need for it; I managed to manufacture a whole series of patches at the wrong patch level. It had been hard work to make them, so I didn't feel like making them all again just to change the depth.

Guilty. As I said, I added it for my own use; so didn't mind too much about weird output. If I resent it would be to drop my modifications to the message (it's redundant anyway - surely you know what you specified on the command line?), so feel free to just remove that hunk.

Andy

Junio C Hamano wrote:

Nonono. Please no. This has saved me more times than I can even care to remember. Especially whenever I'm teaching newcomers how to git. I really wouldn't want to not have it there in case its needed and some schmuck upgrades git and then loses something vital because he forgot to enable the reflog on an old repo.

Does it add significantly to the maintenance burden?

On 2/6/07, Andreas Ericsson <ae@op5.se> wrote:

It's functionality is superseded by "git fsck --unreachable", see this discussion.

Hi,

On Tue, 6 Feb 2007, Alex Riesen wrote:

AFAICT lost-and-found _connects_ the objects to files, and as such is easier to browse after running the command (which is expensive).

If you _have_ to lose lost-and-found, why not resurrect the functionality as an option to fsck?

Ciao, Dscho

The feature release after 1.5.0 will be 1.5.1; hopefully we can stick to 6-8 weeks schedule between feature releases, which makes it due sometime in April, assuming that 1.5.0 will be done in a week or so.

In 1.5.0, you will still see git-resolve and git-diff-stages, but they will be removed by 1.5.1.

We will keep the following for now, but not encourage use of them to new users. There isn't any definite removal schedule right now and we may not even need one.

	whatchanged (use "log --full-history --raw -r" instead)
	applymbox (use "am" instead)
	init-db (use "init")
	fsck-objects (use "fsck")
	repo-config (use "config")

When we created the contrib/ area, I said that anything there is subject to periodical review for removal if kept unused and unmaintained. But anything that satisfies the requirements of its small userbase will have happy users without exposing its shortcomings, so I suspect removal from contrib/ by periodic review would never happen in practice.

I've already removed contrib/colordiff and git-merge-recur.

Among the ones I mentioned in my initial message, the ones that are not mentioned in this message will stay as before.

Junio C Hamano wrote:

Well, it is not as if we cannot obtain equivalent of git-diff-stages without this command. Stages are <ours>, <theirs> and <ancestor> (git-merge-base <ours> <theirs>) so I think we can use git-diff-tree with appropriate arguments...

Hi,

Jakub wrote:

Not exactly. The stages are in the index. For example, when you have conflicts, the stages might not reflect _any_ tree at all! This is because _part_ of the changes could be merged, and _part_ of the changes conflict.

But it does not matter anyway. Good bye diff-stages!

Ciao, Dscho

Johannes Schindelin wrote:

Hmmm... I do wonder if git-diff-stages precedes introduction of combined diff format...

Jakub Narebski <jnareb@gmail.com> writes:

Well, sorry for wasting the bandwidth if it was not obvious from my message, but that's exactly why I am announcing officially that they *will* be removed with a definite timeframe.

Hi,

On Tue, 6 Feb 2007, Junio C Hamano wrote:

Thanks!

Ciao, Dscho