* [PATCH 1/7] Documentation: minor edits of git-lost-found manpage
[not found] <11766982362087-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
[not found] ` <11766982361830-git-send-email->
1 sibling, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@pad.(none)>
Minor improvements to grammar and clarity of lost-found manpage.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/git-lost-found.txt | 23 +++++++++++------------
1 files changed, 11 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt
index f52a9d7..e48607f 100644
--- a/Documentation/git-lost-found.txt
+++ b/Documentation/git-lost-found.txt
@@ -12,23 +12,22 @@ SYNOPSIS
DESCRIPTION
-----------
Finds dangling commits and tags from the object database, and
-creates refs to them in .git/lost-found/ directory. Commits and
-tags that dereference to commits go to .git/lost-found/commit
-and others are stored in .git/lost-found/other directory.
+creates refs to them in the .git/lost-found/ directory. Commits and
+tags that dereference to commits are stored in .git/lost-found/commit,
+and other objects are stored in .git/lost-found/other.
OUTPUT
------
-One line description from the commit and tag found along with
-their object name are printed on the standard output.
-
+Prints to standard output the object names and one-line descriptions
+of any commits or tags found.
EXAMPLE
-------
-Suppose you run 'git tag -f' and mistyped the tag to overwrite.
+Suppose you run 'git tag -f' and mistype the tag to overwrite.
The ref to your tag is overwritten, but until you run 'git
-prune', it is still there.
+prune', the tag itself is still there.
------------
$ git lost-found
@@ -36,15 +35,15 @@ $ git lost-found
...
------------
-Also you can use gitk to browse how they relate to each other
-and existing (probably old) tags.
+Also you can use gitk to browse how any tags found relate to each
+other.
------------
$ gitk $(cd .git/lost-found/commit && echo ??*)
------------
-After making sure that it is the object you are looking for, you
-can reconnect it to your regular .git/refs hierarchy.
+After making sure you know which the object is the tag you are looking
+for, you can reconnect it to your regular .git/refs hierarchy.
------------
$ git cat-file -t 1ef2b196
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 2/7] Documentation: clarify git-checkout -f, minor editing
[not found] ` <11766982361830-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
2007-04-16 5:13 ` Junio C Hamano
[not found] ` <1176698236722-git-send-email->
1 sibling, 1 reply; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@pad.(none)>
"Force a re-read of everything" doesn't mean much to me.
Also some minor grammar fixes.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/git-checkout.txt | 9 +++++----
1 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index f5b2d50..2ead493 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -23,9 +23,9 @@ options, which will be passed to `git branch`.
When <paths> are given, this command does *not* switch
branches. It updates the named paths in the working tree from
-the index file (i.e. it runs `git-checkout-index -f -u`), or a
-named commit. In
-this case, `-f` and `-b` options are meaningless and giving
+the index file (i.e. it runs `git-checkout-index -f -u`), or
+from a named commit. In
+this case, the `-f` and `-b` options are meaningless and giving
either of them results in an error. <tree-ish> argument can be
used to specify a specific tree-ish (i.e. commit, tag or tree)
to update the index for the given paths before updating the
@@ -38,7 +38,8 @@ OPTIONS
Quiet, supress feedback messages.
-f::
- Force a re-read of everything.
+ Proceed even if the index or the working tree differs
+ from HEAD.
-b::
Create a new branch named <new_branch> and start it at
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 3/7] Documentation: clarify track/no-track option.
[not found] ` <1176698236722-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
[not found] ` <11766982363767-git-send-email->
1 sibling, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@pad.(none)>
Fix the description of the --no-track option so it no longer says the
opposite of what was intended. Also mention branch.autosetupmerge
explicitly.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/git-checkout.txt | 12 ++++++++----
1 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 2ead493..337b3d5 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -49,13 +49,17 @@ OPTIONS
--track::
When -b is given and a branch is created off a remote branch,
- setup so that git-pull will automatically retrieve data from
- the remote branch.
+ set up configuration so that git-pull will automatically
+ retrieve data from the remote branch. Set the
+ branch.autosetupmerge configuration variable to true if you
+ want git-checkout and git-branch to always behave as if
+ '--track' were given.
--no-track::
When -b is given and a branch is created off a remote branch,
- force that git-pull will automatically retrieve data from
- the remote branch independent of the configuration settings.
+ set up configuration so that git-pull will not retrieve data
+ from the remote branch, ignoring the branch.autosetupmerge
+ configuration variable.
-l::
Create the new branch's ref log. This activates recording of
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 4/7] user-manual: fix discussion of default clone
[not found] ` <11766982363767-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
[not found] ` <11766982363276-git-send-email->
1 sibling, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@citi.umich.edu>
The name "master" isn't actually quite so special. Also, fix some bad
grammar.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/user-manual.txt | 6 +++---
1 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index d43d237..49e936f 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -298,9 +298,9 @@ $ git branch
* master
------------------------------------------------
-A freshly cloned repository contains a single branch head, named
-"master", and working directory is initialized to the state of
-the project referred to by "master".
+A freshly cloned repository contains a single branch head, by default
+named "master", with the working directory initialized to the state of
+the project referred to by that branch head.
Most projects also use <<def_tag,tags>>. Tags, like heads, are
references into the project's history, and can be listed using the
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 5/7] user-manual: detached HEAD
[not found] ` <11766982363276-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
[not found] ` <11766982362066-git-send-email->
1 sibling, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@citi.umich.edu>
Add a brief mention of detached HEADs and .git/HEAD.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/user-manual.txt | 44 +++++++++++++++++++++++++++++++++++++++-
1 files changed, 42 insertions(+), 2 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 49e936f..bff072f 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -495,8 +495,48 @@ git checkout -b <new> <start-point>::
create a new branch <new> referencing <start-point>, and
check it out.
-It is also useful to know that the special symbol "HEAD" can always
-be used to refer to the current branch.
+The special symbol "HEAD" can always be used to refer to the current
+branch. In fact, git uses a file named "HEAD" in the .git directory to
+remember which branch is current:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+Examining an old version without creating a new branch
+------------------------------------------------------
+
+The git-checkout command normally expects a branch head, but will also
+accept an arbitrary commit; for example, you can check out the commit
+referenced by a tag:
+
+------------------------------------------------
+$ git checkout v2.6.17
+Note: moving to "v2.6.17" which isn't a local branch
+If you want to create a new branch from this checkout, you may do so
+(now or later) by using -b with the checkout command again. Example:
+ git checkout -b <new_branch_name>
+HEAD is now at 427abfa... Linux v2.6.17
+------------------------------------------------
+
+The HEAD then refers to the SHA1 of the commit instead of to a branch,
+and git branch shows that you are no longer on a branch:
+
+------------------------------------------------
+$ cat .git/HEAD
+427abfa28afedffadfca9dd8b067eb6d36bac53f
+git branch
+* (no branch)
+ master
+------------------------------------------------
+
+In this case we say that the HEAD is "detached".
+
+This can be an easy way to check out a particular version without having
+to make up a name for a new branch. However, keep in mind that when you
+switch away from the (for example, by checking out something else), you
+can lose track of what the HEAD used to point to.
Examining branches from a remote repository
-------------------------------------------
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 6/7] user-manual: start revising "internals" chapter
[not found] ` <11766982362066-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
[not found] ` <11766982362911-git-send-email->
1 sibling, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@citi.umich.edu>
Minor revisions, cross-references.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/user-manual.txt | 38 ++++++++++++++++++++------------------
1 files changed, 20 insertions(+), 18 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index bff072f..c32aaef 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2315,8 +2315,8 @@ options mentioned above.
Git internals
=============
-There are two object abstractions: the "object database", and the
-"current directory cache" aka "index".
+Git depends on two fundamental abstractions: the "object database", and
+the "current directory cache" aka "index".
The Object Database
-------------------
@@ -2331,22 +2331,23 @@ All objects have a statically determined "type" aka "tag", which is
determined at object creation time, and which identifies the format of
the object (i.e. how it is used, and how it can refer to other
objects). There are currently four different object types: "blob",
-"tree", "commit" and "tag".
+"tree", "commit", and "tag".
-A "blob" object cannot refer to any other object, and is, like the type
-implies, a pure storage object containing some user data. It is used to
-actually store the file data, i.e. a blob object is associated with some
-particular version of some file.
+A <<def_blob_object,"blob" object>> cannot refer to any other object,
+and is, as the name implies, a pure storage object containing some
+user data. It is used to actually store the file data, i.e. a blob
+object is associated with some particular version of some file.
-A "tree" object is an object that ties one or more "blob" objects into a
-directory structure. In addition, a tree object can refer to other tree
-objects, thus creating a directory hierarchy.
+A <<def_tree_object,"tree" object>> is an object that ties one or more
+"blob" objects into a directory structure. In addition, a tree object
+can refer to other tree objects, thus creating a directory hierarchy.
-A "commit" object ties such directory hierarchies together into
-a DAG of revisions - each "commit" is associated with exactly one tree
-(the directory hierarchy at the time of the commit). In addition, a
-"commit" refers to one or more "parent" commit objects that describe the
-history of how we arrived at that directory hierarchy.
+A <<def_commit_object,"commit" object>> ties such directory hierarchies
+together into a <<def_DAG,directed acyclic graph>> of revisions - each
+"commit" is associated with exactly one tree (the directory hierarchy at
+the time of the commit). In addition, a "commit" refers to one or more
+"parent" commit objects that describe the history of how we arrived at
+that directory hierarchy.
As a special case, a commit object with no parents is called the "root"
object, and is the point of an initial project commit. Each project
@@ -2356,9 +2357,10 @@ has two or more separate roots as its ultimate parents, that's probably
just going to confuse people. So aim for the notion of "one root object
per project", even if git itself does not enforce that.
-A "tag" object symbolically identifies and can be used to sign other
-objects. It contains the identifier and type of another object, a
-symbolic name (of course!) and, optionally, a signature.
+A <<def_tag_object,"tag" object>> symbolically identifies and can be
+used to sign other objects. It contains the identifier and type of
+another object, a symbolic name (of course!) and, optionally, a
+signature.
Regardless of object type, all objects share the following
characteristics: they are all deflated with zlib, and have a header
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 7/7] user-manual: use detached head when rewriting history
[not found] ` <11766982362911-git-send-email->
@ 2007-04-16 4:37 ` J. Bruce Fields
0 siblings, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-16 4:37 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, J. Bruce Fields
From: J. Bruce Fields <bfields@citi.umich.edu>
This is slightly simpler if we use a detached head. And it's probably
good to have another example that uses this feature.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/user-manual.txt | 15 ++++++++-------
1 files changed, 8 insertions(+), 7 deletions(-)
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index c32aaef..5c62516 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -504,6 +504,7 @@ $ cat .git/HEAD
ref: refs/heads/master
------------------------------------------------
+[[detached-head]]
Examining an old version without creating a new branch
------------------------------------------------------
@@ -2055,22 +2056,22 @@ $ git tag bad mywork~5
(Either gitk or git-log may be useful for finding the commit.)
-Then check out a new branch at that commit, edit it, and rebase the rest of
-the series on top of it:
+Then check out that commit, edit it, and rebase the rest of the series
+on top of it (note that we could check out the commit on a temporary
+branch, but instead we're using a <<detached-head,detached head>>):
-------------------------------------------------
-$ git checkout -b TMP bad
+$ git checkout bad
$ # make changes here and update the index
$ git commit --amend
-$ git rebase --onto TMP bad mywork
+$ git rebase --onto HEAD bad mywork
-------------------------------------------------
-When you're done, you'll be left with mywork checked out, with the top patches
-on mywork reapplied on top of the modified commit you created in TMP. You can
+When you're done, you'll be left with mywork checked out, with the top
+patches on mywork reapplied on top of your modified commit. You can
then clean up with
-------------------------------------------------
-$ git branch -d TMP
$ git tag -d bad
-------------------------------------------------
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 2/7] Documentation: clarify git-checkout -f, minor editing
2007-04-16 4:37 ` [PATCH 2/7] Documentation: clarify git-checkout -f, minor editing J. Bruce Fields
@ 2007-04-16 5:13 ` Junio C Hamano
2007-04-17 13:58 ` J. Bruce Fields
0 siblings, 1 reply; 10+ messages in thread
From: Junio C Hamano @ 2007-04-16 5:13 UTC (permalink / raw)
To: J. Bruce Fields; +Cc: git
"J. Bruce Fields" <bfields@citi.umich.edu> writes:
> "Force a re-read of everything" doesn't mean much to me.
>
> @@ -38,7 +38,8 @@ OPTIONS
> Quiet, supress feedback messages.
>
> -f::
> - Force a re-read of everything.
> + Proceed even if the index or the working tree differs
> + from HEAD.
>
While this is definitely better, I think it still is not clear
why the command needs an option to proceed.
Not proceeding is about preventing local changes from getting
lost, and the option is a way to allow it to overwrite and lose
any local change.
Other than that, and your "From: " line (did you change your
config or switch machines?) on the first three commits, I find
all the changes very sensible.
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/7] Documentation: clarify git-checkout -f, minor editing
2007-04-16 5:13 ` Junio C Hamano
@ 2007-04-17 13:58 ` J. Bruce Fields
2007-04-17 13:59 ` [PATCH] git-commit.txt: better warning about -f option J. Bruce Fields
0 siblings, 1 reply; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-17 13:58 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
On Sun, Apr 15, 2007 at 10:13:08PM -0700, Junio C Hamano wrote:
> "J. Bruce Fields" <bfields@citi.umich.edu> writes:
>
> > "Force a re-read of everything" doesn't mean much to me.
> >
> > @@ -38,7 +38,8 @@ OPTIONS
> > Quiet, supress feedback messages.
> >
> > -f::
> > - Force a re-read of everything.
> > + Proceed even if the index or the working tree differs
> > + from HEAD.
> >
>
> While this is definitely better, I think it still is not clear
> why the command needs an option to proceed.
>
> Not proceeding is about preventing local changes from getting
> lost, and the option is a way to allow it to overwrite and lose
> any local change.
OK, I agree; does the patch in the following message look like an
improvement?
> Other than that, and your "From: " line (did you change your
> config or switch machines?)
Whoops, yes, I was sloppy about setting up a new laptop--apologies.
> on the first three commits, I find all the changes very sensible.
Thanks.--b.
^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH] git-commit.txt: better warning about -f option
2007-04-17 13:58 ` J. Bruce Fields
@ 2007-04-17 13:59 ` J. Bruce Fields
0 siblings, 0 replies; 10+ messages in thread
From: J. Bruce Fields @ 2007-04-17 13:59 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
Make sure the reader understands that -f may cause the loss of any local
changes.
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
Documentation/git-checkout.txt | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 337b3d5..7aa877f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -39,7 +39,7 @@ OPTIONS
-f::
Proceed even if the index or the working tree differs
- from HEAD.
+ from HEAD, possibly overwriting and losing any local changes.
-b::
Create a new branch named <new_branch> and start it at
--
1.5.1.1.98.gedb4f
^ permalink raw reply related [flat|nested] 10+ messages in thread
end of thread, other threads:[~2007-04-17 13:59 UTC | newest]
Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <11766982362087-git-send-email->
2007-04-16 4:37 ` [PATCH 1/7] Documentation: minor edits of git-lost-found manpage J. Bruce Fields
[not found] ` <11766982361830-git-send-email->
2007-04-16 4:37 ` [PATCH 2/7] Documentation: clarify git-checkout -f, minor editing J. Bruce Fields
2007-04-16 5:13 ` Junio C Hamano
2007-04-17 13:58 ` J. Bruce Fields
2007-04-17 13:59 ` [PATCH] git-commit.txt: better warning about -f option J. Bruce Fields
[not found] ` <1176698236722-git-send-email->
2007-04-16 4:37 ` [PATCH 3/7] Documentation: clarify track/no-track option J. Bruce Fields
[not found] ` <11766982363767-git-send-email->
2007-04-16 4:37 ` [PATCH 4/7] user-manual: fix discussion of default clone J. Bruce Fields
[not found] ` <11766982363276-git-send-email->
2007-04-16 4:37 ` [PATCH 5/7] user-manual: detached HEAD J. Bruce Fields
[not found] ` <11766982362066-git-send-email->
2007-04-16 4:37 ` [PATCH 6/7] user-manual: start revising "internals" chapter J. Bruce Fields
[not found] ` <11766982362911-git-send-email->
2007-04-16 4:37 ` [PATCH 7/7] user-manual: use detached head when rewriting history J. Bruce Fields
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).