[PATCH] git-checkout(1) mention fate of extraneous files

Signed-off-by: jidanni <redacted>
---
 Documentation/git-checkout.txt |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9cd5151..bce31c7 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -14,12 +14,13 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-When <paths> are not given, this command switches branches by
-updating the index and working tree to reflect the specified
-branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
-be created; in this case you can use the --track or --no-track
-options, which will be passed to `git branch`.
+When <paths> are not given, this command switches branches by updating
+the index and working tree to reflect the specified branch, <branch>,
+and updating HEAD to be <branch> or, if specified, <new_branch>. (No
+extraneous files present are deleted, use linkgit:git-clean[1] for a
+pristine checkout.) Using -b will cause <new_branch> to be created; in
+this case you can use the --track or --no-track options, which will be
+passed to `git branch`.
 
 As a convenience, --track will default to create a branch whose
 name is constructed from the specified branch name by stripping

-- 
1.6.0.6

jidanni@jidanni.org, 17.01.2009:

Signed-off-by: jidanni <redacted>
---
 Documentation/git-checkout.txt |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

-When <paths> are not given, this command switches branches by
-updating the index and working tree to reflect the specified
-branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
-be created; in this case you can use the --track or --no-track
-options, which will be passed to `git branch`.
+When <paths> are not given, this command switches branches by updating
+the index and working tree to reflect the specified branch, <branch>,
+and updating HEAD to be <branch> or, if specified, <new_branch>. (No
+extraneous files present are deleted, use linkgit:git-clean[1] for a
+pristine checkout.) Using -b will cause <new_branch> to be created; in
+this case you can use the --track or --no-track options, which will be
+passed to `git branch`.

Why do you reformat the whole paragraph? Just inserting your sentence
would give a much nicer diff for easier review, it's no difference for
asciidoc. Indeed to find the change, I just copied the old and new text
into two Vim windows, reformatted and diffed them.

Then you would get this

  Documentation/git-checkout.txt |   2 ++
  1 files changed, 2 insertions(+), 0 deletions(-)

Markus

MH> Why do you reformat the whole paragraph?

OK, glad to know that I don't need to!!

Signed-off-by: jidanni <redacted>
---
 Documentation/git-checkout.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9cd5151..58abdc6 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -17,7 +17,8 @@ DESCRIPTION
 When <paths> are not given, this command switches branches by
 updating the index and working tree to reflect the specified
 branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
+specified, <new_branch>. (No files are deleted, use linkgit:git-clean[1]
+for a pristine checkout.) Using -b will cause <new_branch> to
 be created; in this case you can use the --track or --no-track
 options, which will be passed to `git branch`.
 

-- 
1.6.0.6

-specified, <new_branch>.  Using -b will cause <new_branch> to
+specified, <new_branch>. (No files are deleted, use linkgit:git-clean[1]
+for a pristine checkout.) Using -b will cause <new_branch> to

The parenthetical remark is not true, here:
$ git status
# On branch anagrams
nothing to commit (working directory clean)
$ ls
anagram  fsdupfind
$ git checkout master
Switched to branch "master"
$ ls
fsdupfind

I think you mean "No untracked content is removed,...".
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/     

Signed-off-by: jidanni <redacted>
---
Thanks Boyd.
 Documentation/git-checkout.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9cd5151..56e1ec9 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -17,7 +17,8 @@ DESCRIPTION
 When <paths> are not given, this command switches branches by
 updating the index and working tree to reflect the specified
 branch, <branch>, and updating HEAD to be <branch> or, if
-specified, <new_branch>.  Using -b will cause <new_branch> to
+specified, <new_branch>. (To also delete untracked content
+use linkgit:git-clean[1].) Using -b will cause <new_branch> to
 be created; in this case you can use the --track or --no-track
 options, which will be passed to `git branch`.
 

-- 
1.6.0.6

Hi,

On Mon, 19 Jan 2009, Boyd Stephen Smith Jr. wrote:

I think you mean "No untracked content is removed,...".

As "checkout" is about switching branches, and as Git is very keen on 
avoiding loss of uncommitted changes, I think this comment is utterly 
unnecessary.  Indeed, it is rather annoying: when I read a document the 
other day, that I _had_ to read, and which was full of obvious statements, 
sure enough, I missed the single important half-sentence.

IOW do not clutter the man page with distracting stuff, please, please, 
please.

Ciao,
Dscho

Signed-off-by: jidanni <redacted>
---
OK thanks Johannes.
I'm still worried that there is no exact statement on the fate of the
various different classes of files, but OK, moving this to only a SEE ALSO.

 Documentation/git-checkout.txt |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9cd5151..6ffb783 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt

@@ -246,6 +246,9 @@ $ edit frotz
 $ git add frotz
 ------------
 
+SEE ALSO
+--------
+linkgit:git-clean[1]
 
 Author
 ------

-- 
1.6.0.6

Hi,

On Tue, 20 Jan 2009, jidanni@jidanni.org wrote:

Signed-off-by: jidanni <redacted>
---
OK thanks Johannes.
I'm still worried that there is no exact statement on the fate of the
various different classes of files, but OK, moving this to only a SEE ALSO.

You completely misread me.  So I will say it out directly: I think no 
patch is needed.

Hth,
Dscho

On Monday 19 January 2009, Johannes Schindelin [off-list ref] 
wrote about 'Re: [PATCH,v4] git-checkout(1): mention fate of extraneous 
files':

On Tue, 20 Jan 2009, jidanni@jidanni.org wrote:

quoted

Signed-off-by: jidanni <redacted>
---
OK thanks Johannes.
I'm still worried that there is no exact statement on the fate of the
various different classes of files, but OK, moving this to only a SEE
ALSO.

You completely misread me.  So I will say it out directly: I think no
patch is needed.

I think some users will expect to get a clean checkout when simply 
doing "git checkout <branch>".  It would be nice for the documentation 
mention that is not the case, and reference the tool that helps get the 
tree into that state.  Just my opinion, though.

It seems natural to me for this to be mentioned in the 'git checkout' 
documentation.  Perhaps there's a better place?
-- 
Boyd Stephen Smith Jr.                     ,= ,-_-. =. 
bss@iguanasuicide.net                     ((_/)o o(\_))
ICQ: 514984 YM/AIM: DaTwinkDaddy           `-'(. .)`-' 
http://iguanasuicide.net/                      \_/