It really is an important concept to grasp for people coming

from CVS. Even if it is briefly mentioned, it is not obvious

enough to sink in.
Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>

---
	On Wed, 6 Dec 2006, Werner LEMBERG wrote:
	> It took me a while to realize that a git repository, as soon as

	> you've cloned it, is *self-contained*, and that commiting to the

	> repository and synchronizing with a different git repository are

	> two completely different things (contrary to CVS).  This should

	> be pronounced more in the CVS->git guide.
 Documentation/cvs-migration.txt |    5 +++++

 1 files changed, 5 insertions(+), 0 deletions(-)
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 6812683..8e610c7 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -24,6 +24,11 @@ First, note some ways that git differs from CVS:

     single shared repository which people can synchronize with; see below

     for details.
+  * Since every working tree contains a repository, a commit will not

+    publish your changes; it will only create a revision. You have to

+    "push" your changes to a public repository to make them visible

+    to others.

+

 Importing a CVS archive

 -----------------------
--

1.4.4.1.g394ac-dirty

-

I think the goal is laudable, but IMO it would be better to shorten

the document rather adding more text.
here is my try
From 980a0ca1b274e1219c24c3138f95e42206c72875 Mon Sep 17 00:00:00 2001

From: Han-Wen Nienhuys <hanwen@lilypond.org>

Date: Wed, 6 Dec 2006 15:50:13 +0100

Subject: [PATCH] another try at  rephrasing cvs doc.
Signed-off-by: Han-Wen Nienhuys <hanwen@xs4all.nl>

---

 Documentation/cvs-migration.txt |   34 +++++++++++++++++++++++-----------

 1 files changed, 23 insertions(+), 11 deletions(-)
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 6812683..3270c57 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -6,24 +6,36 @@ this document is to put you on the road to recovery, by helping you

 convert an existing cvs repository to git, and by showing you how to use a

 git repository in a cvs-like fashion.
-Some basic familiarity with git is required.  This

-link:tutorial.html[tutorial introduction to git] should be sufficient.

-

-First, note some ways that git differs from CVS:

+Git differs from CVS:
   * Commits are atomic and project-wide, not per-file as in CVS.
-  * Offline work is supported: you can make multiple commits locally,

+  * Branching is fast and easy.

+

+  * GIT is a distributed version control system:

+    This has several consequences:

+

+    - Every working tree contains a repository with a full copy of the

+    project history.

+

+    - Offline work is supported: you can create revisions locally,

     then submit them when you're ready.
-  * Branching is fast and easy.

+    Hence, there is a difference between creating a revision

+    (the "commit" command) and submitting it (the "push" command).

+

+    - No repository is inherently more important than

+    any other.

+

+    Of course, a project may still designate one central repository as

+    the True Master that contributors synchronize with.

+

+    See below for details.

 ...
[ message continues ]

I'd rather leave that introduction as it is--just as a section that

advertises the git features without trying to explain much.  And I'd

rather not mention push until we have a chance to explain how to use it.
--b.

-

Hi,
You talk like you'd have an eternity to explain Git. But that is not true.

A developer, especially those whom Git is forced upon, have an attention

span shorter than their pub1c hair.
I _know_ that _I_ did not read the whole document about "Branching and

merging in Git".
Ciao,

Dscho
-

Definitely, I agree.  So that argues for locating the most import stuff

as close to start of the document as possible.  But obviously there's

lot of important stuff and you can't do that with everything, so you

also have to rely on keeping things organized so people can more easily

skip to the middle.
The rest of the introduction is all git marketing: why you should like

using git instead of cvs.  So someone skimming for the quickest possible

"how do I make changes?" stuff may skip it entirely.
The thing that might help such a skimmer the most, actually, would be

a more helpful title for the section that actually does have what

they're looking for.  And making sure that particular section has the

right stuff.  How about something like this?
--b.
cvs-migration: improved section titles, better push/commit explanation
Rename the section titles to make the "how-to" content of the section

obvious.  Also clarify that changes have to be commited before they can

be pushed.
---
 cvs-migration.txt |   19 ++++++++++++-------

 1 file changed, 12 insertions(+), 7 deletions(-)
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 6812683..726b48d 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -76,8 +76,8 @@ variants of this model.

 With a small group, developers may just pull changes from each other's

 repositories without the need for a central maintainer.
-Emulating the CVS Development Model

------------------------------------

+Creating a Shared Repository

+----------------------------
 Start with an ordinary git working directory containing the project, and

 remove the checked-out files, keeping just the bare .git directory:

@@ -105,7 +105,10 @@ $ GIT_DIR=repo.git git repo-config core.

 Make sure committers have a umask of at most 027, so that the directories

 they create are writable and searchable by other group members.
-Suppose this repository is now set up in /pub/repo.git on the host

+...
[ message continues ]

Hm, but, come to think of it, I agree with you that the "how to commit

and push" really should come earlier, since that's the stuff most people

need to know; currently the order is roughly:
	importing a cvs archive

	creating a shared repository

	committing to a shared repository
We should start out with the assumption that a shared repo is already

set up and make it:
	committing to a shared repository

	creating a shared repository

	importing a cvs archive
which puts it in stuff-most-people-need-to-know to

stuff-less-people-need-to-know order.  Maybe the current introduction

should even be postponed to later.
And some day we should move that whole final CVS annotate section

elsewhere.
--b.

-

Yes, definitely!
I'm not complaining about changing to git, but Dscho's comment really

rings true:
 > A developer, especially those whom Git is forced upon, have an

 > attention span shorter than their pub1c hair.
I'm in the middle of exam period, I have a term papers to write, and I

have two weeks of lilypond bug reports and doc typos to process.  I

don't care if git can do branches really nicely or walk my dog or cure

cancer.  I can look at that stuff later -- right now I just want to fix

things and upload them.
Cheers,

- Graham

-

Yeah.  It's a tricky problem; different people need different things,

and to cover everything (and explain it correctly) the documentation

needs to be long; but to ensure that impatient people can get to what

they need quickly, there needs to be a short, clear path to their

particular need.
A few down-to-earth approaches that could help:
	- Clearer section/chapter titles, so we can generate tables of

	  contents where people can quickly find stuff--so, titles that

	  explain what the section will show you how to do with

	  minimized use of jargon that the user doesn't know yet ("how

	  to keep a repository up-to-date" as opposed to "git-fetch and

	  remotes").
	- As in "Everyday Git", think about what different groups of

	  users need.  But where possible, try to order documentation

	  with the stuff needed by the largest group of people first.

	  (For example, right now all the tutorials start with "git

	  init-db" and "git commit", assuming people are starting a

	  project from scratch, when the more typical usage is probably

	  someone joining an existing project, and possibly doing only

	  read-only stuff at first.)
	- Clearer ordering and dependencies, so when people find the "how

	  to resolve merges" section, they can quickly see what else

	  they'd need to read before that.  (And, yeah, I realize 99% of

	  the time they won't actually do that--they'll just dive right

	  in and try a few examples.  But at least they'll know where to

	  turn if that gets them in trouble....)
--b.

-

I agree that we should make that particular document shorter by

catering the immediate need of CVS migrant.  No need for git

marketting and showing off the power.
In that spirit, I think we can lose the section on 'annotate'

altogether now.  It was written in June 2005, way before

'annotate' and 'blame', both of which came in Feb 2006.
-

Modify cvs-migration.txt so it explains first how to develop against a

shared repository, then how to set up a shared repository, then how to

import a repository from cvs.  Though this seems chronologically

backwards, it's still readable in this order, and it puts the more

commonly needed material closer to the front.
Remove the annotate/pickaxe section; perhaps it can find a place elsewhere

in the future.  Remove most of the "why git is better than cvs" stuff from

the introduction.
Add some minor clarifications, including two that have come up several

times on the mailing list:
	1. Recommend committing any changes before running pull.

	2. Note that changes must be commited before they can be pushed.
Update the clone discussion to reflect the new --use-separate-remotes

default, and add a brief mention of git-cvsserver.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>

---

 Documentation/cvs-migration.txt |  349 ++++++++++++---------------------------

 1 files changed, 109 insertions(+), 240 deletions(-)
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 6812683..773fc99 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -1,113 +1,21 @@

 git for CVS users

 =================
-So you're a CVS user. That's OK, it's a treatable condition.  The job of

-this document is to put you on the road to recovery, by helping you

-convert an existing cvs repository to git, and by showing you how to use a

-git repository in a cvs-like fashion.

+Git differs from CVS in that every working tree contains a repository with

+a full copy of the project history, and no repository is inherently more

+important than any other.  However, you can emulate the CVS model by

+designating a single shared repository which people can synchronize with;

+this document explains how to do that.
 Some basic familiarity with git is required.  This

 link:tutorial.html[tutorial introduction to git] should be sufficient.
-...
[ message continues ]

Hi,
This is a laudable goal, and the order makes sense (put first that what

most people are interested in).
A few comments:
- just skimming the patch, I found "commiting" (needs another "t"), and

  "-bare" (needs another "-").
- It might make more sense to "git init-db --shared" and fetch the initial

  revision into it, rather than clone it and then fix. You might also want

  to mention that the "--shared" of -clone is different in meaning from

  that of -init-db (make just a footnote of it, to avoid intimidating

  readers).
- By far the easiest method to import from cvs is to go to a checked out

  _CVS_ working directory, and just say "git cvsimport".
Ciao,

Dscho
-

Thanks for the comments!  Patch, incremental against the previous one,
I do like the idea of anything that gets rid of the ugly find|xargs

chmod.  Result included below (untested).  Is that what you were
I'm ignoring this for now.  We can add it later if someone says they've

run into it.  (But honestly it's partly just laziness on my part--no

objection if you want to make the patch.)
It's too bad about that option-name conflict.  It'd be nice just to be

able to do the whole thing with one clone commandline.  And it'd also

make sense to allow clone and init-db to share commandline options where
Neat, I didn't know about that.  Done.  I left the "-C" in there on the

assumption they often won't want to drop the result into the CVS working

directory.
Also did some miscellaneous cleanup.
--b.
commit 48ec79a74d0daa134b677ed5458beb873aa06e9a

Author: J. Bruce Fields <bfields@citi.umich.edu>

Date:   Thu Dec 7 12:38:09 2006 -0500
    Documentation: simpler shared repo creation, miscellaneous cleanup
    Create the shared repo with init-db --shared, fetch, and manual extraction

    of .git directory, instead of using clone --bare.
    Suggest running git-cvsimport from cvs working directory, more convenient

    thatn providing all the CVS information on the commandline.
    Fix a couple mispellings, add a couple manpage links.
    Thanks to Johannes Schindelin.
    Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 773fc99..4fab0d7 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -43,8 +43,8 @@ Pull: refs/heads/master:refs/remotes/origin/master

 ------------

 ================================
-You can update the shared repository with your changes by first commiting

-your changes, and then using:

+You can update the shared repository with your changes by first committing

+your changes, and then using...
[ message continues ]

Hi,
Even easier:
$ mkdir /pub/my-repo.git

$ cd /pub/my-repo.git

$ git --bare init-db --shared

$ git --bare fetch /home/alice/myproject master:master
(Totally untested, of course.)
Ciao,

Dscho
-

Of course--for some reason I didn't think of doing init-db with --bare.

Thanks again.
--b.
From 22e5bdd9de398f29dfb11125a0921bb4529e2ab7 Mon Sep 17 00:00:00 2001

From: J. Bruce Fields <bfields@citi.umich.edu>

Date: Thu, 7 Dec 2006 22:32:28 -0500

Subject: [PATCH] Documentation: simpler shared repository creation
Take Johannes Schindelin's suggestion for a further simplification of the

shared repository creation using git --bare init-db --shared.
Also fix a mistake from the previous patch: I forgot to remove the manual setup

which the --shared does for us.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>

---

 Documentation/cvs-migration.txt |   27 ++++++++-------------------

 1 files changed, 8 insertions(+), 19 deletions(-)
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt

index 4fab0d7..20c5719 100644

--- a/Documentation/cvs-migration.txt

+++ b/Documentation/cvs-migration.txt

@@ -76,23 +76,15 @@ possibly created from scratch or from a tarball (see the

 link:tutorial.html[tutorial]), or imported from an already existing CVS

 repository (see the next section).
-Assume your existing repo is at /home/alice/myproject.  Create a temporary

-empty shared repository and fetch your project into it:

+Assume your existing repo is at /home/alice/myproject.  Create a new "bare"

+repository (a repository without a working tree) and fetch your project into

+it:
 ------------------------------------------------

-$ mkdir /pub/temporary

-$ cd /pub/temporary

-$ git init-db --shared

-$ git fetch /home/alice/myproject master:master

-------------------------------------------------

-

-Then create a "bare" repository at /pub/repo.git by just moving the contents of

-the .git directory there.  The temporary repository can then be discarded.

-

-------------------------------------------------

-$ mv .git /pub/repo.git

-$ cd ..

-$ rm -rf temporary

+$ mkdir /pub/my-repo.git

+$ cd /pub/my-repo.git

+$ git --bare init-db --shared

+$ gi...
[ message continues ]

This conflicted in a funny way with your own commit but I think

this version (773fc99 blob) supersedes its contents.
I munged only one line, though.  The title of this section

should not be "a CVS repository" but "a shared repository" for
-

Oops, yes, thanks!
--b.

-

As was mentioned in another thread, it make more sense to split this file up

into separate documents for project contributors and project admins.
--

 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

-