git faq : draft and rfc

hi,

After a quick talk on irc with pasky, fonseca and Tv, I've started to
write a git faq starting with questions I had and they have suggested.

I've setted up a git repos : http://git.librium.org/git_faq.git (atm
it's on my DSL link, so it could be slow, should move soon)

The faq is available in both docbook xml and text format (don't know
what you prefer).
You can see the html output there : http://koalabs.org/~ange/git_faq/faq.html
and the text file : http://koalabs.org/~ange/git_faq/faq.txt
if needed I can write specific xsl stylesheets to handle better or
more suited output.

Comments and suggestions are welcome (on the content, the form, format, etc ...)
I'll try to add questions from the archives of this ml, I'm also open
to any suggestions.

Here is a first (text) version :
----

. Why the 'git' name ?
As Linus' own words as the inventor of git :
"git" can mean anything, depending on your mood.
  - random three-letter combination that is pronounceable, and not
    actually used by any common UNIX command.  The fact that it is a
    mispronunciation of "get" may or may not be relevant.
  - stupid. contemptible and despicable. simple. Take your pick from the
    dictionary of slang.
  - "global information tracker": you're in a good mood, and it actually
    works for you. Angels sing, and a light suddenly fills the room.
  - "goddamn idiotic truckload of sh*t": when it breaks

. Can I use my git public repository in a shared way ?
Yes. Use cg-admin-setuprepo -g or do git-init-db --shared and some
additional stuff. It's ok that refs aren't group writable, it's
enough the directory is. See Cogito README or GIT's cvs-migration doc,
"Emulating the CVS Development Model" for details.

. Git commit is dying telling me "fatal : empty ident <user@myhost>
not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your
user line in /etc/passwd isn't empty. If you @myhost is empty make sure
your hostname is correctly set.

. What's the difference between fetch and pull ?
Fetch : download objects and a head from another repository.
Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.

. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.

. Can I import from cvs ?
Yes. Use git-cvsimport. See the cvs-migration doc for more details.

. Can I import from svn ?
Yes. Use git-svnimport. See the svn-import doc for more details.

. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.


--
Thom/ange

On 2/16/06, Thomas Riboulet [off-list ref] wrote:

. Can I import from cvs ?
Yes. Use git-cvsimport. See the cvs-migration doc for more details.

. Can I import from svn ?
Yes. Use git-svnimport. See the svn-import doc for more details.

+ Can I import from arch/baz/tla? Use git-archimport.

+ Can I import from others? Maybe -- check if tailor.py can do it.

cheers,


martin

On Thursday 16 February 2006 00:36, Thomas Riboulet wrote:

. What's the difference between fetch and pull ?
Fetch : download objects and a head from another repository.
Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.

Surely you are using a pull to mean fetch here,  Shouldn't this be

Fetch: download objects and a head from another repository.
Pull: fetch (as defined above) and then merge this with current development

or something

-- 
Alan Chandler
http://www.chandlerfamily.org.uk
Open Source. It's the difference between trust and antitrust.

Hi,

On Thu, 16 Feb 2006, Martin Langhoff wrote:

+ Can I import from others? Maybe -- check if tailor.py can do it.

+ What is tailor.py? http://www.darcs.net/DarcsWiki/Tailor.

Hth,
Dscho

How old linus bk repos have been import to git ?

On 2/16/06, Johannes Schindelin [off-list ref] wrote:

Hi,

On Thu, 16 Feb 2006, Martin Langhoff wrote:

quoted

+ Can I import from others? Maybe -- check if tailor.py can do it.

+ What is tailor.py? http://www.darcs.net/DarcsWiki/Tailor.

Hth,
Dscho

-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

--
Beber
#e.fr@freenode

I'll try to add questions from the archives of this ml, I'm also open
to any suggestions.

This is sort of the "missing" paragraph from the "git-checkout"
man page.  It's there now, but in the "-m" option.

jdl



Q.  Why won't git let me change to a different branch
    using "git checkout <branch>" or "git checkout -b <branch>"?
    Instead it just says:
        fatal: Entry 'foo.c' not uptodate. Cannot merge.

A.  You have changes to files in your working directory that
    will be overwritten, removed or otherwise lost if the checkout
    and change to the new branch were to proceed.  To fix this
    you may either check your changes in, create a patch of your
    changes and revert your files, or use the "-m" flag like this:
        git checkout -m -b my-branch

Hi,

On Thu, 16 Feb 2006, Bertrand Jacquin wrote:

How old linus bk repos have been import to git ?

Using the CVS gateway, via git-cvsimport.

Hth,
Dscho

Dear diary, on Thu, Feb 16, 2006 at 01:36:20AM CET, I got a letter
where Thomas Riboulet [off-list ref] said that...

. Git commit is dying telling me "fatal : empty ident <user@myhost>
not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your
user line in /etc/passwd isn't empty. If you @myhost is empty make sure
your hostname is correctly set.

Please also mention GIT_AUTHOR_NAME; chsh may be frequently unavailable.

. What's the difference between fetch and pull ?
Fetch : download objects and a head from another repository.
Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.

This could do with a little more elaboration as well. Nice inspiration
might be [off-list ref].

. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.

Or .gitignore in the tree itself. .git/info/exclude is only for your
particular checkout while .gitignore is what matters for all and
everyone's checkouts of the project.

. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.

Well this is about how to make it available, not how to use it.

The repository should be set up by cg-admin-setuprepo or git-init-db
--shared and normally does not have a working tree attached. You can
fetch from such a repository either over:

	* the GIT protocol (you need to run git-daemon)
	* SSH (you can set up a git-use-only account using git-shell)
	* rsync (has important disadvantages but it is currently the
	  fastest way to do the initial checkout)
	* or the HTTP protocol (any reasonable webhosting will do, but
	  you need to run git-update-server-info after each repository
	  update; if you used cg-admin-setuprepo to set it up, this
	  will be done automatically, otherwise you may enable it in
	  the post-update hook - see .git/hooks/post-update).

You can push to such a repository over:

	* SSH
	* HTTP DAV (you will need to specially configure your HTTP
	  server for this)

Obviously, you can also fetch/push from/to a repository locally if it
is available in the local filesystem structure.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Of the 3 great composers Mozart tells us what it's like to be human,
Beethoven tells us what it's like to be Beethoven and Bach tells us
what it's like to be the universe.  -- Douglas Adams

On 2/16/06, Petr Baudis [off-list ref] wrote:

Dear diary, on Thu, Feb 16, 2006 at 01:36:20AM CET, I got a letter
where Thomas Riboulet [off-list ref] said that...

quoted

. Git commit is dying telling me "fatal : empty ident <user@myhost>
not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your
user line in /etc/passwd isn't empty. If you @myhost is empty make sure
your hostname is correctly set.

Please also mention GIT_AUTHOR_NAME; chsh may be frequently unavailable.

ok

quoted

. What's the difference between fetch and pull ?
Fetch : download objects and a head from another repository.
Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.

This could do with a little more elaboration as well. Nice inspiration
might be [off-list ref].

ok, I'll as soon as I manage to get it :/

quoted

. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.

Or .gitignore in the tree itself. .git/info/exclude is only for your
particular checkout while .gitignore is what matters for all and
everyone's checkouts of the project.

ok, added

quoted

. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.

Well this is about how to make it available, not how to use it.

The repository should be set up by cg-admin-setuprepo or git-init-db
--shared and normally does not have a working tree attached. You can
fetch from such a repository either over:

        * the GIT protocol (you need to run git-daemon)
        * SSH (you can set up a git-use-only account using git-shell)
        * rsync (has important disadvantages but it is currently the
          fastest way to do the initial checkout)
        * or the HTTP protocol (any reasonable webhosting will do, but
          you need to run git-update-server-info after each repository
          update; if you used cg-admin-setuprepo to set it up, this
          will be done automatically, otherwise you may enable it in
          the post-update hook - see .git/hooks/post-update).

You can push to such a repository over:

        * SSH
        * HTTP DAV (you will need to specially configure your HTTP
          server for this)

Obviously, you can also fetch/push from/to a repository locally if it
is available in the local filesystem structure.

the initial aim of that question was simply to tell svn people (and
others) what can be used to setup a public repos.
isn't it a bit too much for a faq ? maybe add some things to the
present answer and put this question in the "general questions"
section (see below), and add more details in the "usage" section ?

--
                                Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Of the 3 great composers Mozart tells us what it's like to be human,
Beethoven tells us what it's like to be Beethoven and Bach tells us
what it's like to be the universe.  -- Douglas Adams

ok added (and pushed) the :
- taylor qa
- the git import bk qa
- GIT_AUTHOR_NAME

I'll separate the questions between the following sections :
- general questions (who, when, where, ...)
- usage : commands, errors ...

I'm planning on removing the text format faq and handle it as I handle
the html one  : through the docbook. ok ?

--
Thom/ange

Signed-off-by: Jonas Fonseca <redacted>

---

Thomas Riboulet [off-list ref] wrote Thu, Feb 16, 2006:

Comments and suggestions are welcome (on the content, the form, format, etc ...)
I'll try to add questions from the archives of this ml, I'm also open
to any suggestions.

As promissed on the #git channel this patch converts the faq to asciidoc
format, with a few enhancements such as links to manpages and a TOC.

Previews at
http://www.diku.dk/hjemmesider/studerende/fonseca/git/git-faq.{html,txt,xml}.

---

 Makefile |   23 ++++++++
 faq.conf |   19 +++++++
 faq.txt  |  175 ++++++++++++++++++++++++++++++++++++++++++--------------------
 3 files changed, 161 insertions(+), 56 deletions(-)

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..09f6978
--- /dev/null
+++ b/Makefile

@@ -0,0 +1,23 @@
+all: git-faq.html git-faq.xml git-faq.txt
+
+clean:
+	rm -f git-faq.html git-faq.xml git-faq.txt faq-toc.txt
+
+git-faq.html git-faq.xml git-faq.txt: faq.txt faq-toc.txt
+
+git-faq.xml:
+	asciidoc -f faq.conf -b docbook -d article -o $@ faq.txt
+
+git-faq.html: faq.txt faq-toc.txt
+	asciidoc -f faq.conf -b xhtml11 -d article -o $@ faq.txt
+
+git-faq.txt: git-faq.html
+	elinks --no-numbering --no-references --dump $< > $@
+
+faq-toc.txt: faq.txt
+	sed -n '/^\[\[/,/--/p' < $< | while read line; do \
+		case "$$line" in \
+		"[["*"]]") echo -n ". <<$$line, " | sed 's/\[\[\(.*\)\]\]/\1/' ;; \
+		--*)	   echo    ">>" ;; \
+		*)	   echo -n "$$line " ;; \
+		esac; done > $@

diff --git a/faq.conf b/faq.conf
new file mode 100644
index 0000000..fa16ad6
--- /dev/null
+++ b/faq.conf

@@ -0,0 +1,19 @@
+# AsciiDoc FAQ definitions
+
+[attributes]
+gitdoc-base=http://kernel.org/pub/software/scm/git/docs/
+cgdoc-base=http://kernel.org/pub/software/scm/cogito/docs/
+
+ifdef::backend-docbook[]
+[gitdoc-inlinemacro]
+<ulink url="{gitdoc-base}{target}.html">{0}</ulink>
+[cgdoc-inlinemacro]
+<ulink url="{cgdoc-base}{target}.html">{0}</ulink>
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[gitdoc-inlinemacro]
+<a href="{gitdoc-base}{target}.html">{0}</a>
+[cgdoc-inlinemacro]
+<a href="{cgdoc-base}{target}.html">{0}</a>
+endif::backend-xhtml11[]

diff --git a/faq.txt b/faq.txt
index e719d04..9c7baa0 100644
--- a/faq.txt
+++ b/faq.txt

@@ -1,68 +1,131 @@
-Why the 'git' name ?
-
-As Linus' own words as the inventor of git : "git" can mean anything, depending on your mood.
-
-* random three-letter combination that is pronounceable, and not actually used by any common UNIX command. The fact that it is a mispronunciation of "get" may or may not be relevant.
-*  stupid. contemptible and despicable. simple. Take your pick from the dictionary of slang.
-* global information tracker": you're in a good mood, and it actually works for you. Angels sing, and a light suddenly fills the room.
-* "goddamn idiotic truckload of sh*t": when it breaks 
-
-
-Can I share a git public repository and use it in a CVS way ?
-
-Use cg-admin-setuprepo -g or do git-init-db --shared and some additional stuff. It's ok that refs aren't group writable, it's enough the directory is. See Cogito README or GIT's cvs-migration doc, "Emulating the CVS Development Model" for details.
-
-
-Git commit is dying telling me "fatal : empty ident <user@myhost> not allowed" , what's wrong ?
-
-Make sure your Full Name is not empty in chsh or the 5th field of your user line in /etc/passwd isn't empty. You can also set the GIT_AUTHOR_NAME environment variable. If you @myhost is empty make sure your hostname is correctly set.
-What's the difference between fetch and pull ?
-
-Fetch : download objects and a head from another repository.
-Pull : fetch (as defined above) and merge with the current development.
-See man git-fetch and git-pull or the tutorials for more details.
-
-
-
-Can I tell git to ignore files ?
-
-Yes. If you want to ignore files localy (only for you in your local work copy) put the files path in the repository in the .git/info/exclude file.
-
-If you want to make the ignore matters for all and everyone who checkouts the project you have to put the files path in the .gitignore in the tree itself.
-
-
-Can I import from cvs ?
-
-Yes. Use git-cvsimport. See the cvs-migration doc for more details.
-
-
-Can I import from svn ?
-
-Yes. Use git-svnimport. See the svn-import doc for more details.
+The git FAQ
+===========
+:Author:	Thomas Riboulet
+:CorpAuthor:	git mailing list
+
+//////////////////////////////////////////////////////////////////////////////
+A note about required info for FAQ entries. Please use the following template:
+
+	[[question-id]]
+	question?
+	---------
+	answer.
+
+The question-id + question will be used for generating a table of contents.
+//////////////////////////////////////////////////////////////////////////////
+
+// DocBook derived output will (hopefully) have it's own TOC
+ifdef::backend-xhtml11[]
+include::faq-toc.txt[]
+endif::backend-xhtml11[]
+
+[[git-name]]
+Why the 'git' name?
+-------------------
+In Linus' own words as the inventor of git: "git" can mean anything, depending
+on your mood:
+
+ - random three-letter combination that is pronounceable, and not actually
+   used by any common UNIX command. The fact that it is a mispronunciation of
+   "get" may or may not be relevant.
+ - stupid. contemptible and despicable. simple. Take your pick from the
+   dictionary of slang.
+ - global information tracker": you're in a good mood, and it actually works
+   for you. Angels sing, and a light suddenly fills the room.
+ - "goddamn idiotic truckload of sh*t": when it breaks 
+
+
+[[repo-sharing]]]
+Can I share a git public repository and use it in a CVS way?
+------------------------------------------------------------
+Use cg-admin-setuprepo -g or do git-init-db --shared and some additional
+stuff. It's ok that refs aren't group writable, it's enough the directory is.
+See Cogito README or GIT's cvs-migration doc, "Emulating the CVS Development
+Model" for details.
+
+
+[[empty-ident]]
+Git commit is dying telling me "fatal: empty ident <user@myhost> not allowed", what's wrong?
+--------------------------------------------------------------------------------------------
+Make sure your Full Name is not empty in chsh or the 5th field of your user
+line in `/etc/passwd` isn't empty. You can also set the `GIT_AUTHOR_NAME`
+environment variable. If your @myhost is empty make sure your hostname is
+correctly set. Use gitdoc:git-var[`git-var -l`] to make git display user
+identity variables.
+
+
+[[fetch-vs-pull]]
+What's the difference between fetch and pull?
+---------------------------------------------
+The short definition is:
+
+Fetch::	Download objects and a head from another repository.
+Pull::	Fetch (as defined above) and merge with the current development.
+
+See the gitdoc:git-fetch[git-fetch(1)] and gitdoc:git-pull[git-pull(1)]
+manpages or the tutorials for more details.
+
+
+[[gitignore]]
+Can I tell git to ignore files?
+-------------------------------
+Yes. If you want to ignore files localy (only for you in your local work copy)
+put the files path in the repository in the `.git/info/exclude` file.
+
+If you want to make the ignore matters for all and everyone who checkouts the
+project you have to put the files path in the `.gitignore` in the tree itself.
+
+
+[[import-cvs]]
+Can I import from CVS?
+----------------------
+Yes. Use git-cvsimport. See the gitdoc:git-cvsimport[git-cvsimport(1)] or
+gitdoc:cvs-migration[the CVS migration doc] for more detail.
+
+
+[[import-svn]]
+Can I import from svn?
+----------------------
+Yes. Use git-svnimport. See gitdoc:git-svnimport[git-svnimport(1)] for more
+details.
 
 
+[[import-arch]]
 Can I import from arch/baz/tla?
-
-Yes. Use git-archimport.
+-------------------------------
+Yes. Use git-svnimport. See gitdoc:git-archimport[git-archimport(1)] for more
+details.
 
 
+[[import-others]]
 Can I import from others?
+-------------------------
+Maybe -- check if http://www.darcs.net/DarcsWiki/Tailor[tailor.py] can do it.
 
-Maybe -- check if tailor.py can do it. Check http://www.darcs.net/DarcsWiki/Tailor.
-
-
-How old linus bk repos have been import to git ?
 
+[[linux-bk]]
+How was the old Linux BitKeeper repository imported into git?
+-------------------------------------------------------------
 Using the CVS gateway, via git-cvsimport.
 
 
-What can I use to setup a public repository ?
-
-A ssh server, an http server, or the git-daemon. See the tutorial for more details.
-
-
-Why won't git let me change to a different branch using "git checkout <branch>" or "git checkout -b <branch>"?
-
-Instead it just says: fatal: Entry 'foo.c' not uptodate. Cannot merge.
+[[public-repo]]
+What can I use to setup a public repository?
+--------------------------------------------
+A SSH server, an HTTP server, or the gitdoc:git-daemon[git-daemon]. See the
+tutorial for more details.
+
+
+[[change-branch]]
+Why won't git let me change to a different branch?
+--------------------------------------------------
+Using "git checkout <branch>" or "git checkout -b <branch>" it just says:
+
+	fatal: Entry 'foo.c' not uptodate. Cannot merge.
+
+You have changes to files in your working directory that will be overwritten,
+removed or otherwise lost if the checkout and change to the new branch were to
+proceed. To fix this you may either check your changes in, create a patch of
+your changes and revert your files, or use the "-m" flag like this:
 
-You have changes to files in your working directory that will be overwritten, removed or otherwise lost if the checkout and change to the new branch were to proceed. To fix this you may either check your changes in, create a patch of your changes and revert your files, or use the "-m" flag like this: git checkout -m -b my-branch 
+	git checkout -m -b my-branch

-- 
Jonas Fonseca

On 2/20/06, Jonas Fonseca [off-list ref] wrote:

hi,

ok seems much easier than docbook to write, I've commited your
changes, I'll push them when I'll be back home.

I've tested the docbook file generated, works fine

thanks

--
Thom/ange
http://ange.librium.org

Maybe another question :

How could I merge a branch 'to-merge' with structure a/b/c into branch
'master' with structure g/h/i and include files from branch 'to-merge'
in g/h/i ?

I don't know if it's very clear

--
Beber
#e.fr@freenode

On 2/20/06, Bertrand Jacquin [off-list ref] wrote:

Maybe another question :

How could I merge a branch 'to-merge' with structure a/b/c into branch
'master' with structure g/h/i and include files from branch 'to-merge'
in g/h/i ?

Like as Junio with branch man and html.

I don't know if it's very clear

--
Beber
#e.fr@freenode

--
Beber
#e.fr@freenode