[PATCH] Documentation: packed GIT support commands.

[PATCH] Documentation: packed GIT support commands.

[Junio C Hamano]

This adds documentation for creating packed archives, inspecting,
validating them, and unpacking them.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/git-pack-objects.txt   |   80 ++++++++++++++++++++++++++++++++++
 Documentation/git-show-index.txt     |   36 +++++++++++++++
 Documentation/git-unpack-objects.txt |   33 ++++++++++++++
 Documentation/git-verify-pack.txt    |   13 +++++-
 4 files changed, 161 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/git-pack-objects.txt
 create mode 100644 Documentation/git-show-index.txt
 create mode 100644 Documentation/git-unpack-objects.txt

32a772fa72da57fbbe9ea27d195e6b755c83cd22
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/git-pack-objects.txt
@@ -0,0 +1,80 @@
+git-pack-objects(1)
+===================
+v0.1, July 2005
+
+NAME
+----
+git-pack-objects - Create a packed archive of objects.
+
+
+SYNOPSIS
+--------
+'git-pack-objects' [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list
+
+
+DESCRIPTION
+-----------
+Reads list of objects from the standard input, and writes a packed
+archive with specified base-name, or to the standard output.
+
+A packed archive is an efficient way to transfer set of objects
+between two repositories, and also is an archival format which
+is efficient to access.  The packed archive format (.pack) is
+designed to be unpackable without having anything else, but for
+random access, accompanied with the pack index file (.idx).
+
+'git-unpack-objects' command can read the packed archive and
+expand the objects contained in the pack into "one-file
+one-object" format; this is typically done by the smart-pull
+commands when a pack is created on-the-fly for efficient network
+transport by their peers.
+
+Placing both in pack subdirectory of $GIT_OBJECT_DIRECTORY (or
+any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
+enables GIT to read from such an archive.
+
+
+OPTIONS
+-------
+base-name::
+	Write into a pair of files (.pack and .idx), using
+	<base-name> to determine the name of the created file.
+	When this option is used, the two files are written in
+	<base-name>-<SHA1>.{pack,idx} files.  <SHA1> is a hash
+	of object names (currently in random order so it does
+	not have any useful meaning) to make the resulting
+	filename reasonably unique, and written to the standard
+	output of the command.
+
+--stdout::
+	Write the pack contents (what would have been writtin to
+	.pack file) out to the standard output.
+
+--window and --depth::
+	These two options affects how the objects contained in
+	the pack are stored using delta compression.  The
+	objects are first internally sorted by type, size and
+	optionally names and compared against the other objects
+	within --window to see if using delta compression saves
+	space.  --depth limits the maximum delta depth; making
+	it too deep affects the performance on the unpacker
+	side, because delta data needs to be applied that many
+	times to get to the necessary object.
+
+--incremental::
+	This flag causes an object already in a pack ignored
+	even if it appears in the standard input.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+-------------
+Documentation by Junio C Hamano
+
+GIT
+---
+Part of the link:git.html[git] suite
+
diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/git-show-index.txt
@@ -0,0 +1,36 @@
+git-show-index(1)
+=================
+v0.1, July 2005
+
+NAME
+----
+git-show-index - Show packed archive index
+
+
+SYNOPSIS
+--------
+'git-show-index' < idx-file
+
+
+DESCRIPTION
+-----------
+Reads given idx file for packed GIT archive created with
+git-pack-objects command, and dumps its contents.
+
+The information it outputs is subset of what you can get from
+'git-verify-pack -v'; this command only shows the packfile
+offset and SHA1 of each object.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano
+
+GIT
+---
+Part of the link:git.html[git] suite
+
diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/git-unpack-objects.txt
@@ -0,0 +1,33 @@
+git-unpack-objects(1)
+=====================
+v0.1, July 2005
+
+NAME
+----
+git-unpack-objects - Create a packed archive of objects.
+
+
+SYNOPSIS
+--------
+'git-unpack-objects' < pack-file
+
+
+DESCRIPTION
+-----------
+Reads a packed archive (.pack) from the standard input, and
+expands the objects contained in the pack into "one-file
+one-object" format in $GIT_OBJECT_DIRECTORY.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+-------------
+Documentation by Junio C Hamano
+
+GIT
+---
+Part of the link:git.html[git] suite
+
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -9,7 +9,7 @@ git-verify-pack - Validate packed GIT ar
 
 SYNOPSIS
 --------
-'git-verify-pack' <pack>.idx ...
+'git-verify-pack' [-v] <pack>.idx ...
 
 
 DESCRIPTION
@@ -23,6 +23,17 @@ OPTIONS
 <pack>.idx ...::
 	The idx files to verify.
 
+-v::
+	After verifying the pack, show list of objects contained
+	in the pack.  The format used is:
+
+		SHA1 type size offset-in-packfile
+
+	for objects that are not deltified in the pack, and
+
+		SHA1 type size offset-in-packfile depth base-SHA1
+
+	for objects that are deltified.
 
 Author
 ------

[PATCH] Documentation: update tutorial to talk about push.

[Junio C Hamano]

Talk about publishing to a public repository.  Also fixes a
couple of typos.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---
*** To be consistent with the rest of the text, I said "I" push
*** to master.kernel.org, but obviously I am lying there ;-).  I
*** do not know if your changes enters the public repo starting
*** at master.kernel.org, nor you would particularly want to
*** publicize how it actually works in the documentation.  I
*** just tried giving readers realistic enough feel, but I
*** welcome editorial fixes.

 Documentation/tutorial.txt |   87 ++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 80 insertions(+), 7 deletions(-)

37a26024be1ec6b5ea04ecf109fd149fb6984fe8
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -480,9 +480,10 @@ This has two implications: 
    history outside of the project you created.
 
  - if you want to move or duplicate a git archive, you can do so. There
-   is no "git clone" command: if you want to create a copy of your
-   archive (with all the full history that went along with it), you can
-   do so with a regular "cp -a git-tutorial new-git-tutorial".
+   is "git clone" command, but if all you want to do is just to
+   create a copy of your archive (with all the full history that
+   went along with it), you can do so with a regular
+   "cp -a git-tutorial new-git-tutorial".
 
    Note that when you've moved or copied a git archive, your git index
    file (which caches various information, notably some of the "stat"
@@ -534,7 +535,7 @@ create your own copy of the git reposito
 
 	mkdir my-git
 	cd my-git
-	rsync -rL rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/git.git/ .git
+	rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git .git
 
 followed by 
 
@@ -549,14 +550,14 @@ those, you'd check them out with
 
 where the "-u" flag means that you want the checkout to keep the index
 up-to-date (so that you don't have to refresh it afterward), and the
-"-a" file means "check out all files" (if you have a stale copy or an
+"-a" flag means "check out all files" (if you have a stale copy or an
 older version of a checked out tree you may also need to add the "-f"
-file first, to tell git-checkout-cache to _force_ overwriting of any old
+flag first, to tell git-checkout-cache to _force_ overwriting of any old
 files). 
 
 Again, this can all be simplified with
 
-	git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/git.git/ my-git
+	git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
 	cd my-git
 	git checkout
 
@@ -770,3 +771,75 @@ point, just create a private tag for it,
 name for the state at that point.
 
 [ to be continued.. cvsimports, pushing and pulling ]
+
+
+	Publishing your work
+	--------------------
+
+We already talked about using somebody else's work from a remote
+repository, in the "merging external work" section.  It involved
+fetching the work from a remote repository; but how would _you_
+prepare a repository so that other people can fetch from it?
+
+Your real work happens in your working directory with your
+primary repository hanging under it as its ".git" subdirectory.
+You _could_ make it accessible remotely and ask people to pull
+from it, but in practice that is not the way things are usually
+done.  A recommended way is to have a public repository, make it
+reachable by other people, and when the changes you made in your
+primary working directory are in good shape, update the public
+repository with it.
+
+[ Side note: this public repository could further be mirrored,
+  and that is how kernel.org git repositories are done.  ]
+
+Publishing the changes from your private repository to your
+public repository requires you to have write privilege on the
+machine that hosts your public repository, and it is internally
+done via an SSH connection.
+
+First, you need to create an empty repository to push to on the
+machine that houses your public repository.  This needs to be
+done only once.
+
+Your private repository's GIT directory is usually .git, but
+often your public repository is named "<projectname>.git".
+Let's create such a public repository for project "my-git".
+After logging into the remote machine, create an empty
+directory:
+
+	mkdir my-git.git
+
+Then, initialize that directory with git-init-db, but this time,
+since it's name is not usual ".git", we do things a bit
+differently:
+
+	GIT_DIR=my-git.git git-init-db
+
+Make sure this directory is available for others you want your
+changes to be pulled by.  Also make sure that you have the
+'git-receive-pack' program on the $PATH.
+
+[ Side note: many installations of sshd does not invoke your
+  shell as the login shell when you directly run programs; what
+  this means is that if your login shell is bash, only .bashrc
+  is read bypassing .bash_profile.  As a workaround, make sure
+  .bashrc sets up $PATH so that 'git-receive-pack' program can
+  be run.  ]
+
+Your 'public repository' is ready to accept your changes.  Now,
+come back to the machine you have your private repository.  From
+there, run this command:
+
+	git push <public-host>:/path/to/my-git.git master
+
+This synchronizes your public repository to match the named
+branch head (i.e. refs/heads/master in this case) and objects
+reachable from them in your current repository.
+
+As a real example, this is how I update my public git
+repository.  Kernel.org mirror network takes care of the
+propagation to other publically visible machines:
+
+	git push master.kernel.org:/pub/scm/git/git.git/ 
+

[PATCH] Documentation: pull, push, packing repository and working with others.

[Junio C Hamano]

Describe where you can pull from with a bit more detail.
Clarify description of pushing.

Add a section on packing repositories.

Add a section on recommended workflow for the project lead,
subsystem maintainers and individual developers.

Move "Tag" section around to make the flow of example simpler to
follow.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/tutorial.txt |  371 ++++++++++++++++++++++++++++++++++----------
 1 files changed, 290 insertions(+), 81 deletions(-)

9ad5d377ecf29ab6d7044db128bee98bf9690bbe
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -453,6 +453,55 @@ With that, you should now be having some
 can explore on your own.
 
 
+[ Side note: most likely, you are not directly using the core
+  git Plumbing commands, but using Porcelain like Cogito on top
+  of it.  Cogito works a bit differently and you usually do not
+  have to run "git-update-cache" yourself for changed files (you
+  do tell underlying git about additions and removals via
+  "cg-add" and "cg-rm" commands).  Just before you make a commit
+  with "cg-commit", Cogito figures out which files you modified,
+  and runs "git-update-cache" on them for you.  ]
+
+
+	Tagging a version
+	-----------------
+
+In git, there's two kinds of tags, a "light" one, and a "signed tag".
+
+A "light" tag is technically nothing more than a branch, except we put
+it in the ".git/refs/tags/" subdirectory instead of calling it a "head".
+So the simplest form of tag involves nothing more than
+
+	cat .git/HEAD > .git/refs/tags/my-first-tag
+
+after which point you can use this symbolic name for that particular
+state. You can, for example, do
+
+	git diff my-first-tag
+
+to diff your current state against that tag (which at this point will
+obviously be an empty diff, but if you continue to develop and commit
+stuff, you can use your tag as a "anchor-point" to see what has changed
+since you tagged it.
+
+A "signed tag" is actually a real git object, and contains not only a
+pointer to the state you want to tag, but also a small tag name and
+message, along with a PGP signature that says that yes, you really did
+that tag. You create these signed tags with
+
+	git tag <tagname>
+
+which will sign the current HEAD (but you can also give it another
+argument that specifies the thing to tag, ie you could have tagged the
+current "mybranch" point by using "git tag <tagname> mybranch").
+
+You normally only do signed tags for major releases or things
+like that, while the light-weight tags are useful for any marking you
+want to do - any time you decide that you want to remember a certain
+point, just create a private tag for it, and you have a nice symbolic
+name for the state at that point.
+
+
 	Copying archives
 	-----------------
 
@@ -729,117 +778,277 @@ simply do
 and optionally give a branch-name for the remote end as a second
 argument.
 
-[ Todo: fill in real examples ]
-
-
-	Tagging a version
-	-----------------
-
-In git, there's two kinds of tags, a "light" one, and a "signed tag".
-
-A "light" tag is technically nothing more than a branch, except we put
-it in the ".git/refs/tags/" subdirectory instead of calling it a "head".
-So the simplest form of tag involves nothing more than
-
-	cat .git/HEAD > .git/refs/tags/my-first-tag
-
-after which point you can use this symbolic name for that particular
-state. You can, for example, do
-
-	git diff my-first-tag
-
-to diff your current state against that tag (which at this point will
-obviously be an empty diff, but if you continue to develop and commit
-stuff, you can use your tag as a "anchor-point" to see what has changed
-since you tagged it.
-
-A "signed tag" is actually a real git object, and contains not only a
-pointer to the state you want to tag, but also a small tag name and
-message, along with a PGP signature that says that yes, you really did
-that tag. You create these signed tags with
-
-	git tag <tagname>
-
-which will sign the current HEAD (but you can also give it another
-argument that specifies the thing to tag, ie you could have tagged the
-current "mybranch" point by using "git tag <tagname> mybranch").
-
-You normally only do signed tags for major releases or things
-like that, while the light-weight tags are useful for any marking you
-want to do - any time you decide that you want to remember a certain
-point, just create a private tag for it, and you have a nice symbolic
-name for the state at that point.
-
-[ to be continued.. cvsimports, pushing and pulling ]
+The "remote" repository can even be on the same machine.  One of
+the following notations can be used to name the repository to
+pull from:
+
+	Rsync URL
+		rsync://remote.machine/path/to/repo.git/
+
+	HTTP(s) URL
+		http://remote.machine/path/to/repo.git/
+
+	GIT URL
+		git://remote.machine/path/to/repo.git/
+		remote.machine:/path/to/repo.git/
+
+	Local directory
+		/path/to/repo.git/
+
+[ Side Note: currently, HTTP transport is slightly broken in
+  that when the remote repository is "packed" they do not always
+  work.  But we have not talked about packing repository yet, so
+  let's not worry too much about it for now.  ]
+
+[ Digression: you could do without using any branches at all, by
+  keeping as many local repositories as you would like to have
+  branches, and merging between them with "git pull", just like
+  you merge between branches.  The advantage of this approach is
+  that it lets you keep set of files for each "branch" checked
+  out and you may find it easier to switch back and forth if you
+  juggle multiple lines of development simultaneously.  Of
+  course, you will pay the price of more disk usage to hold
+  multiple working trees, but disk space is cheap these days.  ]
 
 
 	Publishing your work
 	--------------------
 
-We already talked about using somebody else's work from a remote
-repository, in the "merging external work" section.  It involved
-fetching the work from a remote repository; but how would _you_
-prepare a repository so that other people can fetch from it?
+So we can use somebody else's work from a remote repository; but
+how can _you_ prepare a repository to let other people pull from
+it?
 
-Your real work happens in your working directory with your
+Your do your real work in your working directory that has your
 primary repository hanging under it as its ".git" subdirectory.
-You _could_ make it accessible remotely and ask people to pull
-from it, but in practice that is not the way things are usually
-done.  A recommended way is to have a public repository, make it
-reachable by other people, and when the changes you made in your
-primary working directory are in good shape, update the public
-repository with it.
+You _could_ make that repository accessible remotely and ask
+people to pull from it, but in practice that is not the way
+things are usually done.  A recommended way is to have a public
+repository, make it reachable by other people, and when the
+changes you made in your primary working directory are in good
+shape, update the public repository from it.  This is often
+called "pushing".
 
 [ Side note: this public repository could further be mirrored,
   and that is how kernel.org git repositories are done.  ]
 
-Publishing the changes from your private repository to your
-public repository requires you to have write privilege on the
-machine that hosts your public repository, and it is internally
-done via an SSH connection.
-
-First, you need to create an empty repository to push to on the
-machine that houses your public repository.  This needs to be
+Publishing the changes from your local (private) repository to
+your remote (public) repository requires a write privilege on
+the remote machine.  You need to have an SSH account there to
+run a single command, "git-receive-pack".
+
+First, you need to create an empty repository on the remote
+machine that will house your public repository.  This empty
+repository will be populated and be kept up-to-date by pushing
+into it later.  Obviously, this repository creation needs to be
 done only once.
 
+[ Digression: "git push" uses a pair of programs,
+  "git-send-pack" on your local machine, and "git-receive-pack"
+  on the remote machine.  The communication between the two over
+  the network internally uses an SSH connection.  ]
+
 Your private repository's GIT directory is usually .git, but
-often your public repository is named "<projectname>.git".
-Let's create such a public repository for project "my-git".
-After logging into the remote machine, create an empty
-directory:
+your public repository is often named after the project name,
+i.e. "<project>.git".  Let's create such a public repository for
+project "my-git".  After logging into the remote machine, create
+an empty directory:
 
 	mkdir my-git.git
 
-Then, initialize that directory with git-init-db, but this time,
-since it's name is not usual ".git", we do things a bit
-differently:
+Then, make that directory into a GIT repository by running
+git-init-db, but this time, since it's name is not the usual
+".git", we do things slightly differently:
 
 	GIT_DIR=my-git.git git-init-db
 
 Make sure this directory is available for others you want your
-changes to be pulled by.  Also make sure that you have the
-'git-receive-pack' program on the $PATH.
-
-[ Side note: many installations of sshd does not invoke your
-  shell as the login shell when you directly run programs; what
-  this means is that if your login shell is bash, only .bashrc
-  is read bypassing .bash_profile.  As a workaround, make sure
-  .bashrc sets up $PATH so that 'git-receive-pack' program can
-  be run.  ]
+changes to be pulled by via the transport of your choice.  Also
+you need to make sure that you have the "git-receive-pack"
+program on the $PATH.
+
+[ Side note: many installations of sshd do not invoke your shell
+  as the login shell when you directly run programs; what this
+  means is that if your login shell is bash, only .bashrc is
+  read and not .bash_profile.  As a workaround, make sure
+  .bashrc sets up $PATH so that you can run 'git-receive-pack'
+  program.  ]
 
-Your 'public repository' is ready to accept your changes.  Now,
-come back to the machine you have your private repository.  From
+Your "public repository" is now ready to accept your changes.
+Come back to the machine you have your private repository.  From
 there, run this command:
 
 	git push <public-host>:/path/to/my-git.git master
 
 This synchronizes your public repository to match the named
-branch head (i.e. refs/heads/master in this case) and objects
-reachable from them in your current repository.
+branch head (i.e. "master" in this case) and objects reachable
+from them in your current repository.
 
 As a real example, this is how I update my public git
 repository.  Kernel.org mirror network takes care of the
-propagation to other publically visible machines:
+propagation to other publicly visible machines:
 
 	git push master.kernel.org:pub/scm/git/git.git/ 
 
+
+[ Digression: your GIT "public" repository people can pull from
+  is different from a public CVS repository that lets read-write
+  access to multiple developers.  It is a copy of _your_ primary
+  repository published for others to use, and you should not
+  push into it from more than one repository (this means, not
+  just disallowing other developers to push into it, but also
+  you should push into it from a single repository of yours).
+  Sharing the result of work done by multiple people are always
+  done by pulling (i.e. fetching and merging) from public
+  repositories of those people.  Typically this is done by the
+  "project lead" person, and the resulting repository is
+  published as the public repository of the "project lead" for
+  everybody to base further changes on.  ]
+
+
+	Packing your repository
+	-----------------------
+
+Earlier, we saw that one file under .git/objects/??/ directory
+is stored for each git object you create.  This representation
+is convenient and efficient to create atomically and safely, but
+not so to transport over the network.  Since git objects are
+immutable once they are created, there is a way to optimize the
+storage by "packing them together".  The command
+
+	git repack
+
+will do it for you.  If you followed the tutorial examples, you
+would have accumulated about 17 objects in .git/objects/??/
+directories by now.  "git repack" tells you how many objects it
+packed, and stores the packed file in .git/objects/pack
+directory.
+
+[ Side Note: you will see two files, pack-*.pack and pack-*.idx,
+  in .git/objects/pack directory.  They are closely related to
+  each other, and if you ever copy them by hand to a different
+  repository for whatever reason, you should make sure you copy
+  them together.  The former holds all the data from the objects
+  in the pack, and the latter holds the index for random
+  access.  ]
+
+If you are paranoid, running "git-verify-pack" command would
+detect if you have a corrupt pack, but do not worry too much.
+Our programs are always perfect ;-).
+
+Once you have packed objects, you do not need to leave the
+unpacked objects that are contained in the pack file anymore.
+
+	git prune-packed
+
+would remove them for you.
+
+You can try running "find .git/objects -type f" before and after
+you run "git prune-packed" if you are curious.
+
+[ Side Note: as we already mentioned, "git pull" is broken for
+  some transports dealing with packed repositories right now, so
+  do not run "git prune-packed" if you plan to give "git pull"
+  access via HTTP transport for now.  ]
+
+If you run "git repack" again at this point, it will say
+"Nothing to pack".  Once you continue your development and
+accumulate the changes, running "git repack" again will create a
+new pack, that contains objects created since you packed your
+archive the last time.  We recommend that you pack your project
+soon after the initial import (unless you are starting your
+project from scratch), and then run "git repack" every once in a
+while, depending on how active your project is.
+
+When a repository is synchronized via "git push" and "git pull",
+objects packed in the source repository is usually stored
+unpacked in the destination, unless rsync transport is used.
+
+
+	Working with Others
+	-------------------
+
+A recommended work cycle for a "project lead" is like this:
+
+ (1) Prepare your primary repository on your local machine. Your
+     work is done there.
+
+ (2) Prepare a public repository accessible to others.
+
+ (3) Push into the public repository from your primary
+     repository.
+
+ (4) "git repack" the public repository.  This establishes a big
+     pack that contains the initial set of objects.
+
+ (5) Keep working in your primary repository, and push your
+     changes to the public repository.  Your changes include
+     your own, patches you receive via e-mail, and merge resulting
+     from pulling the "public" repositories of your "subsystem
+     maintainers".
+
+     You can repack this private repository whenever you feel
+     like.
+
+ (6) Every once in a while, "git repack" the public repository.
+     Go back to step (5) and continue working.
+
+A recommended work cycle for a "subsystem maintainer" that
+works on that project and has own "public repository" is like
+this:
+
+ (1) Prepare your work repository, by "git clone" the public
+     repository of the "project lead".
+
+ (2) Prepare a public repository accessible to others.
+
+ (3) Copy over the packed files from "project lead" public
+     repository to your public repository by hand; this part is
+     currently not automated.
+
+ (4) Push into the public repository from your primary
+     repository.
+
+ (5) Keep working in your primary repository, and push your
+     changes to your public repository, and ask your "project
+     lead" to pull from it.  Your changes include your own,
+     patches you receive via e-mail, and merge resulting from
+     pulling the "public" repositories of your "project lead"
+     and possibly your "sub-subsystem maintainers".
+
+     You can repack this private repository whenever you feel
+     like.
+
+ (6) Every once in a while, "git repack" the public repository.
+     Go back to step (5) and continue working.
+
+A recommended work cycle for an "individual developer" who does
+not have a "public" repository is somewhat different.  It goes
+like this:
+
+ (1) Prepare your work repositories, by "git clone" the public
+     repository of the "project lead" (or "subsystem
+     maintainer", if you work on a subsystem).
+
+ (2) Copy .git/refs/master to .git/refs/upstream.
+
+ (3) Do your work there.  Make commits.
+
+ (4) Run "git fetch" from the public repository of your upstream
+     every once in a while.  This does only the first half of
+     "git pull" but does not merge.  The head of the public
+     repository is stored in .git/FETCH_HEAD.  Copy it in
+     .git/refs/heads/upstream.
+
+ (5) Use "git cherry" to see which ones of your patches were
+     accepted, and/or use "git rebase" to port your unmerged
+     changes forward to the updated upstream.
+
+ (6) Use "git format-patch upstream" to prepare patches for
+     e-mail submission to your upstream and send it out.
+     Go back to step (3) and continue. 
+
+[Side Note: I think Cogito calls this upstream "origin".
+ Somebody care to confirm or deny?  ]
+
+
+[ to be continued.. cvsimports ]

[PATCH] fetch/pull: support Cogito-style remote branch information.

[Junio C Hamano]

Since pull and fetch are done often against the same remote
repository, keeping the URL to pull from along with the name of
the head in $GIT_DIR/branches/$name like Cogito does makes a lot
of sense.  Adopt that and be compatible with Cogito for usability.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

*** Although I have tested it to see the change does what it
*** advertises to do, I would like to hear comments from the
*** list if things like this would be good to have in the
*** barebone Porcelain.  I personally think this is a good
*** usability enhancement without complicating it too much.

 Documentation/git-fetch-script.txt |   40 +++++++++++++++++++++++++++
 Documentation/git-pull-script.txt  |   20 +++++++++++--
 Documentation/git.txt              |    9 +++++-
 Documentation/tutorial.txt         |   13 +++++++++
 git-fetch-script                   |   44 +++++++++++++++++++++++------
 git-pull-script                    |   54 +++++++++++++++++++++++++++---------
 6 files changed, 152 insertions(+), 28 deletions(-)
 create mode 100644 Documentation/git-fetch-script.txt

804f1002c007106fb1aeade4b4549169e92042a2
diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/git-fetch-script.txt
@@ -0,0 +1,40 @@
+git-fetch-script(1)
+===================
+v0.1, July 2005
+
+NAME
+----
+git-fetch-script - Download objects and a head from another repository.
+
+
+SYNOPSIS
+--------
+'git-fetch-script' <repository> [ <head> | tag <tag> ]
+
+'git-fetch-script' -b <name>
+
+
+DESCRIPTION
+-----------
+Fetches a named head or a tag from another repository, along
+with the objects necessary to complete that head or tag.  The
+head to pull defaults to HEAD if unspecified.
+
+When '-b' flag is specified to give a name, not an URL to the
+repository, it reads from .git/branches/<name> to get the
+repository URL, possibly immediately followed by '#' and the
+name of the head or the tag.  The latter is meant to make this
+command a bit more Cogito-user friendly.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the link:git.html[git] suite
diff --git a/Documentation/git-pull-script.txt b/Documentation/git-pull-script.txt
--- a/Documentation/git-pull-script.txt
+++ b/Documentation/git-pull-script.txt
@@ -4,17 +4,29 @@ v0.1, May 2005
 
 NAME
 ----
-git-pull-script - Script used by Linus to pull and merge a remote repository
+git-pull-script - Pull and merge from another repository.
 
 
 SYNOPSIS
 --------
-'git-pull-script'
+'git-pull-script' <repository> [ <head> | tag <tag> ]
+
+'git-pull-script' -b <name>
+
 
 DESCRIPTION
 -----------
-This script is used by Linus to pull from a remote repository and perform
-a merge.
+Fetches a named head or a tag from another repository, along
+with the objects necessary to complete that head or tag, and
+merges it into the current repository by running
+'git-resolve-script'.  The head to pull defaults to HEAD if
+unspecified.
+
+When '-b' flag is specified to give a name, not an URL to the
+repository, it reads from .git/branches/<name> to get the
+repository URL, possibly immediately followed by '#' and the
+name of the head or the tag.  The latter is meant to make this
+command a bit more Cogito-user friendly.
 
 
 Author
diff --git a/Documentation/git.txt b/Documentation/git.txt
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -121,6 +121,9 @@ The interrogate commands may create file
 touch the working file set - but in general they don't
 
 
+Synching multiple repositories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 link:git-clone-script.html[git-clone-script]::
 	Clones a repository into the current repository (user interface)
 
@@ -128,10 +131,14 @@ link:git-clone-pack.html[git-clone-pack]
 	Clones a repository into the current repository (engine
 	for ssh and local transport)
 
-link:git-pull-script.html[git-pull-script]::
+link:git-fetch-script.html[git-pull-script]::
 	Pull from a repote repository via various protocols
 	(user interface).
 
+link:git-pull-script.html[git-pull-script]::
+	Fetch from and merge with a repote repository via
+	various protocols (user interface).
+
 link:git-http-pull.html[git-http-pull]::
 	Downloads a remote GIT repository via HTTP
 
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -810,6 +810,19 @@ pull from:
   course, you will pay the price of more disk usage to hold
   multiple working trees, but disk space is cheap these days.  ]
 
+It is likely that you will be pulling from the same remote
+repository from time to time.  As a short hand, you can store
+the remote repository URL in a file under .git/branches/
+directory, like this:
+
+	mkdir -p .git/branches
+	echo rsync://rsync.kernel.org/pub/scm/git/git.git/ \
+	    >.git/branches/linus
+
+and give "-b" option to "git pull" to use that URL:
+
+	git pull -b linus
+
 
 	Publishing your work
 	--------------------
diff --git a/git-fetch-script b/git-fetch-script
--- a/git-fetch-script
+++ b/git-fetch-script
@@ -1,23 +1,47 @@
 #!/bin/sh
 #
-destination=FETCH_HEAD
-
-merge_repo=$1
-merge_name=${2:-HEAD}
-if [ "$2" = "tag" ]; then
-	merge_name="refs/tags/$3"
-	destination="$merge_name"
-fi
 
 . git-sh-setup-script || die "Not a git archive"
 
+destination=FETCH_HEAD
+
+case "$1" in
+-b)
+	# Using Cogito style remote branch information.
+	# The user did not call us via git-pull, but just wants to
+	# fetch from the remote head.
+	name=$2 &&
+	destination=refs/heads/"$name" &&
+	remote_branch=$(cat "$GIT_DIR/branches/$name") ||
+	die "cannot read remote branch $name."
+	case "$remote_branch" in
+	*'#'*)
+		merge_repo=$(expr "$remote_branch" : '\(.*\)#') &&
+		merge_name=$(expr "$remote_branch" : '.*#\(.*\)$')
+		;;
+        *)
+		merge_repo="$remote_branch" &&
+		merge_name=HEAD
+		;;
+	esac
+	;;
+*)
+	merge_repo=$1
+	merge_name=${2:-HEAD}
+	if [ "$2" = "tag" ]; then
+		merge_name="refs/tags/$3"
+		destination="$merge_name"
+	fi
+	;;
+esac
+
 TMP_HEAD="$GIT_DIR/TMP_HEAD"
 
 case "$merge_repo" in
 http://*)
 	head=$(wget -q -O - "$merge_repo/$merge_name") || exit 1
-	echo Fetching $head using http
-	git-http-pull -v -a "$head" "$merge_repo/"
+	echo Fetching $merge_name using http
+	git-http-pull -v -a "$merge_name" "$merge_repo/"
 	;;
 rsync://*)
 	rsync -L "$merge_repo/$merge_name" "$TMP_HEAD" || exit 1
diff --git a/git-pull-script b/git-pull-script
--- a/git-pull-script
+++ b/git-pull-script
@@ -2,20 +2,48 @@
 #
 . git-sh-setup-script || die "Not a git archive"
 
-merge_repo=$1
+usage () {
+    echo >&2 "* git pull <repo> [ <head> | tag <tag> ]"
+    echo >&2 "* git pull -b <name>"
+    exit 1
+}
 
-merge_name=$(echo "$1" | sed 's:\.git/*$::')
-merge_head=HEAD
-type=head
-if [ "$2" = "tag" ]; then
-   type=tag
-   shift
-fi
-if [ "$2" ]
-then
-   merge_name="$type '$2' of $merge_name"
-   merge_head="refs/${type}s/$2"
-fi
+case "$1" in
+-b)
+	# Use Cogito style remote branch information.
+	name=$2 &&
+	remote_branch=$(cat "$GIT_DIR/branches/$name") ||
+	die "cannot read remote branch $name."
+	case "$remote_branch" in
+	*'#'*)
+		merge_repo=$(expr "$remote_branch" : '\(.*\)#') &&
+		merge_head=$(expr "$remote_branch" : '.*#\(.*\)$') &&
+		merge_name=$(echo "$merge_repo" | sed 's:\.git/*$::') &&
+		merge_name="'$merge_head' of $merge_name"
+		;;
+        *)
+		merge_head=HEAD &&
+		merge_repo="$remote_branch" &&
+		merge_name=$(echo "$merge_repo" | sed 's:\.git/*$::')
+		;;
+	esac
+	;;
+*)
+	merge_repo=$1
+	merge_name=$(echo "$merge_repo" | sed 's:\.git/*$::')
+	merge_head=HEAD
+	type=head
+	if [ "$2" = "tag" ]; then
+		type=tag
+		shift
+	fi
+	if [ "$2" ]
+	then
+		merge_name="$type '$2' of $merge_name"
+		merge_head="refs/${type}s/$2"
+	fi
+	;;
+esac
 
 git-fetch-script "$merge_repo" "$merge_head" || exit 1
 

Re: [PATCH] fetch/pull: support Cogito-style remote branch information.

[Linus Torvalds]

Hmm..

This patch actually brings up two different issues

 - I actually prefer code and documentation to be separated. Finding the 
   actual changes to code in this patch is made much harder by the fact
   that most of the changes are documentation updates. In many ways it 
   would have been nicer to separate the two out - first the actual 
   change, then the docs updates.

   Maybe that's just me.

 - I'd much rather have a generic "address rewriting layer" than a "-b" 
   flag.

   I don't mind the shorthand at all, but I don't think it should be that
   special. It's not "worthy" of a flag - if you have a shorthand that 
   says "linus == rsync://kernel.org/pub/scm/git/git.git", then I think it 
   should just work, and 

	git pull linus

   should end up not needing a "-b" flag. It's not like there is any 
   real ambiguity.

Now, I'd like the address rewriting to actually be fairly capable, so it 
should be a script of its own.

And it's not necessarily just the branch handling, but more of a generic
shorthand: I'd love to be able to mix something like

	git pull jgarzik/misc-2.6 upstream

and "jgarzik" would be expanded (through something like .git/branches) to 
"master.kernel.org:/pub/scm/linux/kernel/git/jgarzik/"), resulting in the 
_full_ path being expanded to

	master.kernel.org:/pub/scm/linux/kernel/git/jgarzik/misc-2.6 upstream

which I have to write out in full (or, more commonly, cut-and-paste) right
now.

Hmm?

		Linus

Re: [PATCH] fetch/pull: support Cogito-style remote branch information.

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

>  - I actually prefer code and documentation to be separated. ...
>    first the actual change, then the docs updates.

Understood.

>  - I'd much rather have a generic "address rewriting layer" than a "-b" 
>    flag.
>
>    I don't mind the shorthand at all, but I don't think it should be that
>    special. It's not "worthy" of a flag - if you have a shorthand that 
>    says "linus == rsync://kernel.org/pub/scm/git/git.git", then I think it 
>    should just work, and 
>
> 	git pull linus
>
>    should end up not needing a "-b" flag. It's not like there is any 
>    real ambiguity.

That makes sense.  Naturally,

	git pull linus experimental
        git pull linus tag v2.6.13

should expand to:

       git pull rsync://kernel.org/pub/scm/git/git.git/ experimental
       git pull rsync://kernel.org/pub/scm/git/git.git/ tag v2.6.13

If a user is usually interested in e100 driver work, we should
allow:

	echo rsync://kernel.org/pub/.../git/jgarzik/netdev-2.6.git#e100
	        >.git/branches/jgarzik-e100

and "git pull jgarzik-e100" should expand to:

	git pull rsync://kernel.org/pub/.../netdev-2.6.git/ e100

If the user says:

	git fetch jgarzik-e100 ieee80211-wifi

because the user wanted to peek his other branch just once, but
did not want to bother creating another remote reference
("jgarzik-wifi", perhaps) for this one-time use.  This should
expand to:

	git fetch rsync://kernel.org/pub/.../netdev-2.6.git/ ieee80211-wifi

> And it's not necessarily just the branch handling, but more of a generic
> shorthand: I'd love to be able to mix something like
>
> 	git pull jgarzik/misc-2.6 upstream
>
> and "jgarzik" would be expanded (through something like .git/branches) to 
> "master.kernel.org:/pub/scm/linux/kernel/git/jgarzik/"), resulting in the 
> _full_ path being expanded to
>
> 	master.kernel.org:/pub/scm/linux/kernel/git/jgarzik/misc-2.6 upstream

Nice, and sounds doable without too much ambiguities.  This last
one, however, needs to be coordinated with Pasky, if we want to
use .git/branches/$name convention.  I think Cogito would barf
with your partial URL that ends with "...git/jgarzik/".

I'll code something up.

[PATCH] Documentation: adjust cvsimport command line.

[Junio C Hamano]

The cvsimport example in the cvs migration document was still
using the old syntax for target repository after new and
improved cvsimport-script was merged.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/cvs-migration.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

b29d86237da6af317cd0053aa9c8ebd72455c113
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -63,7 +63,7 @@ Once you've gotten (and installed) cvsps
 any more familiar with it, but make sure it is in your path. After that,
 the magic command line is
 
-	git cvsimport -v -d <cvsroot> <module> <destination>
+	git cvsimport -v -d <cvsroot> -C <destination> <module>
 
 which will do exactly what you'd think it does: it will create a git
 archive of the named CVS module. The new archive will be created in the

[PATCH] fetch/pull: short-hand notation for remote repositories.

[Junio C Hamano]

Since pull and fetch are done often against the same remote
repository repeatedly, keeping the URL to pull from along with
the name of the head to use in $GIT_DIR/branches/$name makes a
lot of sense.  Adopt that convention from Cogito, and try to be
compatible when possible; storing a partial URL and completing
it with a trailing path may not be understood by Cogito.

While we are at it, fix pulling a tag.  Earlier, we updated only
refs/tags/$tag without updating FETCH_HEAD, and called
resolve-script using a stale (or absent) FETCH_HEAD.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Makefile         |    2 +
 git-fetch-script |   36 ++++++++++++++-----------
 git-parse-remote |   79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 git-pull-script  |   19 ++-----------
 4 files changed, 104 insertions(+), 32 deletions(-)
 create mode 100755 git-parse-remote

431b72ee18b73aac44048ac6c4cb62e0618c6f6e
diff --git a/Makefile b/Makefile
--- a/Makefile
+++ b/Makefile
@@ -36,7 +36,7 @@ SCRIPTS=git git-apply-patch-script git-m
 	git-reset-script git-add-script git-checkout-script git-clone-script \
 	gitk git-cherry git-rebase-script git-relink-script git-repack-script \
 	git-format-patch-script git-sh-setup-script git-push-script \
-	git-branch-script
+	git-branch-script git-parse-remote
 
 PROG=   git-update-cache git-diff-files git-init-db git-write-tree \
 	git-read-tree git-commit-tree git-cat-file git-fsck-cache \
diff --git a/git-fetch-script b/git-fetch-script
--- a/git-fetch-script
+++ b/git-fetch-script
@@ -1,33 +1,39 @@
 #!/bin/sh
 #
-destination=FETCH_HEAD
-
-merge_repo=$1
-merge_name=${2:-HEAD}
-if [ "$2" = "tag" ]; then
-	merge_name="refs/tags/$3"
-	destination="$merge_name"
-fi
-
 . git-sh-setup-script || die "Not a git archive"
+. git-parse-remote "$@"
+merge_repo="$_remote_repo"
+merge_head="$_remote_head"
+merge_store="$_remote_store"
 
 TMP_HEAD="$GIT_DIR/TMP_HEAD"
 
 case "$merge_repo" in
 http://*)
-	head=$(wget -q -O - "$merge_repo/$merge_name") || exit 1
-	echo Fetching $head using http
-	git-http-pull -v -a "$head" "$merge_repo/"
+	head=$(wget -q -O - "$merge_repo/$merge_head") || exit 1
+	echo Fetching "$merge_head" using http
+	git-http-pull -v -a "$merge_head" "$merge_repo/"
 	;;
 rsync://*)
-	rsync -L "$merge_repo/$merge_name" "$TMP_HEAD" || exit 1
+	rsync -L "$merge_repo/$merge_head" "$TMP_HEAD" || exit 1
 	head=$(git-rev-parse TMP_HEAD)
 	rm -f "$TMP_HEAD"
 	rsync -avz --ignore-existing "$merge_repo/objects/" "$GIT_OBJECT_DIRECTORY/"
 	;;
 *)
-	head=$(git-fetch-pack "$merge_repo" "$merge_name")
+	head=$(git-fetch-pack "$merge_repo" "$merge_head")
 	;;
 esac || exit 1
+
 git-rev-parse --verify "$head" > /dev/null || exit 1
-echo "$head" > "$GIT_DIR/$destination"
+
+case "$merge_store" in
+'')
+	echo "$head" > "$GIT_DIR/$merge_store"
+esac &&
+
+# FETCH_HEAD is fed to git-resolve-script which will eventually be
+# passed to git-commit-tree as one of the parents.  Make sure we do
+# not give a tag object ID.
+
+git-rev-parse "$head^0" >"$GIT_DIR/FETCH_HEAD"
diff --git a/git-parse-remote b/git-parse-remote
new file mode 100755
--- /dev/null
+++ b/git-parse-remote
@@ -0,0 +1,79 @@
+: To be included in git-pull and git-fetch scripts.
+
+# A remote repository can be specified on the command line
+# in one of the following formats:
+#
+#	<repo>
+#	<repo> <head>
+#	<repo> tag <tag>
+#
+# where <repo> could be one of:
+#
+#	a URL (including absolute or local pathname)
+#	a short-hand
+#	a short-hand followed by a trailing path
+#
+# A short-hand <name> has a corresponding file $GIT_DIR/branches/<name>,
+# whose contents is a URL, possibly followed by a URL fragment #<head>
+# to name the default branch on the remote side to fetch from.
+
+_remote_repo= _remote_store= _remote_head= _remote_name=
+
+case "$1" in
+*:* | /* | ../* | ./* )
+	_remote_repo="$1"
+	;;
+* )
+	# otherwise, it is a short hand.
+	case "$1" in
+	*/*)
+		# a short-hand followed by a trailing path
+		_token=$(expr "$1" : '\([^/]*\)/')
+		_rest=$(expr "$1" : '[^/]*\(/.*\)$')
+		;;
+	*)
+		_token="$1"
+		_rest=
+		_remote_store="refs/heads/$_token"
+		;;
+	esac
+	test -f "$GIT_DIR/branches/$_token" ||
+	die "No such remote branch: $_token"
+
+	_remote_repo=$(cat "$GIT_DIR/branches/$_token")"$_rest"
+	;;
+esac
+
+case "$_remote_repo" in
+*"#"*)
+	_remote_head=`expr "$_remote_repo" : '.*#\(.*\)$'`
+	_remote_repo=`expr "$_remote_repo" : '\(.*\)#'`
+	;;
+esac
+
+_remote_name=$(echo "$_remote_repo" | sed 's|\.git/*$||')
+
+case "$2" in
+tag)
+	_remote_name="tag '$3' of $_remote_name"
+	_remote_head="refs/tags/$3"
+	_remote_store="$_remote_head"
+	;;
+?*)
+	# command line specified a head explicitly; do not
+	# store the fetched head as a branch head.
+	_remote_name="head '$2' of $_remote_name"
+	_remote_head="refs/heads/$2"
+	_remote_store=''
+	;;
+'')
+	case "$_remote_head" in
+	'')
+		_remote_head=HEAD ;;
+	*)
+		_remote_head="refs/heads/$_remote_head"
+		_remote_name="head '$_remote_head' of $_remote_name"
+		;;
+	esac
+	;;
+esac
diff --git a/git-pull-script b/git-pull-script
--- a/git-pull-script
+++ b/git-pull-script
@@ -1,23 +1,10 @@
 #!/bin/sh
 #
 . git-sh-setup-script || die "Not a git archive"
+. git-parse-remote "$@"
+merge_name="$_remote_name"
 
-merge_repo=$1
-
-merge_name=$(echo "$1" | sed 's:\.git/*$::')
-merge_head=HEAD
-type=head
-if [ "$2" = "tag" ]; then
-   type=tag
-   shift
-fi
-if [ "$2" ]
-then
-   merge_name="$type '$2' of $merge_name"
-   merge_head="refs/${type}s/$2"
-fi
-
-git-fetch-script "$merge_repo" "$merge_head" || exit 1
+git-fetch-script "$@" || exit 1
 
 git-resolve-script \
 	"$(cat "$GIT_DIR"/HEAD)" \

[PATCH] Documentation: describe short-hand used in fetch/pull.

[Junio C Hamano]

Describe short-hand for remote repository used in fetch/pull.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/git-fetch-script.txt |   47 ++++++++++++++++++++++++++++++++++++
 Documentation/git-pull-script.txt  |   16 ++++++++----
 Documentation/git.txt              |    9 ++++++-
 Documentation/pull-fetch-param.txt |   36 ++++++++++++++++++++++++++++
 Documentation/tutorial.txt         |   28 +++++++++++++++++++++
 5 files changed, 130 insertions(+), 6 deletions(-)
 create mode 100644 Documentation/git-fetch-script.txt
 create mode 100644 Documentation/pull-fetch-param.txt

d4d1afc8c8e8417b8a30ecfc8f5e32be2b47c956
diff --git a/Documentation/git-fetch-script.txt b/Documentation/git-fetch-script.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/git-fetch-script.txt
@@ -0,0 +1,47 @@
+git-fetch-script(1)
+===================
+v0.1, July 2005
+
+NAME
+----
+git-fetch-script - Download objects and a head from another repository.
+
+
+SYNOPSIS
+--------
+'git-fetch-script' <repository> [ <head> | tag <tag> ]
+
+
+DESCRIPTION
+-----------
+Fetches a named head or a tag from another repository, along
+with the objects necessary to complete that head or tag.  The
+head to pull defaults to HEAD if unspecified.  The head or tag
+fetched from the remote repository is stored in
+$GIT_DIR/FETCH_HEAD.
+
+When a <tag> is specified, the <tag> fetched from the remote is
+also copied to the local $GIT_DIR/tags/<tag> file.  When no
+<head> nor <tag> is specified, and <repository> was specified
+with the short-hand notation (i.e. naming a file under the
+$GIT_DIR/branches directory), the head fetched from the remote
+repository is also copied to the local $GIT_DIR/heads/<repository>
+file.
+
+
+OPTIONS
+-------
+include::pull-fetch-param.txt[]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the link:git.html[git] suite
diff --git a/Documentation/git-pull-script.txt b/Documentation/git-pull-script.txt
--- a/Documentation/git-pull-script.txt
+++ b/Documentation/git-pull-script.txt
@@ -4,22 +4,28 @@ v0.1, May 2005
 
 NAME
 ----
-git-pull-script - Script used by Linus to pull and merge a remote repository
+git-pull-script - Pull and merge from another repository.
 
 
 SYNOPSIS
 --------
-'git-pull-script'
+'git-pull-script' <repository> [ <head> | tag <tag> ]
+
 
 DESCRIPTION
 -----------
-This script is used by Linus to pull from a remote repository and perform
-a merge.
+Runs 'git-fetch-script' with the given parameters, then
+'git-resolve-script' to merge the local HEAD and FETCH_HEAD.
+
+
+OPTIONS
+-------
+include::pull-fetch-param.txt[]
 
 
 Author
 ------
-Written by Linus Torvalds <torvalds@osdl.org>
+Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
 
 Documentation
 --------------
diff --git a/Documentation/git.txt b/Documentation/git.txt
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -121,6 +121,9 @@ The interrogate commands may create file
 touch the working file set - but in general they don't
 
 
+Synching repositories
+~~~~~~~~~~~~~~~~~~~~~
+
 link:git-clone-script.html[git-clone-script]::
 	Clones a repository into the current repository (user interface)
 
@@ -128,10 +131,14 @@ link:git-clone-pack.html[git-clone-pack]
 	Clones a repository into the current repository (engine
 	for ssh and local transport)
 
-link:git-pull-script.html[git-pull-script]::
+link:git-fetch-script.html[git-pull-script]::
 	Pull from a repote repository via various protocols
 	(user interface).
 
+link:git-pull-script.html[git-pull-script]::
+	Fetch from and merge with a repote repository via
+	various protocols (user interface).
+
 link:git-http-pull.html[git-http-pull]::
 	Downloads a remote GIT repository via HTTP
 
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
new file mode 100644
--- /dev/null
+++ b/Documentation/pull-fetch-param.txt
@@ -0,0 +1,36 @@
+<repository>::
+	The "remote" repository to pull from.  One of the
+	following notations can be used to name the repository
+	to pull from:
+
+		Rsync URL
+			rsync://remote.machine/path/to/repo.git/
+
+		HTTP(s) URL
+			http://remote.machine/path/to/repo.git/
+
+		GIT URL
+			git://remote.machine/path/to/repo.git/
+			remote.machine:/path/to/repo.git/
+
+		Local directory
+			/path/to/repo.git/
+
+	In addition to that, as a short-hand, the name of a file
+	in $GIT_DIR/branches directory can be specified; the
+	named file should contain a single line, a URL in one of
+	the above formats, optionally followed by a hash '#' and
+	the name of remote head.
+
+<head>::
+	The remote head name to fetch from.  That is, make the
+	objects reachable from the commit recorded in
+	$GIT_DIR/refs/heads/<head> in the remote repository
+	available locally.
+
+tag <tag>::
+	The remote head tag to fetch from.  That is, make the
+	objects reachable from the commit recorded in
+	$GIT_DIR/refs/tags/<tag> in the remote repository
+	available locally.
+
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -810,6 +810,34 @@ pull from:
   course, you will pay the price of more disk usage to hold
   multiple working trees, but disk space is cheap these days.  ]
 
+It is likely that you will be pulling from the same remote
+repository from time to time.  As a short hand, you can store
+the remote repository URL in a file under .git/branches/
+directory, like this:
+
+	mkdir -p .git/branches
+	echo rsync://kernel.org/pub/scm/git/git.git/ \
+	    >.git/branches/linus
+
+and use the filenae to "git pull" instead of the full URL.
+The contents of a file under .git/branches can even be a prefix
+of a full URL, like this:
+
+	echo rsync://kernel.org/pub/.../jgarzik/
+	        >.git/branches/jgarzik
+
+Examples.
+
+	(1) git pull linus
+	(2) git pull linus tag v0.99.1
+	(3) git pull jgarzik/netdev-2.6.git/ e100
+
+the above are equivalent to:
+
+	(1) git pull rsync://kernel.org/pub/scm/git/git.git/ HEAD
+	(2) git pull rsync://kernel.org/pub/scm/git/git.git/ tag v0.99.1
+	(3) git pull rsync://kernel.org/pub/.../jgarzik/netdev-2.6.git e100
+
 
 	Publishing your work
 	--------------------

[PATCH-fix] fetch/pull: short-hand notation for remote repositories.

[Junio C Hamano]

The logic to decide when to store fetched head/tag under
$GIT_DIR/refs/, and http transport were broken in the previous
round. 

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

*** I see you have already merged my broken one; sorry.

*** Anything written under the influence should be tested as twice
*** as hard than usual before being sent --- Don't drink and
*** develop ;-).  *Blush*

cd /opt/packrat/playpen/public/in-place/git/git.junio/
jit-diff 8:10
# - 4: Documentation: describe short-hand used in fetch/pull.
# + 6: git-fetch-script: fix thinko in http fetch.
diff --git a/git-fetch-script b/git-fetch-script
--- a/git-fetch-script
+++ b/git-fetch-script
@@ -12,7 +12,7 @@ case "$merge_repo" in
 http://*)
 	head=$(wget -q -O - "$merge_repo/$merge_head") || exit 1
 	echo Fetching "$merge_head" using http
-	git-http-pull -v -a "$merge_head" "$merge_repo/"
+	git-http-pull -v -a "$head" "$merge_repo/"
 	;;
 rsync://*)
 	rsync -L "$merge_repo/$merge_head" "$TMP_HEAD" || exit 1
@@ -27,10 +27,10 @@ esac || exit 1
 
 git-rev-parse --verify "$head" > /dev/null || exit 1
 
-case "$merge_store" in
-'')
+if test "$merge_store"
+then
 	echo "$head" > "$GIT_DIR/$merge_store"
-esac &&
+fi &&
 
 # FETCH_HEAD is fed to git-resolve-script which will eventually be
 # passed to git-commit-tree as one of the parents.  Make sure we do

Compilation finished at Sat Jul 16 09:37:07

Re: [PATCH-fix] fetch/pull: short-hand notation for remote repositories.

[Linus Torvalds]

On Sat, 16 Jul 2005, Junio C Hamano wrote:
> 
> *** I see you have already merged my broken one; sorry.

I already noticed the breakage, and fixed that a bit differently.

Feel free to send an updated patch if you prefer your version after my 
commits have percolated out..

		Linus

Re: [PATCH-fix] fetch/pull: short-hand notation for remote repositories.

[Junio C Hamano]

Linus Torvalds <torvalds@osdl.org> writes:

> I already noticed the breakage, and fixed that a bit differently.
>
> Feel free to send an updated patch if you prefer your version after my 
> commits have percolated out..

As an old timer, I always prefer "case" over "test", so the
version in your tree is actually better to me.  Thanks for the
fix.

[PATCH] git-clone-script: store where we cloned from in .git/branches/origin

[Junio C Hamano]

A bit more usability enhancement related to the recent URL
short-hand support in .git/branches, while retaining Cogito
compatibility.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 git-clone-script |   41 +++++++++++++++++++++++------------------
 1 files changed, 23 insertions(+), 18 deletions(-)

cb70e0d83c336e0fc3485b6c823b948c07d15a12
diff --git a/git-clone-script b/git-clone-script
--- a/git-clone-script
+++ b/git-clone-script
@@ -20,12 +20,12 @@ upload_pack=
 while
 	case "$#,$1" in
 	0,*) break ;;
-        *,-l|*,--l|*,--lo|*,--loc|*,--loca|*,--local) use_local=yes ;;
+	*,-l|*,--l|*,--lo|*,--loc|*,--loca|*,--local) use_local=yes ;;
 	*,-q|*,--quiet) quiet=-q ;;
-	1,-u|*,--upload-pack) usage ;;
+	1,-u|1,--upload-pack) usage ;;
 	*,-u|*,--upload-pack)
 		shift
-		upload_pack="--exec=$2" ;;
+		upload_pack="--exec=$1" ;;
 	*,-*) usage ;;
 	*) break ;;
 	esac
@@ -81,23 +81,28 @@ yes,yes)
 		HEAD=HEAD
 	fi
 	tar Ccf "$repo" - refs $HEAD | tar Cxf "$D/.git" - || exit 1
-	exit 0
-	;;
-esac
-
-case "$repo" in
-rsync://*)
-	rsync $quiet -avz --ignore-existing "$repo/objects/" "$D/.git/objects/" &&
-	rsync $quiet -avz --ignore-existing "$repo/refs/" "$D/.git/refs/"
-	;;
-http://*)
-	echo "Somebody should add http fetch" >&2
-	exit 1
 	;;
 *)
-	cd "$D" && case "$upload_pack" in
-	'') git-clone-pack $quiet "$repo" ;;
-	*) git-clone-pack $quiet "$upload_pack" "$repo" ;;
+	case "$repo" in
+	rsync://*)
+		rsync $quiet -avz --ignore-existing "$repo/objects/" "$D/.git/objects/" &&
+		rsync $quiet -avz --ignore-existing "$repo/refs/" "$D/.git/refs/"
+		;;
+	http://*)
+		echo "Somebody should add http fetch" >&2
+		exit 1
+		;;
+	*)
+		cd "$D" && case "$upload_pack" in
+		'') git-clone-pack $quiet "$repo" ;;
+		*) git-clone-pack $quiet "$upload_pack" "$repo" ;;
+		esac
+		;;
 	esac
 	;;
 esac
+
+# Update origin.
+mkdir -p "$D/.git/branches/" &&
+rm -f "$D/.git/branches/origin" &&
+echo "$repo" >"$D/.git/branches/origin"

[PATCH] tutorial: mention "git clone" records .git/branches/origin

[Junio C Hamano]

Update the recommended workflow for individual developers.
While they are tracking the origin, refs/heads/origin is updated
by "git fetch", so there is no need to manually copy FETCH_HEAD
to refs/heads/ anywhere.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 Documentation/tutorial.txt |   48 ++++++++++++++++++++------------------------
 1 files changed, 22 insertions(+), 26 deletions(-)

6af33a52163dd15beaaf610f6b7506b900189770
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -1042,7 +1042,8 @@ A recommended work cycle for a "subsyste
 on that project and has own "public repository" goes like this:
 
  (1) Prepare your work repository, by "git clone" the public
-     repository of the "project lead".
+     repository of the "project lead".  The URL used for the
+     initial cloning is stored in .git/branches/origin.
 
  (2) Prepare a public repository accessible to others.
 
@@ -1051,7 +1052,7 @@ on that project and has own "public repo
      currently not automated.
 
  (4) Push into the public repository from your primary
-     repository.  Run "git repack" (and possibly "git
+     repository.  Run "git repack", and possibly "git
      prune-packed" if the transport used for pulling from your
      repository supports packed repositories.
 
@@ -1076,30 +1077,25 @@ A recommended work cycle for an "individ
 not have a "public" repository is somewhat different.  It goes
 like this:
 
- (1) Prepare your work repositories, by "git clone" the public
-     repository of the "project lead" (or "subsystem
-     maintainer", if you work on a subsystem).
-
- (2) Copy .git/refs/master to .git/refs/upstream.
-
- (3) Do your work there.  Make commits.
-
- (4) Run "git fetch" from the public repository of your upstream
-     every once in a while.  This does only the first half of
-     "git pull" but does not merge.  The head of the public
-     repository is stored in .git/FETCH_HEAD.  Copy it in
-     .git/refs/heads/upstream.
-
- (5) Use "git cherry" to see which ones of your patches were
-     accepted, and/or use "git rebase" to port your unmerged
-     changes forward to the updated upstream.
-
- (6) Use "git format-patch upstream" to prepare patches for
-     e-mail submission to your upstream and send it out.
-     Go back to step (3) and continue. 
-
-[Side Note: I think Cogito calls this upstream "origin".
- Somebody care to confirm or deny?  ]
+ (1) Prepare your work repository, by "git clone" the public
+     repository of the "project lead" (or a "subsystem
+     maintainer", if you work on a subsystem).  The URL used for
+     the initial cloning is stored in .git/branches/origin.
+
+ (2) Do your work there.  Make commits.
+
+ (3) Run "git fetch origin" from the public repository of your
+     upstream every once in a while.  This does only the first
+     half of "git pull" but does not merge.  The head of the
+     public repository is stored in .git/refs/heads/origin.
+
+ (4) Use "git cherry origin" to see which ones of your patches
+     were accepted, and/or use "git rebase origin" to port your
+     unmerged changes forward to the updated upstream.
+
+ (5) Use "git format-patch origin" to prepare patches for e-mail
+     submission to your upstream and send it out.  Go back to
+     step (2) and continue.
 
 
 [ to be continued.. cvsimports ]