From 23091e954c968282d4d9087da00f60c2f02aecc5 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sun, 2 Apr 2006 17:54:34 -0400 Subject: [PATCH 1/3] Documentation: revise top of git man page I'm afraid I'll be accused of trying to suck all the jokes and the personality out of the git documentation. I'm not! Really! That said, "man git" is one of the first things a new user is likely try, and it seems a little cruel to start off with a somewhat obscure joke about the architecture of git. So instead I'm trying for a relatively straightforward description of what git does, and what features distinguish it from other systems, together with immediate links to introductory documentation. I also did some minor reorganization in an attempt to clarify the classification of commands. And revised a bit for conciseness (as is obvious from the diffstat--hopefully I didn't cut anything important). Signed-off-by: J. Bruce Fields Signed-off-by: Junio C Hamano --- Documentation/git.txt | 89 ++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 48 deletions(-) diff --git a/Documentation/git.txt b/Documentation/git.txt index fe34f50dc5..06b2e5303e 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -12,10 +12,14 @@ SYNOPSIS DESCRIPTION ----------- -'git' is both a program and a directory content tracker system. -The program 'git' is just a wrapper to reach the core git programs -(or a potty if you like, as it's not exactly porcelain but still -brings your stuff to the plumbing). +Git is a fast, scalable, distributed revision control system with an +unusually rich command set that provides both high-level operations +and full access to internals. + +See this link:tutorial.html[tutorial] to get started, then see +link:everyday.html[Everyday Git] for a useful minimum set of commands, and +"man git-commandname" for documentation of each command. CVS users may +also want to read link:cvs-migration.html[CVS migration]. OPTIONS ------- @@ -35,55 +39,38 @@ OPTIONS the current setting and then exit. -NOT LEARNING CORE GIT COMMANDS ------------------------------- +FURTHER DOCUMENTATION +--------------------- -This manual is intended to give complete background information -and internal workings of git, which may be too much for most -people. The <> section below contains much useful -definition and clarification - read that first. +See the references above to get started using git. The following is +probably more detail than necessary for a first-time user. -If you are interested in using git to manage (version control) -projects, use link:tutorial.html[The Tutorial] to get you started, -and then link:everyday.html[Everyday GIT] as a guide to the -minimum set of commands you need to know for day-to-day work. -Most likely, that will get you started, and you can go a long -way without knowing the low level details too much. +The <> section below and the +link:core-tutorial.html[Core tutorial] both provide introductions to the +underlying git architecture. -The link:core-tutorial.html[Core tutorial] document covers how things -internally work. +See also the link:howto-index.html[howto] documents for some useful +examples. -If you are migrating from CVS, link:cvs-migration.html[cvs -migration] document may be helpful after you finish the -tutorial. +GIT COMMANDS +------------ -After you get the general feel from the tutorial and this -overview page, you may want to take a look at the -link:howto-index.html[howto] documents. +We divide git into high level ("porcelain") commands and low level +("plumbing") commands. +Low-level commands (plumbing) +----------------------------- -CORE GIT COMMANDS ------------------ +Although git includes its +own porcelain layer, its low-level commands are sufficient to support +development of alternative porcelains. Developers of such porcelains +might start by reading about gitlink:git-update-index[1] and +gitlink:git-read-tree[1]. -If you are writing your own Porcelain, you need to be familiar -with most of the low level commands --- I suggest starting from -gitlink:git-update-index[1] and gitlink:git-read-tree[1]. - - -Commands Overview ------------------ -The git commands can helpfully be split into those that manipulate -the repository, the index and the files in the working tree, those that -interrogate and compare them, and those that moves objects and -references between repositories. - -In addition, git itself comes with a spartan set of porcelain -commands. They are usable but are not meant to compete with real -Porcelains. - -There are also some ancillary programs that can be viewed as useful -aids for using the core commands but which are unlikely to be used by -SCMs layered over git. +We divide the low-level commands into commands that manipulate objects (in +the repository, index, and working tree), commands that interrogate and +compare objects, and commands that move objects and references between +repositories. Manipulation commands ~~~~~~~~~~~~~~~~~~~~~ @@ -248,8 +235,14 @@ gitlink:git-upload-pack[1]:: what are asked for. -Porcelain-ish Commands ----------------------- +High-level commands (porcelain) +------------------------------- + +We separate the porcelain commands into the main commands and some +ancillary user utilities. + +Main porcelain commands +~~~~~~~~~~~~~~~~~~~~~~~ gitlink:git-add[1]:: Add paths to the index. @@ -346,7 +339,7 @@ gitlink:git-whatchanged[1]:: Ancillary Commands ------------------- +~~~~~~~~~~~~~~~~~~ Manipulators: gitlink:git-applypatch[1]:: From 40e907bff260a94306b1fe43d0fb829bf54e3103 Mon Sep 17 00:00:00 2001 From: Jim Radford Date: Sun, 2 Apr 2006 20:50:17 -0700 Subject: [PATCH 2/3] fix repacking with lots of tags Use git-rev-list's --all instead of git-rev-parse's to keep from hitting the shell's argument list length limits when repacking with lots of tags. Signed-off-by: Junio C Hamano --- git-repack.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/git-repack.sh b/git-repack.sh index bc901126bf..a5d349fd09 100755 --- a/git-repack.sh +++ b/git-repack.sh @@ -29,12 +29,10 @@ PACKDIR="$GIT_OBJECT_DIRECTORY/pack" case ",$all_into_one," in ,,) rev_list='--unpacked' - rev_parse='--all' pack_objects='--incremental' ;; ,t,) rev_list= - rev_parse='--all' pack_objects= # Redundancy check in all-into-one case is trivial. @@ -43,7 +41,7 @@ case ",$all_into_one," in ;; esac pack_objects="$pack_objects $local $quiet $no_reuse_delta" -name=$(git-rev-list --objects $rev_list $(git-rev-parse $rev_parse) 2>&1 | +name=$(git-rev-list --objects --all $rev_list 2>&1 | git-pack-objects --non-empty $pack_objects .tmp-pack) || exit 1 if [ -z "$name" ]; then From c72112e6e1593bd77132a815ba484d0ff880a7b4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 2 Apr 2006 16:25:01 -0700 Subject: [PATCH 3/3] git-clone: fix handling of upsteram whose HEAD does not point at master. When cloning from a remote repository that has master, main, and origin branches _and_ with the HEAD pointing at main branch, we did quite confused things during clone. So this cleans things up. The behaviour is a bit different between separate remotes/ layout and the mixed branches layout. The newer layout with $GIT_DIR/refs/remotes/$origin/, things are simpler and more transparent: - remote branches are copied to refs/remotes/$origin/. - HEAD points at the branch with the same name as the remote HEAD points at, and starts at where the remote HEAD points at. - $GIT_DIR/remotes/$origin file is set up to fetch all remote branches, and merge the branch HEAD pointed at at the time of the cloning. Everything-in-refs/heads layout was the more confused one, but cleaned up like this: - remote branches are copied to refs/heads, but the branch "$origin" is not copied, instead a copy of the branch the remote HEAD points at is created there. - HEAD points at the branch with the same name as the remote HEAD points at, and starts at where the remote HEAD points at. - $GIT_DIR/remotes/$origin file is set up to fetch all remote branches except "$origin", and merge the branch HEAD pointed at at the time of the cloning. With this, the remote has master, main and origin, and its HEAD points at main, you could: git clone $URL --origin upstream to use refs/heads/upstream as the tracking branch for remote "main", and your primary working branch will also be "main". "master" and "origin" are used to track the corresponding remote branches and with this setup they do not have any special meaning. Signed-off-by: Junio C Hamano --- git-clone.sh | 47 ++++++++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/git-clone.sh b/git-clone.sh index 823c74b913..c013e481d0 100755 --- a/git-clone.sh +++ b/git-clone.sh @@ -52,7 +52,8 @@ Perhaps git-update-server-info needs to be run there?" git-http-fetch -v -a -w "$tname" "$name" "$1/" || exit 1 done <"$clone_tmp/refs" rm -fr "$clone_tmp" - http_fetch "$1/HEAD" "$GIT_DIR/REMOTE_HEAD" + http_fetch "$1/HEAD" "$GIT_DIR/REMOTE_HEAD" || + rm -f "$GIT_DIR/REMOTE_HEAD" } # Read git-fetch-pack -k output and store the remote branches. @@ -324,7 +325,7 @@ test -d "$GIT_DIR/refs/reference-tmp" && rm -fr "$GIT_DIR/refs/reference-tmp" if test -f "$GIT_DIR/CLONE_HEAD" then - # Figure out where the remote HEAD points at. + # Read git-fetch-pack -k output and store the remote branches. perl -e "$copy_refs" "$GIT_DIR" "$use_separate_remote" "$origin" fi @@ -332,22 +333,25 @@ cd "$D" || exit if test -z "$bare" && test -f "$GIT_DIR/REMOTE_HEAD" then - head_sha1=`cat "$GIT_DIR/REMOTE_HEAD"` # Figure out which remote branch HEAD points at. case "$use_separate_remote" in '') remote_top=refs/heads ;; *) remote_top="refs/remotes/$origin" ;; esac - # What to use to track the remote primary branch - if test -n "$use_separate_remote" - then - origin_tracking="remotes/$origin/master" - else - origin_tracking="heads/$origin" - fi + head_sha1=`cat "$GIT_DIR/REMOTE_HEAD"` + case "$head_sha1" in + 'ref: refs/'*) + # Uh-oh, the remote told us (http transport done against + # new style repository with a symref HEAD). + # Ideally we should skip the guesswork but for now + # opt for minimum change. + head_sha1=`expr "$head_sha1" : 'ref: refs/heads/\(.*\)'` + head_sha1=`cat "$GIT_DIR/$remote_top/$head_sha1"` + ;; + esac - # The name under $remote_top the remote HEAD seems to point at + # The name under $remote_top the remote HEAD seems to point at. head_points_at=$( ( echo "master" @@ -368,23 +372,28 @@ then ) ) - # Write out remotes/$origin file. + # Write out remotes/$origin file, and update our "$head_points_at". case "$head_points_at" in ?*) mkdir -p "$GIT_DIR/remotes" && + git-symbolic-ref HEAD "refs/heads/$head_points_at" && + case "$use_separate_remote" in + t) origin_track="$remote_top/$head_points_at" + git-update-ref HEAD "$head_sha1" ;; + *) origin_track="$remote_top/$origin" + git-update-ref "refs/heads/$origin" "$head_sha1" ;; + esac && echo >"$GIT_DIR/remotes/$origin" \ "URL: $repo -Pull: refs/heads/$head_points_at:refs/$origin_tracking" && - case "$use_separate_remote" in - t) git-update-ref HEAD "$head_sha1" ;; - *) git-update-ref "refs/heads/$origin" $(git-rev-parse HEAD) ;; - esac && +Pull: refs/heads/$head_points_at:$origin_track" && (cd "$GIT_DIR/$remote_top" && find . -type f -print) | while read dotslref do name=`expr "$dotslref" : './\(.*\)'` && - test "$head_points_at" = "$name" || - test "$origin" = "$name" || + test "$use_separate_remote" = '' && { + test "$head_points_at" = "$name" || + test "$origin" = "$name" + } || echo "Pull: refs/heads/${name}:$remote_top/${name}" done >>"$GIT_DIR/remotes/$origin" && case "$use_separate_remote" in