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
+ git tag my-first-tag
-after which point you can use this symbolic name for that particular
-state. You can, for example, do
+which just writes the current HEAD into the .git/refs/tags/my-first-tag
+file, after which point you can then use this symbolic name for that
+particular state. You can, for example, do
git diff my-first-tag
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
+that tag. You create these signed tags with the "-s" flag to "git tag":
- git tag <tagname>
+ git tag -s <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
---------------------
Branches in git are really nothing more than pointers into the git
-object space from within the ",git/refs/" subdirectory, and as we
+object space from within the ".git/refs/" subdirectory, and as we
already discussed, the HEAD branch is nothing but a symlink to one of
these object pointers.
and nothing enforces it.
To show that as an example, let's go back to the git-tutorial archive we
-used earlier, and create a branch in it. You literally do that by just
-creating a new SHA1 reference file, and switch to it by just making the
-HEAD pointer point to it:
+used earlier, and create a branch in it. You do that by simply just
+saying that you want to check out a new branch:
- cat .git/HEAD > .git/refs/heads/mybranch
- ln -sf refs/heads/mybranch .git/HEAD
+ git checkout -b mybranch
-and you're done.
+will create a new branch based at the current HEAD position, and switch
+to it.
-Now, if you make the decision to start your new branch at some other
-point in the history than the current HEAD, you usually also want to
-actually switch the contents of your working directory to that point
-when you switch the head, and "git checkout" will do that for you:
-instead of switching the branch by hand with "ln -sf", you can just do
+[ Side note: if you make the decision to start your new branch at some
+ other point in the history than the current HEAD, you can do so by
+ just telling "git checkout" what the base of the checkout would be.
+ In other words, if you have an earlier tag or branch, you'd just do
- git checkout mybranch
+ git checkout -b mybranch earlier-branch
-which will basically "jump" to the branch specified, update your working
-directory to that state, and also make it become the new default HEAD.
+ and it would create the new branch "mybranch" at the earlier point,
+ and check out the state at that time. ]
You can always just jump back to your original "master" branch by doing
git checkout master
-and if you forget which branch you happen to be on, a simple
+(or any other branch-name, for that matter) and if you forget which
+branch you happen to be on, a simple
ls -l .git/HEAD
will tell you where it's pointing.
+NOTE! Sometimes you may wish to create a new branch _without_ actually
+checking it out and switching to it. If so, just use the command
+
+ git branch <branchname> [startingpoint]
+
+which will simply _create_ the branch, but will not do anything further.
+You can then later - once you decide that you want to actually develop
+on that branch - switch to that branch with a regular "git checkout"
+with the branchname as the argument.
+
Merging two branches
--------------------
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
--------------------
Working with Others
-------------------
-A recommended work cycle for a "project lead" is like this:
+Although git is a truly distributed system, it is often
+convenient to organize your project with an informal hierarchy
+of developers. Linux kernel development is run this way. There
+is a nice illustration (page 17, "Merges to Mainline") in Randy
+Dunlap's presentation (http://tinyurl.com/a2jdg).
+
+It should be stressed that this hierarchy is purely "informal".
+There is nothing fundamental in git that enforces the "chain of
+patch flow" this hierarchy implies. You do not have to pull
+from only one remote repository.
+
+
+A recommended workflow for a "project lead" goes like this:
(1) Prepare your primary repository on your local machine. Your
work is done there.
repository.
(4) "git repack" the public repository. This establishes a big
- pack that contains the initial set of objects.
+ pack that contains the initial set of objects as the
+ baseline, and possibly "git prune-packed" if the transport
+ used for pulling from your repository supports packed
+ repositories.
- (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".
+ (5) Keep working in your primary repository. Your changes
+ include modifications of your own, patches you receive via
+ e-mails, and merges 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.
+ (6) Push your changes to the public repository, and announce it
+ to the public.
+
+ (7) 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:
+
+A recommended work cycle for a "subsystem maintainer" that works
+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.
currently not automated.
(4) Push into the public repository from your primary
- repository.
+ repository. Run "git repack", and possibly "git
+ prune-packed" if the transport used for pulling from your
+ repository supports packed repositories.
- (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".
+ (5) Keep working in your primary repository. Your changes
+ include modifications of your own, patches you receive via
+ e-mails, and merges 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.
+ (6) Push your changes to your public repository, and ask your
+ "project lead" and possibly your "sub-subsystem
+ maintainers" to pull from it.
+
+ (7) 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.
+ (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.
- (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.
+ (2) Do your work there. Make commits.
- (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.
+ (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.
- (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.
+ (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.
-[Side Note: I think Cogito calls this upstream "origin".
- Somebody care to confirm or deny? ]
+ (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 ]