From e52cf78cdb9991ea34bfa1f65f3b10fea6a8db3b Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 19 Aug 2007 19:15:52 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.3-rc5-40-g2f82 --- git-fast-import.html | 73 +++++++++++++++++++++++++++++++++++++++---- git-fast-import.txt | 74 +++++++++++++++++++++++++++++++++++++++++--- git-reflog.html | 5 +-- git-reflog.txt | 3 +- 4 files changed, 142 insertions(+), 13 deletions(-) diff --git a/git-fast-import.html b/git-fast-import.html index 451ee64de..8e50ca467 100644 --- a/git-fast-import.html +++ b/git-fast-import.html @@ -480,6 +480,13 @@ Supplying additional whitespace characters will cause unexpected results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters unexpected input.

+

Stream Comments

+

To aid in debugging frontends fast-import ignores any line that +begins with # (ASCII pound/hash) up to and including the line +ending LF. A comment line may contain any sequence of bytes +that does not contain an LF and therefore may be used to include +any detailed debugging information that might be specific to the +frontend and useful when inspecting a fast-import data stream.

Date Formats

The following date formats are supported. A frontend should select the format it will use for this import by passing the format name @@ -620,6 +627,16 @@ and control the current import process. More detailed discussion an import.

+
+progress +
+
+

+ Causes fast-import to echo the entire line to its own + standard output. This command is optional and is not needed + to perform an import. +

+

commit

Create or update a branch with a new commit, recording one logical @@ -634,7 +651,7 @@ change to the project.

('from' SP <committish> LF)? ('merge' SP <committish> LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall)* - LF + LF?

where <ref> is the name of the branch to make the commit on. Typically branch names are prefixed with refs/heads/ in @@ -660,6 +677,7 @@ However it is recommended that a filedeleteall command preceed all filemodify, filecopy and filerename commands in the same commit, as filedeleteall wipes the branch clean (see below).

+

The LF after the command is optional (it used to be required).

author

An author command may optionally appear, if the author information might differ from the committer information. If author is omitted @@ -971,10 +989,11 @@ branch from an existing commit without creating a new commit.

        'reset' SP <ref> LF
         ('from' SP <committish> LF)?
-        LF
+ LF?

For a detailed description of <ref> and <committish> see above under commit and from.

+

The LF after the command is optional (it used to be required).

The reset command can also be used to create lightweight (non-annotated) tags. For example:

@@ -1009,6 +1028,10 @@ byte count or delimited with a terminating line. Real frontends intended for production-quality conversions should always use the exact byte count format, as it is more robust and performs better. The delimited format is intended primarily for testing fast-import.

+

Comment lines appearing within the <raw> part of data commands +are always taken to be part of the body of the data and are therefore +never ignored by fast-import. This makes it safe to import any +file/message content whose lines might start with #.

Exact byte count format @@ -1020,12 +1043,16 @@ Exact byte count format 
        'data' SP <count> LF
-        <raw> LF
+ <raw> LF?

where <count> is the exact number of bytes appearing within <raw>. The value of <count> is expressed as an ASCII decimal integer. The LF on either side of <raw> is not included in <count> and will not be included in the imported data.

+

The LF after <raw> is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if <raw> did not end with an LF.

Delimited format @@ -1041,7 +1068,8 @@ Delimited format 
        'data' SP '<<' <delim> LF
         <raw> LF
-        <delim> LF
+ <delim> LF + LF?

where <delim> is the chosen delimiter string. The string <delim> must not appear on a line by itself within <raw>, as otherwise @@ -1049,6 +1077,7 @@ fast-import will think the data ends earlier than it really does. The LF<raw> is part of <raw>. This is one of the limitations of the delimited format, it is impossible to supply a data chunk which does not have an LF as its last byte.

+

The LF after <delim> LF is optional (it used to be required).

checkpoint

@@ -1057,7 +1086,7 @@ save out all current branch refs, tags and marks.

        'checkpoint' LF
-        LF
+ LF?

Note that fast-import automatically switches packfiles when the current packfile reaches --max-pack-size, or 4 GiB, whichever limit is @@ -1072,6 +1101,31 @@ and long running imports, or when they need to allow another Git process access to a branch. However given that a 30 GiB Subversion repository can be loaded into Git through fast-import in about 3 hours, explicit checkpointing may not be necessary.

+

The LF after the command is optional (it used to be required).

+

progress

+

Causes fast-import to print the entire progress line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import's internal state.

+
+
+
        'progress' SP <any> LF
+        LF?
+
+

The <any> part of the command may contain any sequence of bytes +that does not contain LF. The LF after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example:

+
+
+
+
+
frontend | git-fast-import | sed 's/^progress //'
+
+
+

Placing a progress command immediately after a checkpoint will +inform the reader when the checkpoint has been completed and it +can safely access the refs that fast-import updated.

Tips and Tricks

@@ -1144,6 +1198,13 @@ last year), consider expending some extra CPU time and supplying This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository.

+

Include Some Progress Messages

+

Every once in a while have your frontend emit a progress message +to fast-import. The contents of the messages are entirely free-form, +so one suggestion would be to output the current month and year +each time the current commit date moves into the next month. +Your users will feel better knowing how much of the data stream +has been processed.

Packfile Optimization

@@ -1248,7 +1309,7 @@ memory footprint (less than 2.7 MiB per active branch).

diff --git a/git-fast-import.txt b/git-fast-import.txt index 30ee98d17..0a019dd2e 100644 --- a/git-fast-import.txt +++ b/git-fast-import.txt @@ -176,6 +176,15 @@ results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters unexpected input. +Stream Comments +~~~~~~~~~~~~~~~ +To aid in debugging frontends fast-import ignores any line that +begins with `#` (ASCII pound/hash) up to and including the line +ending `LF`. A comment line may contain any sequence of bytes +that does not contain an LF and therefore may be used to include +any detailed debugging information that might be specific to the +frontend and useful when inspecting a fast-import data stream. + Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select @@ -289,6 +298,11 @@ and control the current import process. More detailed discussion This command is optional and is not needed to perform an import. +`progress`:: + Causes fast-import to echo the entire line to its own + standard output. This command is optional and is not needed + to perform an import. + `commit` ~~~~~~~~ Create or update a branch with a new commit, recording one logical @@ -303,7 +317,7 @@ change to the project. ('from' SP LF)? ('merge' SP LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall)* - LF + LF? .... where `` is the name of the branch to make the commit on. @@ -334,6 +348,8 @@ all `filemodify`, `filecopy` and `filerename` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). +The `LF` after the command is optional (it used to be required). + `author` ^^^^^^^^ An `author` command may optionally appear, if the author information @@ -645,12 +661,14 @@ branch from an existing commit without creating a new commit. .... 'reset' SP LF ('from' SP LF)? - LF + LF? .... For a detailed description of `` and `` see above under `commit` and `from`. +The `LF` after the command is optional (it used to be required). + The `reset` command can also be used to create lightweight (non-annotated) tags. For example: @@ -689,18 +707,28 @@ intended for production-quality conversions should always use the exact byte count format, as it is more robust and performs better. The delimited format is intended primarily for testing fast-import. +Comment lines appearing within the `` part of `data` commands +are always taken to be part of the body of the data and are therefore +never ignored by fast-import. This makes it safe to import any +file/message content whose lines might start with `#`. + Exact byte count format:: The frontend must specify the number of bytes of data. + .... 'data' SP LF - LF + LF? .... + where `` is the exact number of bytes appearing within ``. The value of `` is expressed as an ASCII decimal integer. The `LF` on either side of `` is not included in `` and will not be included in the imported data. ++ +The `LF` after `` is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if `` did not end with an `LF`. Delimited format:: A delimiter string is used to mark the end of the data. @@ -712,6 +740,7 @@ Delimited format:: 'data' SP '<<' LF LF LF + LF? .... + where `` is the chosen delimiter string. The string `` @@ -720,6 +749,8 @@ fast-import will think the data ends earlier than it really does. The `LF` immediately trailing `` is part of ``. This is one of the limitations of the delimited format, it is impossible to supply a data chunk which does not have an LF as its last byte. ++ +The `LF` after ` LF` is optional (it used to be required). `checkpoint` ~~~~~~~~~~~~ @@ -728,7 +759,7 @@ save out all current branch refs, tags and marks. .... 'checkpoint' LF - LF + LF? .... Note that fast-import automatically switches packfiles when the current @@ -747,6 +778,32 @@ process access to a branch. However given that a 30 GiB Subversion repository can be loaded into Git through fast-import in about 3 hours, explicit checkpointing may not be necessary. +The `LF` after the command is optional (it used to be required). + +`progress` +~~~~~~~~~~ +Causes fast-import to print the entire `progress` line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import's internal state. + +.... + 'progress' SP LF + LF? +.... + +The `` part of the command may contain any sequence of bytes +that does not contain `LF`. The `LF` after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example: + +==== + frontend | git-fast-import | sed 's/^progress //' +==== + +Placing a `progress` command immediately after a `checkpoint` will +inform the reader when the `checkpoint` has been completed and it +can safely access the refs that fast-import updated. Tips and Tricks --------------- @@ -840,6 +897,15 @@ This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. +Include Some Progress Messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Every once in a while have your frontend emit a `progress` message +to fast-import. The contents of the messages are entirely free-form, +so one suggestion would be to output the current month and year +each time the current commit date moves into the next month. +Your users will feel better knowing how much of the data stream +has been processed. + Packfile Optimization --------------------- diff --git a/git-reflog.html b/git-reflog.html index 673dd8c65..0cfdab8dd 100644 --- a/git-reflog.html +++ b/git-reflog.html @@ -291,7 +291,8 @@ tip, are removed from the reflog. This is typically not used directly by the end users — instead, see git-gc(1).

The subcommand "show" (which is also the default, in the absense of any subcommands) will take all the normal log options, and show the log of -the current branch. It is basically an alias for git log -g --abbrev-commit +HEAD, which will cover all recent actions, including branch switches. +It is basically an alias for git log -g --abbrev-commit --pretty=oneline, see git-log(1).

OPTIONS

@@ -360,7 +361,7 @@ them.

diff --git a/git-reflog.txt b/git-reflog.txt index 89bc9c51e..29b7d9f5f 100644 --- a/git-reflog.txt +++ b/git-reflog.txt @@ -32,7 +32,8 @@ directly by the end users -- instead, see gitlink:git-gc[1]. The subcommand "show" (which is also the default, in the absense of any subcommands) will take all the normal log options, and show the log of -the current branch. It is basically an alias for 'git log -g --abbrev-commit +`HEAD`, which will cover all recent actions, including branch switches. +It is basically an alias for 'git log -g --abbrev-commit --pretty=oneline', see gitlink:git-log[1]. -- 2.26.2