From 119550af0c9f3cdd920e8d0e04b68b40b8485fdc Mon Sep 17 00:00:00 2001
From: "J. Bruce Fields" <bfields@fieldses.org>
Date: Wed, 25 Oct 2006 22:43:47 -0400
Subject: [PATCH 1/5] Documentation: updates to "Everyday GIT"
Remove the introduction: I think it should be obvious why
we have this. (And if it isn't obvious then we've got other
problems.)
Replace reference to git whatchanged by git log.
Miscellaneous style and grammar fixes.
Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Documentation/everyday.txt | 43 +++++++++++---------------------------
1 file changed, 12 insertions(+), 31 deletions(-)
diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index b935c18088..99e24a445b 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -1,22 +1,7 @@
Everyday GIT With 20 Commands Or So
===================================
-GIT suite has over 100 commands, and the manual page for each of
-them discusses what the command does and how it is used in
-detail, but until you know what command should be used in order
-to achieve what you want to do, you cannot tell which manual
-page to look at, and if you know that already you do not need
-the manual.
-
-Does that mean you need to know all of them before you can use
-git? Not at all. Depending on the role you play, the set of
-commands you need to know is slightly different, but in any case
-what you need to learn is far smaller than the full set of
-commands to carry out your day-to-day work. This document is to
-serve as a cheat-sheet and a set of pointers for people playing
-various roles.
-
-<<Basic Repository>> commands are needed by people who has a
+<<Basic Repository>> commands are needed by people who have a
repository --- that is everybody, because every working tree of
git is a repository.
@@ -25,28 +10,27 @@ essential for anybody who makes a commit, even for somebody who
works alone.
If you work with other people, you will need commands listed in
-<<Individual Developer (Participant)>> section as well.
+the <<Individual Developer (Participant)>> section as well.
-People who play <<Integrator>> role need to learn some more
+People who play the <<Integrator>> role need to learn some more
commands in addition to the above.
<<Repository Administration>> commands are for system
-administrators who are responsible to care and feed git
-repositories to support developers.
+administrators who are responsible for the care and feeding
+of git repositories.
Basic Repository[[Basic Repository]]
------------------------------------
-Everybody uses these commands to feed and care git repositories.
+Everybody uses these commands to maintain git repositories.
* gitlink:git-init-db[1] or gitlink:git-clone[1] to create a
new repository.
- * gitlink:git-fsck-objects[1] to validate the repository.
+ * gitlink:git-fsck-objects[1] to check the repository for errors.
- * gitlink:git-prune[1] to garbage collect cruft in the
- repository.
+ * gitlink:git-prune[1] to remove unused objects in the repository.
* gitlink:git-repack[1] to pack loose objects for efficiency.
@@ -78,8 +62,8 @@ $ git repack -a -d <1>
$ git prune
------------
+
-<1> pack all the objects reachable from the refs into one pack
-and remove unneeded other packs
+<1> pack all the objects reachable from the refs into one pack,
+then remove the other packs.
Individual Developer (Standalone)[[Individual Developer (Standalone)]]
@@ -93,9 +77,6 @@ following commands.
* gitlink:git-log[1] to see what happened.
- * gitlink:git-whatchanged[1] to find out where things have
- come from.
-
* gitlink:git-checkout[1] and gitlink:git-branch[1] to switch
branches.
@@ -120,7 +101,7 @@ following commands.
Examples
~~~~~~~~
-Extract a tarball and create a working tree and a new repository to keep track of it.::
+Use a tarball as a starting point for a new repository:
+
------------
$ tar zxf frotz.tar.gz
@@ -203,7 +184,7 @@ $ cd my2.6
$ edit/compile/test; git commit -a -s <1>
$ git format-patch origin <2>
$ git pull <3>
-$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
$ git reset --hard ORIG_HEAD <6>
$ git prune <7>
From d9c04ba3ddd0945ef18657a2a373c5edfe86ef7c Mon Sep 17 00:00:00 2001
From: Christian Couder <chriscool@tuxfamily.org>
Date: Thu, 26 Oct 2006 06:33:07 +0200
Subject: [PATCH 2/5] Remove --syslog in git-daemon inetd documentation
examples.
It is useless because --inetd implies --syslog.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Documentation/everyday.txt | 4 ++--
Documentation/git-daemon.txt | 6 ++----
2 files changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index 99e24a445b..278161f587 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -358,7 +358,7 @@ Run git-daemon to serve /pub/scm from inetd.::
------------
$ grep git /etc/inetd.conf
git stream tcp nowait nobody \
- /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+ /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
------------
+
The actual configuration line should be on one line.
@@ -378,7 +378,7 @@ service git
wait = no
user = nobody
server = /usr/bin/git-daemon
- server_args = --inetd --syslog --export-all --base-path=/pub/scm
+ server_args = --inetd --export-all --base-path=/pub/scm
log_on_failure += USERID
}
------------
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index d562232e52..4b2ea2df31 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -165,8 +165,7 @@ git-daemon as inetd server::
+
------------------------------------------------
git stream tcp nowait nobody /usr/bin/git-daemon
- git-daemon --inetd --verbose
- --syslog --export-all
+ git-daemon --inetd --verbose --export-all
/pub/foo /pub/bar
------------------------------------------------
@@ -179,8 +178,7 @@ git-daemon as inetd server for virtual hosts::
+
------------------------------------------------
git stream tcp nowait nobody /usr/bin/git-daemon
- git-daemon --inetd --verbose
- --syslog --export-all
+ git-daemon --inetd --verbose --export-all
--interpolated-path=/pub/%H%D
/pub/www.example.org/software
/pub/www.example.com/software
From 0074aba1c0d3b073c635fdc1d5754dc6a6b6b7b9 Mon Sep 17 00:00:00 2001
From: Jakub Narebski <jnareb@gmail.com>
Date: Thu, 26 Oct 2006 05:44:49 +0200
Subject: [PATCH 3/5] diff-format.txt: Combined diff format documentation
supplement
Update example combined diff format to the current version
$ git diff-tree -p -c fec9ebf16c948bcb4a8b88d0173ee63584bcde76
and provide complete first chunk in example.
Document combined diff format headers: how "diff header" look like,
which of "extended diff headers" are used with combined diff and how
they look like, differences in two-line from-file/to-file header from
non-combined diff format, chunk header format.
It should be noted that combined diff format was designed for quick
_content_ inspection and renames would work correctly to pick which
blobs from each tree to compare but otherwise not reflected in the
output (the pathnames are not shown).
[jc: with minimum copyediting]
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Documentation/diff-format.txt | 76 +++++++++++++++++++++++++++++++----
1 file changed, 68 insertions(+), 8 deletions(-)
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 617d8f526f..174d63a1ee 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -156,31 +156,91 @@ to produce 'combined diff', which looks like this:
------------
diff --combined describe.c
-@@@ +98,7 @@@
- return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+ return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
}
-
+
- static void describe(char *arg)
-static void describe(struct commit *cmit, int last_one)
++static void describe(char *arg, int last_one)
{
- + unsigned char sha1[20];
- + struct commit *cmit;
+ + unsigned char sha1[20];
+ + struct commit *cmit;
+ struct commit_list *list;
+ static int initialized = 0;
+ struct commit_name *n;
+
+ + if (get_sha1(arg, sha1) < 0)
+ + usage(describe_usage);
+ + cmit = lookup_commit_reference(sha1);
+ + if (!cmit)
+ + usage(describe_usage);
+ +
+ if (!initialized) {
+ initialized = 1;
+ for_each_ref(get_name);
------------
+1. It is preceded with a "git diff" header, that looks like
+ this (when '-c' option is used):
+
+ diff --combined file
++
+or like this (when '--cc' option is used):
+
+ diff --c file
+
+2. It is followed by one or more extended header lines
+ (this example shows a merge with two parents):
+
+ index <hash>,<hash>..<hash>
+ mode <mode>,<mode>..<mode>
+ new file mode <mode>
+ deleted file mode <mode>,<mode>
++
+The `mode <mode>,<mode>..<mode>` line appears only if at least one of
+the <mode> is diferent from the rest. Extended headers with
+information about detected contents movement (renames and
+copying detection) are designed to work with diff of two
+<tree-ish> and are not used by combined diff format.
+
+3. It is followed by two-line from-file/to-file header
+
+ --- a/file
+ +++ b/file
++
+Contrary to two-line header for traditional 'unified' diff
+format, and similar to filenames in ordinary "diff header",
+/dev/null is not used for creation or deletion.
+
+4. Chunk header format is modified to prevent people from
+ accidentally feeding it to `patch -p1`. Combined diff format
+ was created for review of merge commit changes, and was not
+ meant for apply. The change is similar to the change in the
+ extended 'index' header:
+
+ @@@ <from-file-range> <from-file-range> <to-file-range> @@@
++
+There are (number of parents + 1) `@` characters in the chunk
+header for combined diff format.
+
Unlike the traditional 'unified' diff format, which shows two
files A and B with a single column that has `-` (minus --
appears in A but removed in B), `+` (plus -- missing in A but
-added to B), or ` ` (space -- unchanged) prefix, this format
+added to B), or `" "` (space -- unchanged) prefix, this format
compares two or more files file1, file2,... with one file X, and
shows how X differs from each of fileN. One column for each of
fileN is prepended to the output line to note how X's line is
different from it.
A `-` character in the column N means that the line appears in
-fileN but it does not appear in the last file. A `+` character
+fileN but it does not appear in the result. A `+` character
in the column N means that the line appears in the last file,
-and fileN does not have that line.
+and fileN does not have that line (in other words, the line was
+added, from the point of view of that parent).
In the above example output, the function signature was changed
from both files (hence two `-` removals from both file1 and
From 0ac3056850394723c9b407754b44d3d37f1dcc3f Mon Sep 17 00:00:00 2001
From: Junio C Hamano <junkio@cox.net>
Date: Thu, 26 Oct 2006 01:15:42 -0700
Subject: [PATCH 4/5] Documentation: clarify refname disambiguation rules.
Nobody should create ambiguous refs (i.e. have tag "foobar" and branch
"foobar" at the same time) that need to be disambiguated with these
rules to keep sanity, but the rules are there so document them.
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Documentation/git-rev-parse.txt | 25 +++++++++++++++++++++----
1 file changed, 21 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 5d4257062d..ed938aafb0 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -122,14 +122,30 @@ blobs contained in a commit.
your repository whose object name starts with dae86e.
* An output from `git-describe`; i.e. a closest tag, followed by a
- dash, a 'g', and an abbreviated object name.
+ dash, a `g`, and an abbreviated object name.
* A symbolic ref name. E.g. 'master' typically means the commit
object referenced by $GIT_DIR/refs/heads/master. If you
happen to have both heads/master and tags/master, you can
explicitly say 'heads/master' to tell git which one you mean.
+ When ambiguous, a `<name>` is disambiguated by taking the
+ first match in the following rules:
-* A suffix '@' followed by a date specification enclosed in a brace
+ . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
+ useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
+
+ . otherwise, `$GIT_DIR/refs/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+
+* A ref followed by the suffix '@' with a date specification
+ enclosed in a brace
pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
of the ref at a prior point in time. This suffix may only be
@@ -146,8 +162,9 @@ blobs contained in a commit.
* A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>th generation grand-parent of the named
commit object, following only the first parent. I.e. rev~3 is
- equivalent to rev{caret}{caret}{caret} which is equivalent to\
- rev{caret}1{caret}1{caret}1.
+ equivalent to rev{caret}{caret}{caret} which is equivalent to
+ rev{caret}1{caret}1{caret}1. See below for a illustration of
+ the usage of this form.
* A suffix '{caret}' followed by an object type name enclosed in
brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
From d5f6a01af0658bc0ec5f068d81ba321be94526d5 Mon Sep 17 00:00:00 2001
From: Junio C Hamano <junkio@cox.net>
Date: Thu, 26 Oct 2006 00:05:04 -0700
Subject: [PATCH 5/5] combine-diff: a few more finishing touches.
"new file" and "deleted file" were already reported in the
original code, but the logic was not as transparent as it could
have. This uses a few variables and more comments to clarify
the flow. The rule is: (1) if a path exists in the merge result
when no parent had it, we report "new" (otherwise it came from
the parents, as opposed to have added by the evil merge). (2) if
the path does not exist in the merge result, it is "deleted".
Since we can say "new" and "deleted", there is no reason not to
follow the /dev/null convention. This fixes it.
Appending function name after @@@ ... @@@ is trivial, so
implement it.
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
Documentation/diff-format.txt | 6 ++---
combine-diff.c | 48 +++++++++++++++++++++++++++++++----
2 files changed, 46 insertions(+), 8 deletions(-)
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 174d63a1ee..ed4ebcbab7 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -212,9 +212,9 @@ copying detection) are designed to work with diff of two
--- a/file
+++ b/file
+
-Contrary to two-line header for traditional 'unified' diff
-format, and similar to filenames in ordinary "diff header",
-/dev/null is not used for creation or deletion.
+Similar to two-line header for traditional 'unified' diff
+format, `/dev/null` is used to signal created or deleted
+files.
4. Chunk header format is modified to prevent people from
accidentally feeding it to `patch -p1`. Combined diff format
diff --git a/combine-diff.c b/combine-diff.c
index 46d9121baf..01a8437f5c 100644
--- a/combine-diff.c
+++ b/combine-diff.c
@@ -489,6 +489,12 @@ static void show_parent_lno(struct sline *sline, unsigned long l0, unsigned long
printf(" -%lu,%lu", l0, l1-l0);
}
+static int hunk_comment_line(const char *bol)
+{
+ int ch = *bol & 0xff;
+ return (isalpha(ch) || ch == '_' || ch == '$');
+}
+
static void dump_sline(struct sline *sline, unsigned long cnt, int num_parent,
int use_color)
{
@@ -508,8 +514,13 @@ static void dump_sline(struct sline *sline, unsigned long cnt, int num_parent,
struct sline *sl = &sline[lno];
unsigned long hunk_end;
unsigned long rlines;
- while (lno <= cnt && !(sline[lno].flag & mark))
+ const char *hunk_comment = NULL;
+
+ while (lno <= cnt && !(sline[lno].flag & mark)) {
+ if (hunk_comment_line(sline[lno].bol))
+ hunk_comment = sline[lno].bol;
lno++;
+ }
if (cnt < lno)
break;
else {
@@ -526,6 +537,22 @@ static void dump_sline(struct sline *sline, unsigned long cnt, int num_parent,
show_parent_lno(sline, lno, hunk_end, i);
printf(" +%lu,%lu ", lno+1, rlines);
for (i = 0; i <= num_parent; i++) putchar(combine_marker);
+
+ if (hunk_comment) {
+ int comment_end = 0;
+ for (i = 0; i < 40; i++) {
+ int ch = hunk_comment[i] & 0xff;
+ if (!ch || ch == '\n')
+ break;
+ if (!isspace(ch))
+ comment_end = i;
+ }
+ if (comment_end)
+ putchar(' ');
+ for (i = 0; i < comment_end; i++)
+ putchar(hunk_comment[i]);
+ }
+
printf("%s\n", c_reset);
while (lno < hunk_end) {
struct lline *ll;
@@ -707,6 +734,8 @@ static void show_patch_diff(struct combine_diff_path *elem, int num_parent,
int use_color = opt->color_diff;
const char *c_meta = diff_get_color(use_color, DIFF_METAINFO);
const char *c_reset = diff_get_color(use_color, DIFF_RESET);
+ int added = 0;
+ int deleted = 0;
if (rev->loginfo)
show_log(rev, opt->msg_sep);
@@ -722,7 +751,10 @@ static void show_patch_diff(struct combine_diff_path *elem, int num_parent,
printf("..%s%s\n", abb, c_reset);
if (mode_differs) {
- int added = !!elem->mode;
+ deleted = !elem->mode;
+
+ /* We say it was added if nobody had it */
+ added = !deleted;
for (i = 0; added && i < num_parent; i++)
if (elem->parent[i].status !=
DIFF_STATUS_ADDED)
@@ -731,7 +763,7 @@ static void show_patch_diff(struct combine_diff_path *elem, int num_parent,
printf("%snew file mode %06o",
c_meta, elem->mode);
else {
- if (!elem->mode)
+ if (deleted)
printf("%sdeleted file ", c_meta);
printf("mode ");
for (i = 0; i < num_parent; i++) {
@@ -743,8 +775,14 @@ static void show_patch_diff(struct combine_diff_path *elem, int num_parent,
}
printf("%s\n", c_reset);
}
- dump_quoted_path("--- a/", elem->path, c_meta, c_reset);
- dump_quoted_path("+++ b/", elem->path, c_meta, c_reset);
+ if (added)
+ dump_quoted_path("--- /dev/", "null", c_meta, c_reset);
+ else
+ dump_quoted_path("--- a/", elem->path, c_meta, c_reset);
+ if (deleted)
+ dump_quoted_path("+++ /dev/", "null", c_meta, c_reset);
+ else
+ dump_quoted_path("+++ b/", elem->path, c_meta, c_reset);
dump_sline(sline, cnt, num_parent, opt->color_diff);
}
free(result);