Re: diff/Checking out by date specification

[Jeff King <peff@peff.net>]

On Mon, Jun 30, 2008 at 12:24:03PM +1000, Toby Corkindale wrote:

> `man git-rev-parse` seems to indicate that one can look at the state of  
> the repository by date (absolute or relative), and use this for diff or  
> checkout, etc.
> It includes examples such as "{yesterday}" and "{1979-02-26 18:30:00}".

It's a little bit more complex than that. The branch@{time} syntax means
"what was in _my_ branch at that time". And if you just cloned, your
branch doesn't go back very far.

If you want to say "find commits that happened before time T", you want
--until or --since (or their aliases --before and --after).

Would the documentation patch below have helped with the confusion?

-- >8 --
doc/rev-parse: clarify reflog vs --until for specifying revisions

The rev-parse manpage introduces the branch@{date} syntax,
and mentions the reflog specifically. However, new users may
not be familiar with the distinction between the reflog and
the commit date, so let's help them out with a "you may be
interested in --until" pointer.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-rev-parse.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 9e273bc..59e95ad 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -184,7 +184,10 @@ blobs contained in a commit.
   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
   of the ref at a prior point in time.  This suffix may only be
   used immediately following a ref name and the ref must have an
-  existing log ($GIT_DIR/logs/<ref>).
+  existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
+  of your *local* ref at a given time; e.g., what was in your local
+  `master` branch last week. If you want to look at commits made during
+  certain times, see `--since` and `--until`.
 
 * A ref followed by the suffix '@' with an ordinal specification
   enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
-- 
1.5.6.1.202.g3a23.dirty