What exactly does 'needs update' mean?

  I've come to accept the term 'needs update' when I've forgotten to 
stash or commit before certain Git operations.  However, I got cornered 
today and was asked to explain what it means.  I had to admit I don't know.

What does "you can't do this operation without having a clean working tree and these are the modified files currently preventing the operation from proceeding" have to do with "needs update"?

Thanks.

Josh

Joshua Jensen <jjensen@workspacewhiz.com> writes:

It came from "you need to run update-index on that path, as you have local modification in the working tree".

  ----- Original Message -----
From: Junio C Hamano
Date: 9/25/2010 12:06 AM

Okay, your description makes sense to me, and I'll be able to explain what it means.

I did a Google search before I posted here. It turns out this phrase is *very* confusing to others. Casual Joes don't use the plumbing commands (which I assume git update-index is). Is there opposition to modernizing this turn to make it more clear based on the porcelain commands being run?

Thanks.

Josh

  ----- Original Message -----
From: Joshua Jensen
Date: 9/25/2010 8:16 AM

<sigh> Just waking up for the day.

Is there opposition to modernizing this *term* to make it more clear based on the porcelain commands being run?

-Josh

Hi Joshua,

Joshua Jensen writes:

Most porcelain commands already contain checks to specifically prevent it from displaying this message. See:

cache.h:506:#define REFRESH_IN_PORCELAIN 0x0020 /* user friendly output, not "needs update" */ git-add--interactive.perl:215: ;# ignore 'needs update' read-cache.c:1109: needs_update_fmt = (in_porcelain ? "M\t%s\n" : "%s: needs update\n"); builtin/add.c:190: refresh_index(&the_index, verbose ? REFRESH_IN_PORCELAIN : REFRESH_QUIET, builtin/commit.c:284: if (refresh_cache(refresh_flags | REFRESH_IN_PORCELAIN)) builtin/reset.c:326: quiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN); builtin/reset.c:377: quiet ? REFRESH_QUIET : REFRESH_IN_PORCELAIN); cache.h:506:#define REFRESH_IN_PORCELAIN 0x0020 /* user friendly output, not "needs update" */ read-cache.c:1104: int in_porcelain = (flags & REFRESH_IN_PORCELAIN);

The real problem is with the shell scripts that invoke `git update-index --refresh` without `-q` and forget to redirect output to /dev/null. The Git infrastructure thinks update-index is a non-porcelain: little does it know that update-index being run from a porcelain-level shell script.

Thank you for reporting this bug.

-- Ram

Ramkumar Ramachandra (2):
  sh-setup: Write a new require_clean_work_tree function
  Porcelain scripts: Rewrite cryptic "needs update" error message

 git-pull.sh                |    5 +----
 git-rebase--interactive.sh |   16 ++++------------
 git-rebase.sh              |   14 +-------------
 git-sh-setup.sh            |   23 +++++++++++++++++++++++
 4 files changed, 29 insertions(+), 29 deletions(-)

Write a new require_clean_work_tree function to error out when working tree contains unstaged changes or index contains uncommitted changes.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 git-sh-setup.sh |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)

Ramkumar Ramachandra <artagnon@gmail.com> writes:

I totally agree on the idea, and the implementation is OK. On the format of the message, you can try to make it more consistent with other error messages, like:

$ git merge branch
error: The following untracked working tree files would be overwritten by merge:
        one
	two
Please move or remove them before you can merge.

That would give stg like:

echo >&2 "error: The following files have unstaged changes:" git diff-files --name-status -r --ignore-submodules -- >&2 echo >&2 "Please commit or stash them to proceed."

(same for the second case)

Also, you probably want to give all the error before you "exit 1", hence stg like:

error=f
...
if
then
	...
	error=t
fi

if
then
	...
	error=t
fi

if [ "$error" = "t" ]; then
	exit 1
fi

Hi Matthieu,

Matthieu Moy writes:

Thanks for the review.

Ok, sounds good.

Hm, is that a good idea? We want the output to be functional and indicative: it should tell the user what to do immediately. I'm afraid that displaying both errors will make the output very verbose. We can just tell the user about the unstaged changes, and wait for them to commit or stash it. Either way, both commit and stash will affect the index by default :)

-- Ram

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Yes, but I find this very painfull when you

$ git do-something error: you need X before you can do-something $ do X $ git do-something error: Ah, you also need Y before you can do-something

A plain commit will get rid of staged changes, not of unstaged ones.

Your patch shows unstaged changes first. If the only problem was unstaged changes, then "git stash --keep-index" would be a good solution. As a user, I prefer knowing both problems to find the right solution (and avoid trying to solve only unstaged changes before noticing I need to solve the other one too).

Hi Matthieu,

Matthieu Moy writes:

Ah, yes. This would definitely be annoying.

Good point. I'll make the error messages a little more comprehensive and focused in the next iteration.

-- Ram

Although Git interally has the facility to differentiate between porcelain and plubmbing commands and appropriately print errors, several shell scripts invoke plubming commands triggering cryptic plumbing errors to be displayed on a porcelain interface. This patch replaces the "needs update" message in git-pull and git-rebase, when `git update-index` is run, with a more friendly message.

Reported-by: Joshua Jensen <jjensen@workspacewhiz.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 git-pull.sh                |    5 +----
 git-rebase--interactive.sh |   16 ++++------------
 git-rebase.sh              |   14 +-------------
 3 files changed, 6 insertions(+), 29 deletions(-)

Ramkumar Ramachandra <artagnon@gmail.com> writes:

That will make a duplicate "commit or stash your changes" message.

Otherwise, the patch seems OK.