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
-----------------
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"
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
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
and optionally give a branch-name for the remote end as a second
argument.
-[ Todo: fill in real examples ]
+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/
- Tagging a version
- -----------------
+ HTTP(s) URL
+ http://remote.machine/path/to/repo.git/
-In git, there's two kinds of tags, a "light" one, and a "signed tag".
+ GIT URL
+ git://remote.machine/path/to/repo.git/
+ remote.machine:/path/to/repo.git/
-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
+ Local directory
+ /path/to/repo.git/
- cat .git/HEAD > .git/refs/tags/my-first-tag
+[ 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. ]
-after which point you can use this symbolic name for that particular
-state. You can, for example, do
+[ 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. ]
- 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.
+ Publishing your work
+ --------------------
-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
+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 do your real work in your working directory that has your
+primary repository hanging under it as its ".git" subdirectory.
+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 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
+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, 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 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 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. "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 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. ]
- 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").
+ 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? ]
-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 ]
+[ to be continued.. cvsimports ]