From a1d4aa742416953a3ac9be9154c55e90a4193cd6 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 1 Sep 2005 16:56:13 -0700 Subject: Add repository-layout document. ... and link to it from both the main index and the tutorial. Signed-off-by: Junio C Hamano diff --git a/Documentation/Makefile b/Documentation/Makefile index e19c86f..afdecc1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -3,7 +3,11 @@ MAN7_TXT=git.txt DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) -ARTICLES = tutorial cvs-migration diffcore howto-index +ARTICLES = tutorial +ARTICLES += cvs-migration +ARTICLES += diffcore +ARTICLES += howto-index +ARTICLES += repository-layout # with their own formatting rules. SP_ARTICLES = glossary howto/revert-branch-rebase diff --git a/Documentation/git.txt b/Documentation/git.txt index dba9035..2f8a647 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -412,24 +412,13 @@ HEAD:: File/Directory Structure ------------------------ -The git-core manipulates the following areas in the directory: - .git/ The base (overridden with $GIT_DIR) - objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY) - ??/ 'First 2 chars of object' directories. - pack/ Packed archives. - - refs/ Directories containing symbolic names for objects - (each file contains the hex SHA1 + newline) - heads/ Commits which are heads of various sorts - tags/ Tags, by the tag name (or some local renaming of it) - */ Any other subdirectory of refs/ can be used to store - files similar to what are under refs/heads/. - HEAD Symlink to refs/heads/ +Please see link:repository-layout.html[repository layout] document. Higher level SCMs may provide and manage additional information in the GIT_DIR. + Terminology ----------- Please see link:glossary.html[glossary] document. diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt new file mode 100644 index 0000000..297a47b --- /dev/null +++ b/Documentation/repository-layout.txt @@ -0,0 +1,136 @@ +GIT repository layout +===================== +v0.99.5, Sep 2005 + +You may find these things in your git repository (`.git` +directory for a repository associated with your working tree, or +`'project'.git` directory for a public 'naked' repository). + +objects:: + Object store associated with this repository. Usually + an object store is self sufficient (i.e. all the objects + that are referred to by an object found in it are also + found in it), but there are couple of ways to violate + it. ++ +. You could populate the repository by running a commit walker +without `-a` option. Depending on which options are given, you +could have only commit objects without associated blobs and +trees this way, for example. A repository with this kind of +incomplete object store is not suitable to be published to the +outside world but sometimes useful for private repository. +. You can be using `objects/info/alternates` mechanism, or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +objects from other object stores. A repository with this kind +of incompete object store is not suitable to be published for +use with dumb transports but otherwise is OK as long as +`objects/info/alternates` points at the right object stores +it borrows from. + +objects/[0-9a-f][0-9a-f]:: + Traditionally, each object is stored in its own file. + They are split into 256 subdirectories using the first + two letters from its object name to keep the number of + directory entries `objects` directory itself needs to + hold. Objects found here are often called 'unpacked' + objects. + +objects/pack:: + Packs (files that store many object in compressed form, + along with index files to allow them to be randomly + accessed) are found in this directory. + +objects/info:: + Additional information about the object store is + recorded in this directory. + +objects/info/packs:: + This file is to help dumb transports discover what packs + are available in this object store. Whenever a pack is + added or removed, `git update-server-info` should be run + to keep this file up-to-date if the repository is + published for dumb transports. `git repack` does this + by default. + +objects/info/alternates:: + This file records absolute filesystem paths of alternate + object stores that this object store borrows objects + from, one pathname per line. + +refs:: + References are stored in subdirectories of this + directory. The `git prune` command knows to keep + objects reachable from refs found in this directory and + its subdirectories. + +refs/heads/`name`:: + records tip-of-the-tree commit objects of branch `name` + +refs/tags/`name`:: + records any object name (not necessarily a commit + object, or a tag object that points at a commit object). + +HEAD:: + A symlink of the form `refs/heads/'name'` to point at + the current branch, if exists. It does not mean much if + the repository is not associated with any working tree + (i.e. 'naked' repository), but a valid git repository + *must* have such a symlink here. It is legal if the + named branch 'name' does not (yet) exist. + +branches:: + A slightly deprecated way to store shorthands to be used + to specify URL to `git fetch`, `git pull` and `git push` + commands is to store a file in `branches/'name'` and + give 'name' to these commands in place of 'repository' + argument. + +hooks:: + Hooks are customization scripts used by various git + commands. A handful of sample hooks are installed when + `git init-db` is run, but all of them are disabled by + default. To enable, they need to be made executable. + +index:: + The current index file for the repository. It is + usually not found in a naked repository. + +info:: + Additional information about the repository is recorded + in this directory. + +info/refs:: + This file is to help dumb transports to discover what + refs are available in this repository. Whenever you + create/delete a new branch or a new tag, `git + update-server-info` should be run to keep this file + up-to-date if the repository is published for dumb + transports. The `git-receive-pack` command, which is + run on a remote repository when you `git push` into it, + runs `hooks/update` hook to help you achive this. + +info/grafts:: + This file records fake commit ancestry information, to + pretend the set of parents a commit has is different + from how the commit was actually created. One record + per line describes a commit and its fake parents by + listing their 40-byte hexadecimal object names separated + by a space and terminated by a newline. + +info/rev-cache:: + No higher-level tool currently takes advantage of this + file, but it is generated when `git update-server-info` + is run. It records the commit ancestry information of + the commits in this repository in a concise binary + format, and can be read with `git-show-rev-cache`. + +info/exclude:: + This file, by convention among Porcelains, stores the + exclude pattern list. `git status` looks at it, but + otherwise it is not looked at by any of the core GIT + commands. + +remotes:: + Stoers shorthands to be used to give URL and default + refnames to interact with remote repository to `git + fetch`, `git pull` and `git push` commands. diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 1ed8038..04354a3 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -93,6 +93,11 @@ expect to see a number of 41-byte files containing these references in these `refs` subdirectories when you actually start populating your tree. +[NOTE] +An advanced user may want to take a look at the +link:repository-layout.html[repository layout] document +after finishing this tutorial. + You have now created your first git repository. Of course, since it's empty, that's not very useful, so let's start populating it with data. -- cgit v0.10.2-6-g49f6 From 89bc8c785e20258efba3b2b5ffc26098fa0b8bc8 Mon Sep 17 00:00:00 2001 From: Amos Waterland Date: Thu, 1 Sep 2005 09:13:50 -0500 Subject: [PATCH] Explain what went wrong on update-cache of new file If somebody tries to run `git update-cache foo', where foo is a new file, git dies with a rather cryptic error message: fatal: Unable to add foo to database This trivial patch makes git explain what probably went wrong. It is not a perfect diagnosis of all error paths, but for 90% of the cases it should provide the user with the clue they need. [jc: I ended up wording slightly differently, and fixed another confusing error message I noticed while reviewing the code.] Signed-off-by: Amos Waterland Signed-off-by: Junio C Hamano diff --git a/update-cache.c b/update-cache.c index 63815ed..3d1fd2b 100644 --- a/update-cache.c +++ b/update-cache.c @@ -53,7 +53,11 @@ static int add_file_to_cache(char *path) if (allow_remove) return remove_file_from_cache(path); } - return error("open(\"%s\"): %s", path, strerror(errno)); + if (0 == status) + return error("%s: is a directory", path); + else + return error("lstat(\"%s\"): %s", path, + strerror(errno)); } namelen = strlen(path); size = cache_entry_size(namelen); @@ -393,7 +397,7 @@ int main(int argc, char **argv) continue; } if (add_file_to_cache(path)) - die("Unable to add %s to database", path); + die("Unable to add %s to database; maybe you want to use --add option?", path); } if (write_cache(newfd, active_cache, active_nr) || commit_index_file(&cache_file)) -- cgit v0.10.2-6-g49f6 From 06ec2b4bb4ab9096d1304ba5a2ec388078dcdf7f Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 2 Sep 2005 02:34:13 -0700 Subject: Fix automerge message. The rewrite done while adding the shorthand support made the remote refname recorded in the commit message too long for human consumption, while losing information by using the shorthand not the real URL to name the remote repository there. They were both bad changes done without enough thinking. Pointed out by Linus. Signed-off-by: Junio C Hamano diff --git a/git-fetch-script b/git-fetch-script index dd94ede..f9f90b6 100755 --- a/git-fetch-script +++ b/git-fetch-script @@ -55,21 +55,41 @@ append_fetch_head () { remote_nick_="$4" local_name_="$5" + # remote-nick is the URL given on the command line (or a shorthand) + # remote-name is the $GIT_DIR relative refs/ path we computed + # for this refspec. + case "$remote_name_" in + HEAD) + note_= ;; + refs/heads/*) + note_="$(expr "$remote_name_" : 'refs/heads/\(.*\)')" + note_="branch '$note_' of " ;; + refs/tags/*) + note_="$(expr "$remote_name_" : 'refs/tags/\(.*\)')" + note_="tag '$note_' of " ;; + *) + note_="$remote_name of " ;; + esac + remote_1_=$(expr "$remote_" : '\(.*\)\.git/*$') && + remote_="$remote_1_" + note_="$note_$remote_" + # 2.6.11-tree tag would not be happy to be fed to resolve. if git-cat-file commit "$head_" >/dev/null 2>&1 then headc_=$(git-rev-parse --verify "$head_^0") || exit - note_="$headc_ $remote_name_ from $remote_nick_" - echo "$note_" >>$GIT_DIR/FETCH_HEAD - echo >&2 "* committish: $note_" + echo "$headc_ $note_" >>$GIT_DIR/FETCH_HEAD + echo >&2 "* committish: $head_" + echo >&2 " $note_" else - echo >&2 "* non-commit: $note_" + echo >&2 "* non-commit: $head_" + echo >&2 " $note_" fi if test "$local_name_" != "" then # We are storing the head locally. Make sure that it is # a fast forward (aka "reverse push"). - fast_forward_local "$local_name_" "$head_" "$remote_" "$remote_name_" + fast_forward_local "$local_name_" "$head_" "$note_" fi } @@ -80,11 +100,9 @@ fast_forward_local () { # is no way to guarantee "fast-forward" anyway. if test -f "$GIT_DIR/$1" then - echo >&2 "* $1: updating with $4" - echo >&2 " from $3." + echo >&2 "* $1: updating with $3" else - echo >&2 "* $1: storing $4" - echo >&2 " from $3." + echo >&2 "* $1: storing $3" fi echo "$2" >"$GIT_DIR/$1" ;; @@ -97,31 +115,28 @@ fast_forward_local () { mb=$(git-merge-base "$local" "$2") && case "$2,$mb" in $local,*) - echo >&2 "* $1: same as $4" - echo >&2 " from $3" + echo >&2 "* $1: same as $3" ;; *,$local) - echo >&2 "* $1: fast forward to $4" - echo >&2 " from $3" + echo >&2 "* $1: fast forward to $3" ;; *) false ;; esac || { - echo >&2 "* $1: does not fast forward to $4" + echo >&2 "* $1: does not fast forward to $3;" case "$force,$single_force" in t,* | *,t) - echo >&2 " from $3; forcing update." + echo >&2 " forcing update." ;; *) mv "$GIT_DIR/$1.lock" "$GIT_DIR/$1.remote" - echo >&2 " from $3; leaving it in '$1.remote'" + echo >&2 " leaving it in '$1.remote'" ;; esac } else - echo >&2 "* $1: storing $4" - echo >&2 " from $3." + echo >&2 "* $1: storing $3" fi test -f "$GIT_DIR/$1.lock" && mv "$GIT_DIR/$1.lock" "$GIT_DIR/$1" -- cgit v0.10.2-6-g49f6 From 79882c2883267e16280d630730d6a8b5a86a8092 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 2 Sep 2005 10:39:57 -0700 Subject: git-checkout-script: Remove unnecessary variable. There was unused variable $i that counted the number of arguments being processed. Remove it. Signed-off-by: Junio C Hamano diff --git a/git-checkout-script b/git-checkout-script index 9feff14..b31ded7 100755 --- a/git-checkout-script +++ b/git-checkout-script @@ -37,7 +37,6 @@ while [ "$#" != "0" ]; do fi ;; esac - i=$(($i+1)) done [ -z "$new" ] && new=$old -- cgit v0.10.2-6-g49f6 From 86b13da46cd710a45a89968880c691452d5b70b4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 2 Sep 2005 10:53:15 -0700 Subject: scripts: equality test '==' is not portable. On NetBSD 3 we trigger an error: [: ==: unexpected operator Double-equal is accepted by bash built-in '[' and bash(1) suggests using '=' for strict POSIX compliance (test(1) from coreutils does not mention '=='). Eradicate their uses everywhere. [jc: Somebody with a pseudonym kindly sent a message to let me know about the problem privately; I do not have access to a NetBSD box.] Signed-off-by: Junio C Hamano diff --git a/git-resolve-script b/git-resolve-script index 7c0e3d8..000cbb8 100755 --- a/git-resolve-script +++ b/git-resolve-script @@ -36,19 +36,21 @@ if [ -z "$common" ]; then die "Unable to find common commit between" $merge $head fi -if [ "$common" == "$merge" ]; then +case "$common" in +"$merge") echo "Already up-to-date. Yeeah!" dropheads exit 0 -fi -if [ "$common" == "$head" ]; then + ;; +"$head") echo "Updating from $head to $merge." git-read-tree -u -m $head $merge || exit 1 echo $merge > "$GIT_DIR"/HEAD git-diff-tree -p $head $merge | git-apply --stat dropheads exit 0 -fi + ;; +esac # Find an optimum merge base if there are more than one candidates. LF=' diff --git a/git-status-script b/git-status-script index 2b02954..ee8f706 100755 --- a/git-status-script +++ b/git-status-script @@ -77,9 +77,9 @@ then #' fi -if [ "$committable" == "0" ] -then +case "$committable" in +0) echo "nothing to commit" exit 1 -fi +esac exit 0 diff --git a/templates/hooks--update b/templates/hooks--update index 0726975..3f38b82 100644 --- a/templates/hooks--update +++ b/templates/hooks--update @@ -16,10 +16,14 @@ then git-rev-list --pretty "$3" else $base=$(git-merge-base "$2" "$3") - if [ $base == "$2" ]; then + case "$base" in + "$2") echo "New commits:" - else + ;; + *) echo "Rebased ref, commits from common ancestor:" + ;; + esac fi git-rev-list --pretty "$3" "^$base" fi | -- cgit v0.10.2-6-g49f6 From 953e5842f8fcd40c3e7013a9793746719016db1b Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 2 Sep 2005 11:46:43 -0700 Subject: Mention post-update when we first talk about publishing a repository. There is more detailed instruction for `project lead` later in the tutorial to talk about the same, but at this point in the flow of tutorial, the first time reader has no way of knowing it. Signed-off-by: Junio C Hamano diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 04354a3..8d999b0 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -1103,6 +1103,12 @@ 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. +[NOTE] +If you plan to publish this repository to be accessed over http, +you should do `chmod +x my-git.git/hooks/post-update` at this +point. This makes sure that every time you push into this +repository, `git-update-server-info` is run. + 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: -- cgit v0.10.2-6-g49f6