git for CVS users

From: Junio C Hamano Date: Tue, 27 Dec 2005 08:17:23 +0000 (-0800) Subject: Autogenerated HTML docs for 36de72aa9dc3b7daf8cf2770c840f39bb0d2ae70 X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=1a4e841b439ba014b365999c3a6b9e2be3740bd8;p=git.git Autogenerated HTML docs for 36de72aa9dc3b7daf8cf2770c840f39bb0d2ae70 --- 1a4e841b439ba014b365999c3a6b9e2be3740bd8 diff --git a/cvs-migration.html b/cvs-migration.html new file mode 100644 index 00000000..d3ccbe14 --- /dev/null +++ b/cvs-migration.html @@ -0,0 +1,525 @@ + + + + + + +git for CVS users + + + +

Ok, so you're a CVS user. That's ok, it's a treatable condition, and the +first step to recovery is admitting you have a problem. The fact that +you are reading this file means that you may be well on that path +already.

The thing about CVS is that it absolutely sucks as a source control +manager, and you'll thus be happy with almost anything else. git, +however, may be a bit too different (read: "good") for your taste, and +does a lot of things differently.

One particular suckage of CVS is very hard to work around: CVS is +basically a tool for tracking file history, while git is a tool for +tracking project history. This sometimes causes problems if you are +used to doing very strange things in CVS, in particular if you're doing +things like making branches of just a subset of the project. git can't +track that, since git never tracks things on the level of an individual +file, only on the whole project level.

The good news is that most people don't do that, and in fact most sane +people think it's a bug in CVS that makes it tag (and check in changes) +one file at a time. So most projects you'll ever see will use CVS +as if it was sane. In which case you'll find it very easy indeed to +move over to git.

First off: this is not a git tutorial. See +Documentation/tutorial.txt for how git +actually works. This is more of a random collection of gotcha's +and notes on converting from CVS to git.

Second: CVS has the notion of a "repository" as opposed to the thing +that you're actually working in (your working directory, or your +"checked out tree"). git does not have that notion at all, and all git +working directories are the repositories. However, you can easily +emulate the CVS model by having one special "global repository", which +people can synchronize with. See details later, but in the meantime +just keep in mind that with git, every checked out working tree will +have a full revision control history of its own.

Importing a CVS archive

Ok, you have an old project, and you want to at least give git a chance +to see how it performs. The first thing you want to do (after you've +gone through the git tutorial, and generally familiarized yourself with +how to commit stuff etc in git) is to create a git'ified version of your +CVS archive.

Happily, that's very easy indeed. git will do it for you, although git +will need the help of a program called "cvsps":

http://www.cobite.com/cvsps/

which is not actually related to git at all, but which makes CVS usage +look almost sane (ie you almost certainly want to have it even if you +decide to stay with CVS). However, git will want at least version 2.1 +of cvsps (available at the address above), and in fact will currently +refuse to work with anything else.

Once you've gotten (and installed) cvsps, you may or may not want to get +any more familiar with it, but make sure it is in your path. After that, +the magic command line is

git cvsimport -v -d <cvsroot> -C <destination> <module>

which will do exactly what you'd think it does: it will create a git +archive of the named CVS module. The new archive will be created in the +subdirectory named <destination>; it'll be created if it doesn't exist. +Default is the local directory.

It can take some time to actually do the conversion for a large archive +since it involves checking out from CVS every revision of every file, +and the conversion script is reasonably chatty unless you omit the -v +option, but on some not very scientific tests it averaged about twenty +revisions per second, so a medium-sized project should not take more +than a couple of minutes. For larger projects or remote repositories, +the process may take longer.

After the (initial) import is done, the CVS archive's current head +revision will be checked out — thus, you can start adding your own +changes right away.

The import is incremental, i.e. if you call it again next month it'll +fetch any CVS updates that have been happening in the meantime. The +cut-off is date-based, so don't change the branches that were imported +from CVS.

You can merge those updates (or, in fact, a different CVS branch) into +your main branch:

git resolve HEAD origin "merge with current CVS HEAD"

The HEAD revision from CVS is named "origin", not "HEAD", because git +already uses "HEAD". (If you don't like origin, use cvsimport's +-o option to change it.)

Emulating CVS behaviour

So, by now you are convinced you absolutely want to work with git, but +at the same time you absolutely have to have a central repository. +Step back and think again. Okay, you still need a single central +repository? There are several ways to go about that:

+
+Designate a person responsible to pull all branches. Make the +repository of this person public, and make every team member +pull regularly from it. +
+
+
+Set up a public repository with read/write access for every team +member. Use "git pull/push" as you used "cvs update/commit". Be +sure that your repository is up to date before pushing, just +like you used to do with "cvs commit"; your push will fail if +what you are pushing is not up to date. +
+
+
+Make the repository of every team member public. It is the +responsibility of each single member to pull from every other +team member. +
+

CVS annotate

So, something has gone wrong, and you don't know whom to blame, and +you're an ex-CVS user and used to do "cvs annotate" to see who caused +the breakage. You're looking for the "git annotate", and it's just +claiming not to find such a script. You're annoyed.

Yes, that's right. Core git doesn't do "annotate", although it's +technically possible, and there are at least two specialized scripts out +there that can be used to get equivalent information (see the git +mailing list archives for details).

git has a couple of alternatives, though, that you may find sufficient +or even superior depending on your use. One is called "git-whatchanged" +(for obvious reasons) and the other one is called "pickaxe" ("a tool for +the software archeologist").

The "git-whatchanged" script is a truly trivial script that can give you +a good overview of what has changed in a file or a directory (or an +arbitrary list of files or directories). The "pickaxe" support is an +additional layer that can be used to further specify exactly what you're +looking for, if you already know the specific area that changed.

Let's step back a bit and think about the reason why you would +want to do "cvs annotate a-file.c" to begin with.

You would use "cvs annotate" on a file when you have trouble +with a function (or even a single "if" statement in a function) +that happens to be defined in the file, which does not do what +you want it to do. And you would want to find out why it was +written that way, because you are about to modify it to suit +your needs, and at the same time you do not want to break its +current callers. For that, you are trying to find out why the +original author did things that way in the original context.

Many times, it may be enough to see the commit log messages of +commits that touch the file in question, possibly along with the +patches themselves, like this:

$ git-whatchanged -p a-file.c

This will show log messages and patches for each commit that +touches a-file.

This, however, may not be very useful when this file has many +modifications that are not related to the piece of code you are +interested in. You would see many log messages and patches that +do not have anything to do with the piece of code you are +interested in. As an example, assuming that you have this piece +of code that you are interested in in the HEAD version:

if (frotz) {
+        nitfol();
+}

you would use git-rev-list and git-diff-tree like this:

$ git-rev-list HEAD |
+  git-diff-tree --stdin -v -p -S'if (frotz) {
+        nitfol();
+}'

We have already talked about the "--stdin" form of git-diff-tree +command that reads the list of commits and compares each commit +with its parents (otherwise you should go back and read the tutorial). +The git-whatchanged command internally runs +the equivalent of the above command, and can be used like this:

$ git-whatchanged -p -S'if (frotz) {
+        nitfol();
+}'

When the -S option is used, git-diff-tree command outputs +differences between two commits only if one tree has the +specified string in a file and the corresponding file in the +other tree does not. The above example looks for a commit that +has the "if" statement in it in a file, but its parent commit +does not have it in the same shape in the corresponding file (or +the other way around, where the parent has it and the commit +does not), and the differences between them are shown, along +with the commit message (thanks to the -v flag). It does not +show anything for commits that do not touch this "if" statement.

Also, in the original context, the same statement might have +appeared at first in a different file and later the file was +renamed to "a-file.c". CVS annotate would not help you to go +back across such a rename, but git would still help you in such +a situation. For that, you can give the -C flag to +git-diff-tree, like this:

$ git-whatchanged -p -C -S'if (frotz) {
+        nitfol();
+}'

When the -C flag is used, file renames and copies are followed. +So if the "if" statement in question happens to be in "a-file.c" +in the current HEAD commit, even if the file was originally +called "o-file.c" and then renamed in an earlier commit, or if +the file was created by copying an existing "o-file.c" in an +earlier commit, you will not lose track. If the "if" statement +did not change across such a rename or copy, then the commit that +does rename or copy would not show in the output, and if the +"if" statement was modified while the file was still called +"o-file.c", it would find the commit that changed the statement +when it was in "o-file.c".

+ + + +

Note

The current version of "git-diff-tree -C" is not eager + enough to find copies, and it will miss the fact that a-file.c + was created by copying o-file.c unless o-file.c was somehow + changed in the same commit.

You can use the —pickaxe-all flag in addition to the -S flag. +This causes the differences from all the files contained in +those two commits, not just the differences between the files +that contain this changed "if" statement:

$ git-whatchanged -p -C -S'if (frotz) {
+        nitfol();
+}' --pickaxe-all

+ + + +

Note

This option is called "—pickaxe-all" because -S + option is internally called "pickaxe", a tool for software + archaeologists.

+ + + diff --git a/cvs-migration.txt b/cvs-migration.txt new file mode 100644 index 00000000..dc9387b6 --- /dev/null +++ b/cvs-migration.txt @@ -0,0 +1,248 @@ +git for CVS users +================= + +Ok, so you're a CVS user. That's ok, it's a treatable condition, and the +first step to recovery is admitting you have a problem. The fact that +you are reading this file means that you may be well on that path +already. + +The thing about CVS is that it absolutely sucks as a source control +manager, and you'll thus be happy with almost anything else. git, +however, may be a bit 'too' different (read: "good") for your taste, and +does a lot of things differently. + +One particular suckage of CVS is very hard to work around: CVS is +basically a tool for tracking 'file' history, while git is a tool for +tracking 'project' history. This sometimes causes problems if you are +used to doing very strange things in CVS, in particular if you're doing +things like making branches of just a subset of the project. git can't +track that, since git never tracks things on the level of an individual +file, only on the whole project level. + +The good news is that most people don't do that, and in fact most sane +people think it's a bug in CVS that makes it tag (and check in changes) +one file at a time. So most projects you'll ever see will use CVS +'as if' it was sane. In which case you'll find it very easy indeed to +move over to git. + +First off: this is not a git tutorial. See +link:tutorial.html[Documentation/tutorial.txt] for how git +actually works. This is more of a random collection of gotcha's +and notes on converting from CVS to git. + +Second: CVS has the notion of a "repository" as opposed to the thing +that you're actually working in (your working directory, or your +"checked out tree"). git does not have that notion at all, and all git +working directories 'are' the repositories. However, you can easily +emulate the CVS model by having one special "global repository", which +people can synchronize with. See details later, but in the meantime +just keep in mind that with git, every checked out working tree will +have a full revision control history of its own. + + +Importing a CVS archive +----------------------- + +Ok, you have an old project, and you want to at least give git a chance +to see how it performs. The first thing you want to do (after you've +gone through the git tutorial, and generally familiarized yourself with +how to commit stuff etc in git) is to create a git'ified version of your +CVS archive. + +Happily, that's very easy indeed. git will do it for you, although git +will need the help of a program called "cvsps": + + http://www.cobite.com/cvsps/ + +which is not actually related to git at all, but which makes CVS usage +look almost sane (ie you almost certainly want to have it even if you +decide to stay with CVS). However, git will want 'at least' version 2.1 +of cvsps (available at the address above), and in fact will currently +refuse to work with anything else. + +Once you've gotten (and installed) cvsps, you may or may not want to get +any more familiar with it, but make sure it is in your path. After that, +the magic command line is + + git cvsimport -v -d -C + +which will do exactly what you'd think it does: it will create a git +archive of the named CVS module. The new archive will be created in the +subdirectory named ; it'll be created if it doesn't exist. +Default is the local directory. + +It can take some time to actually do the conversion for a large archive +since it involves checking out from CVS every revision of every file, +and the conversion script is reasonably chatty unless you omit the '-v' +option, but on some not very scientific tests it averaged about twenty +revisions per second, so a medium-sized project should not take more +than a couple of minutes. For larger projects or remote repositories, +the process may take longer. + +After the (initial) import is done, the CVS archive's current head +revision will be checked out -- thus, you can start adding your own +changes right away. + +The import is incremental, i.e. if you call it again next month it'll +fetch any CVS updates that have been happening in the meantime. The +cut-off is date-based, so don't change the branches that were imported +from CVS. + +You can merge those updates (or, in fact, a different CVS branch) into +your main branch: + + git resolve HEAD origin "merge with current CVS HEAD" + +The HEAD revision from CVS is named "origin", not "HEAD", because git +already uses "HEAD". (If you don't like 'origin', use cvsimport's +'-o' option to change it.) + + +Emulating CVS behaviour +----------------------- + + +So, by now you are convinced you absolutely want to work with git, but +at the same time you absolutely have to have a central repository. +Step back and think again. Okay, you still need a single central +repository? There are several ways to go about that: + +1. Designate a person responsible to pull all branches. Make the +repository of this person public, and make every team member +pull regularly from it. + +2. Set up a public repository with read/write access for every team +member. Use "git pull/push" as you used "cvs update/commit". Be +sure that your repository is up to date before pushing, just +like you used to do with "cvs commit"; your push will fail if +what you are pushing is not up to date. + +3. Make the repository of every team member public. It is the +responsibility of each single member to pull from every other +team member. + + +CVS annotate +------------ + +So, something has gone wrong, and you don't know whom to blame, and +you're an ex-CVS user and used to do "cvs annotate" to see who caused +the breakage. You're looking for the "git annotate", and it's just +claiming not to find such a script. You're annoyed. + +Yes, that's right. Core git doesn't do "annotate", although it's +technically possible, and there are at least two specialized scripts out +there that can be used to get equivalent information (see the git +mailing list archives for details). + +git has a couple of alternatives, though, that you may find sufficient +or even superior depending on your use. One is called "git-whatchanged" +(for obvious reasons) and the other one is called "pickaxe" ("a tool for +the software archeologist"). + +The "git-whatchanged" script is a truly trivial script that can give you +a good overview of what has changed in a file or a directory (or an +arbitrary list of files or directories). The "pickaxe" support is an +additional layer that can be used to further specify exactly what you're +looking for, if you already know the specific area that changed. + +Let's step back a bit and think about the reason why you would +want to do "cvs annotate a-file.c" to begin with. + +You would use "cvs annotate" on a file when you have trouble +with a function (or even a single "if" statement in a function) +that happens to be defined in the file, which does not do what +you want it to do. And you would want to find out why it was +written that way, because you are about to modify it to suit +your needs, and at the same time you do not want to break its +current callers. For that, you are trying to find out why the +original author did things that way in the original context. + +Many times, it may be enough to see the commit log messages of +commits that touch the file in question, possibly along with the +patches themselves, like this: + + $ git-whatchanged -p a-file.c + +This will show log messages and patches for each commit that +touches a-file. + +This, however, may not be very useful when this file has many +modifications that are not related to the piece of code you are +interested in. You would see many log messages and patches that +do not have anything to do with the piece of code you are +interested in. As an example, assuming that you have this piece +of code that you are interested in in the HEAD version: + + if (frotz) { + nitfol(); + } + +you would use git-rev-list and git-diff-tree like this: + + $ git-rev-list HEAD | + git-diff-tree --stdin -v -p -S'if (frotz) { + nitfol(); + }' + +We have already talked about the "\--stdin" form of git-diff-tree +command that reads the list of commits and compares each commit +with its parents (otherwise you should go back and read the tutorial). +The git-whatchanged command internally runs +the equivalent of the above command, and can be used like this: + + $ git-whatchanged -p -S'if (frotz) { + nitfol(); + }' + +When the -S option is used, git-diff-tree command outputs +differences between two commits only if one tree has the +specified string in a file and the corresponding file in the +other tree does not. The above example looks for a commit that +has the "if" statement in it in a file, but its parent commit +does not have it in the same shape in the corresponding file (or +the other way around, where the parent has it and the commit +does not), and the differences between them are shown, along +with the commit message (thanks to the -v flag). It does not +show anything for commits that do not touch this "if" statement. + +Also, in the original context, the same statement might have +appeared at first in a different file and later the file was +renamed to "a-file.c". CVS annotate would not help you to go +back across such a rename, but git would still help you in such +a situation. For that, you can give the -C flag to +git-diff-tree, like this: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' + +When the -C flag is used, file renames and copies are followed. +So if the "if" statement in question happens to be in "a-file.c" +in the current HEAD commit, even if the file was originally +called "o-file.c" and then renamed in an earlier commit, or if +the file was created by copying an existing "o-file.c" in an +earlier commit, you will not lose track. If the "if" statement +did not change across such a rename or copy, then the commit that +does rename or copy would not show in the output, and if the +"if" statement was modified while the file was still called +"o-file.c", it would find the commit that changed the statement +when it was in "o-file.c". + +NOTE: The current version of "git-diff-tree -C" is not eager + enough to find copies, and it will miss the fact that a-file.c + was created by copying o-file.c unless o-file.c was somehow + changed in the same commit. + +You can use the --pickaxe-all flag in addition to the -S flag. +This causes the differences from all the files contained in +those two commits, not just the differences between the files +that contain this changed "if" statement: + + $ git-whatchanged -p -C -S'if (frotz) { + nitfol(); + }' --pickaxe-all + +NOTE: This option is called "--pickaxe-all" because -S + option is internally called "pickaxe", a tool for software + archaeologists. diff --git a/diff-format.txt b/diff-format.txt new file mode 100644 index 00000000..97756ec0 --- /dev/null +++ b/diff-format.txt @@ -0,0 +1,148 @@ +The output format from "git-diff-index", "git-diff-tree" and +"git-diff-files" are very similar. + +These commands all compare two sets of things; what is +compared differs: + +git-diff-index :: + compares the and the files on the filesystem. + +git-diff-index --cached :: + compares the and the index. + +git-diff-tree [-r]

[...]:: + compares the trees named by the two arguments. + +git-diff-files [...]:: + compares the index and the files on the filesystem. + + +An output line is formatted this way: + +------------------------------------------------ +in-place edit :100644 100644 bcd1234... 0123456... M file0 +copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 +rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 +create :000000 100644 0000000... 1234567... A file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 +------------------------------------------------ + +That is, from the left to the right: + +. a colon. +. mode for "src"; 000000 if creation or unmerged. +. a space. +. mode for "dst"; 000000 if deletion or unmerged. +. a space. +. sha1 for "src"; 0\{40\} if creation or unmerged. +. a space. +. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree". +. a space. +. status, followed by optional "score" number. +. a tab or a NUL when '-z' option is used. +. path for "src" +. a tab or a NUL when '-z' option is used; only exists for C or R. +. path for "dst"; only exists for C or R. +. an LF or a NUL when '-z' option is used, to terminate the record. + + is shown as all 0's if a file is new on the filesystem +and it is out of sync with the index. + +Example: + +------------------------------------------------ +:100644 100644 5be4a4...... 000000...... M file.c +------------------------------------------------ + +When `-z` option is not used, TAB, LF, and backslash characters +in pathnames are represented as `\t`, `\n`, and `\\`, +respectively. + + +Generating patches with -p +-------------------------- + +When "git-diff-index", "git-diff-tree", or "git-diff-files" are run +with a '-p' option, they do not produce the output described above; +instead they produce a patch file. + +The patch generation can be customized at two levels. + +1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, + these commands internally invoke "diff" like this: + + diff -L a/ -L b/ -pu ++ +For added files, `/dev/null` is used for . For removed +files, `/dev/null` is used for ++ +The "diff" formatting options can be customized via the +environment variable 'GIT_DIFF_OPTS'. For example, if you +prefer context diff: + + GIT_DIFF_OPTS=-c git-diff-index -p HEAD + + +2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the + program named by it is called, instead of the diff invocation + described above. ++ +For a path that is added, removed, or modified, +'GIT_EXTERNAL_DIFF' is called with 7 parameters: + + path old-file old-hex old-mode new-file new-hex new-mode ++ +where: + + -file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of , + -hex:: are the 40-hexdigit SHA1 hashes, + -mode:: are the octal representation of the file modes. + ++ +The file parameters can point at the user's working file +(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` +when a new file is added), or a temporary file (e.g. `old-file` in the +index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the +temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. + +For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 +parameter, . + + +git specific extension to diff format +------------------------------------- + +What -p option produces is slightly different from the +traditional diff format. + +1. It is preceeded with a "git diff" header, that looks like + this: + + diff --git a/file1 b/file2 ++ +The `a/` and `b/` filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +`/dev/null` is _not_ used in place of `a/` or `b/` filenames. ++ +When rename/copy is involved, `file1` and `file2` show the +name of the source file of the rename/copy and the name of +the file that rename/copy produces, respectively. + +2. It is followed by one or more extended header lines: + + old mode + new mode + deleted file mode + new file mode + copy from + copy to + rename from + rename to + similarity index + dissimilarity index + index .. + +3. TAB, LF, and backslash characters in pathnames are + represented as `\t`, `\n`, and `\\`, respectively. diff --git a/diff-options.txt b/diff-options.txt new file mode 100644 index 00000000..9e574a04 --- /dev/null +++ b/diff-options.txt @@ -0,0 +1,70 @@ +-p:: + Generate patch (see section on generating patches) + +-u:: + Synonym for "-p". + +-z:: + \0 line termination on output + +--name-only:: + Show only names of changed files. + +--name-status:: + Show only names and status of changed files. + +--full-index:: + Instead of the first handful characters, show full + object name of pre- and post-image blob on the "index" + line when generating a patch format output. + +--abbrev[=]:: + Instead of showing the full 40-byte hexadecimal object + name in diff-raw format output and diff-tree header + lines, show only handful dhexigits prefix. This is + independent of --full-index option above, which controls + the diff-patch output format. Non default number of + digits can be specified with --abbrev=. + +-B:: + Break complete rewrite changes into pairs of delete and create. + +-M:: + Detect renames. + +-C:: + Detect copies as well as renames. + +--find-copies-harder:: + For performance reasons, by default, -C option finds copies only + if the original file of the copy was modified in the same + changeset. This flag makes the command + inspect unmodified files as candidates for the source of + copy. This is a very expensive operation for large + projects, so use it with caution. + +-l:: + -M and -C options require O(n^2) processing time where n + is the number of potential rename/copy targets. This + option prevents rename/copy detection from running if + the number of rename/copy targets exceeds the specified + number. + +-S:: + Look for differences that contain the change in . + +--pickaxe-all:: + When -S finds a change, show all the changes in that + changeset, not just the files that contain the change + in . + +-O:: + Output the patch in the order specified in the + , which has one shell glob pattern per line. + +-R:: + Swap two inputs; that is, show differences from index or + on-disk file to tree contents. + +For more detailed explanation on these common options, see also +link:diffcore.html[diffcore documentation]. diff --git a/diffcore.html b/diffcore.html new file mode 100644 index 00000000..4c3b6af7 --- /dev/null +++ b/diffcore.html @@ -0,0 +1,554 @@ + + + + + + +Tweaking diff output + + + +

Introduction

The diff commands git-diff-index, git-diff-files, git-diff-tree, and +git-diff-stages can be told to manipulate differences they find in +unconventional ways before showing diff(1) output. The manipulation +is collectively called "diffcore transformation". This short note +describes what they are and how to use them to produce diff outputs +that are easier to understand than the conventional kind.

The chain of operation

The git-diff-* family works by first comparing two sets of +files:

+
+git-diff-index compares contents of a "tree" object and the + working directory (when --cached flag is not used) or a + "tree" object and the index file (when --cached flag is + used); +
+
+
+git-diff-files compares contents of the index file and the + working directory; +
+
+
+git-diff-tree compares contents of two "tree" objects; +
+
+
+git-diff-stages compares contents of blobs at two stages in an + unmerged index file. +
+

In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +comparison is passed from these commands to what is internally +called "diffcore", in a format similar to what is output when +the -p option is not used. E.g.

in-place edit  :100644 100644 bcd1234... 0123456... M file0
+create         :000000 100644 0000000... 1234567... A file4
+delete         :100644 000000 1234567... 0000000... D file5
+unmerged       :000000 000000 0000000... 0000000... U file6

The diffcore mechanism is fed a list of such comparison results +(each of which is called "filepair", although at this point each +of them talks about a single file), and transforms such a list +into another list. There are currently 6 such transformations:

+
+diffcore-pathspec +
+
+
+diffcore-break +
+
+
+diffcore-rename +
+
+
+diffcore-merge-broken +
+
+
+diffcore-pickaxe +
+
+
+diffcore-order +
+

These are applied in sequence. The set of filepairs git-diff-* +commands find are used as the input to diffcore-pathspec, and +the output from diffcore-pathspec is used as the input to the +next transformation. The final result is then passed to the +output routine and generates either diff-raw format (see Output +format sections of the manual for git-diff-* commands) or +diff-patch format.

diffcore-pathspec: For Ignoring Files Outside Our Consideration

The first transformation in the chain is diffcore-pathspec, and +is controlled by giving the pathname parameters to the +git-diff-* commands on the command line. The pathspec is used +to limit the world diff operates in. It removes the filepairs +outside the specified set of pathnames. E.g. If the input set +of filepairs included:

:100644 100644 bcd1234... 0123456... M junkfile

but the command invocation was "git-diff-files myfile", then the +junkfile entry would be removed from the list because only "myfile" +is under consideration.

Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same.

diffcore-break: For Splitting Up "Complete Rewrites"

The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +used to detect a filepair that represents "complete rewrite" and +break such filepair into two filepairs that represent delete and +create. E.g. If the input contained this filepair:

:100644 100644 bcd1234... 0123456... M file0

and if it detects that the file "file0" is completely rewritten, +it changes it to:

:100644 000000 bcd1234... 0000000... D file0
+:000000 100644 0000000... 0123456... A file0

For the purpose of breaking a filepair, diffcore-break examines +the extent of changes between the contents of the files before +and after modification (i.e. the contents that have "bcd1234…" +and "0123456…" as their SHA1 content ID, in the above +example). The amount of deletion of original contents and +insertion of new material are added together, and if it exceeds +the "break score", the filepair is broken into two. The break +score defaults to 50% of the size of the smaller of the original +and the result (i.e. if the edit shrinks the file, the size of +the result is used; if the edit lengthens the file, the size of +the original is used), and can be customized by giving a number +after "-B" option (e.g. "-B75" to tell it to use 75%).

diffcore-rename: For Detection Renames and Copies

This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(to detect copies as well) to the git-diff-* commands. If the +input contained these filepairs:

:100644 000000 0123456... 0000000... D fileX
+:000000 100644 0000000... 0123456... A file0

and the contents of the deleted file fileX is similar enough to +the contents of the created file file0, then rename detection +merges these filepairs and creates:

:100644 100644 0123456... 0123456... R100 fileX file0

When the "-C" option is used, the original contents of modified files, +and deleted files (and also unmodified files, if the +"--find-copies-harder" option is used) are considered as candidates +of the source files in rename/copy operation. If the input were like +these filepairs, that talk about a modified file fileY and a newly +created file file0:

:100644 100644 0123456... 1234567... M fileY
+:000000 100644 0000000... bcd3456... A file0

the original contents of fileY and the resulting contents of +file0 are compared, and if they are similar enough, they are +changed to:

:100644 100644 0123456... 1234567... M fileY
+:100644 100644 0123456... bcd3456... C100 fileY file0

In both rename and copy detection, the same "extent of changes" +algorithm used in diffcore-break is used to determine if two +files are "similar enough", and can be customized to use +a similarity score different from the default of 50% by giving a +number after the "-M" or "-C" option (e.g. "-M8" to tell it to use +8/10 = 80%).

Note. When the "-C" option is used with --find-copies-harder +option, git-diff-* commands feed unmodified filepairs to +diffcore mechanism as well as modified ones. This lets the copy +detector consider unmodified files as copy source candidates at +the expense of making it slower. Without --find-copies-harder, +git-diff-* commands can detect copies only if the file that was +copied happened to have been modified in the same changeset.

diffcore-merge-broken: For Putting "Complete Rewrites" Back Together

This transformation is used to merge filepairs broken by +diffcore-break, and not transformed into rename/copy by +diffcore-rename, back into a single modification. This always +runs when diffcore-break is used.

For the purpose of merging broken filepairs back, it uses a +different "extent of changes" computation from the ones used by +diffcore-break and diffcore-rename. It counts only the deletion +from the original, and does not count insertion. If you removed +only 10 lines from a 100-line document, even if you added 910 +new lines to make a new 1000-line document, you did not do a +complete rewrite. diffcore-break breaks such a case in order to +help diffcore-rename to consider such filepairs as candidate of +rename/copy detection, but if filepairs broken that way were not +matched with other filepairs to create rename/copy, then this +transformation merges them back into the original +"modification".

The "extent of changes" parameter can be tweaked from the +default 80% (that is, unless more than 80% of the original +material is deleted, the broken pairs are merged back into a +single modification) by giving a second number to -B option, +like these:

+
+-B50/60 (give 50% "break score" to diffcore-break, use 60% + for diffcore-merge-broken). +
+
+
+-B/60 (the same as above, since diffcore-break defaults to 50%). +
+

Note that earlier implementation left a broken pair as a separate +creation and deletion patches. This was an unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently for easier review in case of such +a complete rewrite by showing the entire contents of old version +prefixed with -, followed by the entire contents of new +version prefixed with +.

diffcore-pickaxe: For Detecting Addition/Deletion of Specified String

This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-S option and the --pickaxe-all option to the git-diff-* +commands.

When diffcore-pickaxe is in use, it checks if there are +filepairs whose "original" side has the specified string and +whose "result" side does not. Such a filepair represents "the +string appeared in this changeset". It also checks for the +opposite case that loses the specified string.

When --pickaxe-all is not in effect, diffcore-pickaxe leaves +only such filepairs that touch the specified string in its +output. When --pickaxe-all is used, diffcore-pickaxe leaves all +filepairs intact if there is such a filepair, or makes the +output empty otherwise. The latter behaviour is designed to +make reviewing of the changes in the context of the whole +changeset easier.

diffcore-order: For Sorting the Output Based on Filenames

This is used to reorder the filepairs according to the user's +(or project's) taste, and is controlled by the -O option to the +git-diff-* commands.

This takes a text file each of whose lines is a shell glob +pattern. Filepairs that match a glob pattern on an earlier line +in the file are output before ones that match a later line, and +filepairs that do not match any glob pattern are output last.

As an example, a typical orderfile for the core git probably +would look like this:

README
+Makefile
+Documentation
+*.h
+*.c
+t

+ + + diff --git a/diffcore.txt b/diffcore.txt new file mode 100644 index 00000000..cb4e5620 --- /dev/null +++ b/diffcore.txt @@ -0,0 +1,275 @@ +Tweaking diff output +==================== +June 2005 + + +Introduction +------------ + +The diff commands git-diff-index, git-diff-files, git-diff-tree, and +git-diff-stages can be told to manipulate differences they find in +unconventional ways before showing diff(1) output. The manipulation +is collectively called "diffcore transformation". This short note +describes what they are and how to use them to produce diff outputs +that are easier to understand than the conventional kind. + + +The chain of operation +---------------------- + +The git-diff-* family works by first comparing two sets of +files: + + - git-diff-index compares contents of a "tree" object and the + working directory (when '\--cached' flag is not used) or a + "tree" object and the index file (when '\--cached' flag is + used); + + - git-diff-files compares contents of the index file and the + working directory; + + - git-diff-tree compares contents of two "tree" objects; + + - git-diff-stages compares contents of blobs at two stages in an + unmerged index file. + +In all of these cases, the commands themselves compare +corresponding paths in the two sets of files. The result of +comparison is passed from these commands to what is internally +called "diffcore", in a format similar to what is output when +the -p option is not used. E.g. + +------------------------------------------------ +in-place edit :100644 100644 bcd1234... 0123456... M file0 +create :000000 100644 0000000... 1234567... A file4 +delete :100644 000000 1234567... 0000000... D file5 +unmerged :000000 000000 0000000... 0000000... U file6 +------------------------------------------------ + +The diffcore mechanism is fed a list of such comparison results +(each of which is called "filepair", although at this point each +of them talks about a single file), and transforms such a list +into another list. There are currently 6 such transformations: + +- diffcore-pathspec +- diffcore-break +- diffcore-rename +- diffcore-merge-broken +- diffcore-pickaxe +- diffcore-order + +These are applied in sequence. The set of filepairs git-diff-\* +commands find are used as the input to diffcore-pathspec, and +the output from diffcore-pathspec is used as the input to the +next transformation. The final result is then passed to the +output routine and generates either diff-raw format (see Output +format sections of the manual for git-diff-\* commands) or +diff-patch format. + + +diffcore-pathspec: For Ignoring Files Outside Our Consideration +--------------------------------------------------------------- + +The first transformation in the chain is diffcore-pathspec, and +is controlled by giving the pathname parameters to the +git-diff-* commands on the command line. The pathspec is used +to limit the world diff operates in. It removes the filepairs +outside the specified set of pathnames. E.g. If the input set +of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was "git-diff-files myfile", then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. + +Implementation note. For performance reasons, git-diff-tree +uses the pathname parameters on the command line to cull set of +filepairs it feeds the diffcore mechanism itself, and does not +use diffcore-pathspec, but the end result is the same. + + +diffcore-break: For Splitting Up "Complete Rewrites" +---------------------------------------------------- + +The second transformation in the chain is diffcore-break, and is +controlled by the -B option to the git-diff-* commands. This is +used to detect a filepair that represents "complete rewrite" and +break such filepair into two filepairs that represent delete and +create. E.g. If the input contained this filepair: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M file0 +------------------------------------------------ + +and if it detects that the file "file0" is completely rewritten, +it changes it to: + +------------------------------------------------ +:100644 000000 bcd1234... 0000000... D file0 +:000000 100644 0000000... 0123456... A file0 +------------------------------------------------ + +For the purpose of breaking a filepair, diffcore-break examines +the extent of changes between the contents of the files before +and after modification (i.e. the contents that have "bcd1234..." +and "0123456..." as their SHA1 content ID, in the above +example). The amount of deletion of original contents and +insertion of new material are added together, and if it exceeds +the "break score", the filepair is broken into two. The break +score defaults to 50% of the size of the smaller of the original +and the result (i.e. if the edit shrinks the file, the size of +the result is used; if the edit lengthens the file, the size of +the original is used), and can be customized by giving a number +after "-B" option (e.g. "-B75" to tell it to use 75%). + + +diffcore-rename: For Detection Renames and Copies +------------------------------------------------- + +This transformation is used to detect renames and copies, and is +controlled by the -M option (to detect renames) and the -C option +(to detect copies as well) to the git-diff-* commands. If the +input contained these filepairs: + +------------------------------------------------ +:100644 000000 0123456... 0000000... D fileX +:000000 100644 0000000... 0123456... A file0 +------------------------------------------------ + +and the contents of the deleted file fileX is similar enough to +the contents of the created file file0, then rename detection +merges these filepairs and creates: + +------------------------------------------------ +:100644 100644 0123456... 0123456... R100 fileX file0 +------------------------------------------------ + +When the "-C" option is used, the original contents of modified files, +and deleted files (and also unmodified files, if the +"\--find-copies-harder" option is used) are considered as candidates +of the source files in rename/copy operation. If the input were like +these filepairs, that talk about a modified file fileY and a newly +created file file0: + +------------------------------------------------ +:100644 100644 0123456... 1234567... M fileY +:000000 100644 0000000... bcd3456... A file0 +------------------------------------------------ + +the original contents of fileY and the resulting contents of +file0 are compared, and if they are similar enough, they are +changed to: + +------------------------------------------------ +:100644 100644 0123456... 1234567... M fileY +:100644 100644 0123456... bcd3456... C100 fileY file0 +------------------------------------------------ + +In both rename and copy detection, the same "extent of changes" +algorithm used in diffcore-break is used to determine if two +files are "similar enough", and can be customized to use +a similarity score different from the default of 50% by giving a +number after the "-M" or "-C" option (e.g. "-M8" to tell it to use +8/10 = 80%). + +Note. When the "-C" option is used with `\--find-copies-harder` +option, git-diff-\* commands feed unmodified filepairs to +diffcore mechanism as well as modified ones. This lets the copy +detector consider unmodified files as copy source candidates at +the expense of making it slower. Without `\--find-copies-harder`, +git-diff-\* commands can detect copies only if the file that was +copied happened to have been modified in the same changeset. + + +diffcore-merge-broken: For Putting "Complete Rewrites" Back Together +-------------------------------------------------------------------- + +This transformation is used to merge filepairs broken by +diffcore-break, and not transformed into rename/copy by +diffcore-rename, back into a single modification. This always +runs when diffcore-break is used. + +For the purpose of merging broken filepairs back, it uses a +different "extent of changes" computation from the ones used by +diffcore-break and diffcore-rename. It counts only the deletion +from the original, and does not count insertion. If you removed +only 10 lines from a 100-line document, even if you added 910 +new lines to make a new 1000-line document, you did not do a +complete rewrite. diffcore-break breaks such a case in order to +help diffcore-rename to consider such filepairs as candidate of +rename/copy detection, but if filepairs broken that way were not +matched with other filepairs to create rename/copy, then this +transformation merges them back into the original +"modification". + +The "extent of changes" parameter can be tweaked from the +default 80% (that is, unless more than 80% of the original +material is deleted, the broken pairs are merged back into a +single modification) by giving a second number to -B option, +like these: + +* -B50/60 (give 50% "break score" to diffcore-break, use 60% + for diffcore-merge-broken). + +* -B/60 (the same as above, since diffcore-break defaults to 50%). + +Note that earlier implementation left a broken pair as a separate +creation and deletion patches. This was an unnecessary hack and +the latest implementation always merges all the broken pairs +back into modifications, but the resulting patch output is +formatted differently for easier review in case of such +a complete rewrite by showing the entire contents of old version +prefixed with '-', followed by the entire contents of new +version prefixed with '+'. + + +diffcore-pickaxe: For Detecting Addition/Deletion of Specified String +--------------------------------------------------------------------- + +This transformation is used to find filepairs that represent +changes that touch a specified string, and is controlled by the +-S option and the `\--pickaxe-all` option to the git-diff-* +commands. + +When diffcore-pickaxe is in use, it checks if there are +filepairs whose "original" side has the specified string and +whose "result" side does not. Such a filepair represents "the +string appeared in this changeset". It also checks for the +opposite case that loses the specified string. + +When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves +only such filepairs that touch the specified string in its +output. When `\--pickaxe-all` is used, diffcore-pickaxe leaves all +filepairs intact if there is such a filepair, or makes the +output empty otherwise. The latter behaviour is designed to +make reviewing of the changes in the context of the whole +changeset easier. + + +diffcore-order: For Sorting the Output Based on Filenames +--------------------------------------------------------- + +This is used to reorder the filepairs according to the user's +(or project's) taste, and is controlled by the -O option to the +git-diff-* commands. + +This takes a text file each of whose lines is a shell glob +pattern. Filepairs that match a glob pattern on an earlier line +in the file are output before ones that match a later line, and +filepairs that do not match any glob pattern are output last. + +As an example, a typical orderfile for the core git probably +would look like this: + +------------------------------------------------ +README +Makefile +Documentation +*.h +*.c +t +------------------------------------------------ + diff --git a/everyday.html b/everyday.html new file mode 100644 index 00000000..a51a09a6 --- /dev/null +++ b/everyday.html @@ -0,0 +1,815 @@ + + + + + + +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 +repository --- that is everybody, because every working tree of +git is a repository.

In addition, [Individual Developer (Standalone)] commands are +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.

People who play [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.

Basic Repository

Everybody uses these commands to feed and care git repositories.

+
+git-init-db(1) or git-clone(1) to create a + new repository. +
+
+
+git-fsck-objects(1) to validate the repository. +
+
+
+git-prune(1) to garbage collect crufts in the + repository. +
+
+
+git-repack(1) to pack loose objects for efficiency. +
+

Examples

+Check health and remove cruft. +

$ git fsck-objects (1)
+$ git prune
+$ git count-objects (2)
+$ git repack (3)
+$ git prune (4)
+
+(1) running without "--full" is usually cheap and assures the
+repository health reasonably well.
+(2) check how many loose objects there are and how much
+diskspace is wasted by not repacking.
+(3) without "-a" repacks incrementally.  repacking every 4-5MB
+of loose objects accumulation may be a good rule of thumb.
+(4) after repack, prune removes the duplicate loose objects.

+Repack a small project into single pack. +

$ git repack -a -d (1)
+$ git prune
+
+(1) pack all the objects reachable from the refs into one pack
+and remove unneeded other packs

Individual Developer (Standalone)

A standalone individual developer does not exchange patches with +other poeple, and works alone in a single repository, using the +following commands.

+
+git-show-branch(1) to see where you are. +
+
+
+git-log(1) to see what happened. +
+
+
+git-whatchanged(1) to find out where things have + come from. +
+
+
+git-checkout(1) and git-branch(1) to switch + branches. +
+
+
+git-add(1) and git-update-index(1) to manage + the index file. +
+
+
+git-diff(1) and git-status(1) to see what + you are in the middle of doing. +
+
+
+git-commit(1) to advance the current branch. +
+
+
+git-reset(1) and git-checkout(1) (with + pathname parameters) to undo changes. +
+
+
+git-pull(1) with "." as the remote to merge between + local branches. +
+
+
+git-rebase(1) to maintain topic branches. +
+
+
+git-tag(1) to mark known point. +
+

Examples

+Extract a tarball and create a working tree and a new repository to keep track of it. +

$ tar zxf frotz.tar.gz
+$ cd frotz
+$ git-init-db
+$ git add . (1)
+$ git commit -m 'import of frotz source tree.'
+$ git tag v2.43 (2)
+
+(1) add everything under the current directory.
+(2) make a lightweight, unannotated tag.

+Create a topic branch and develop. +

$ git checkout -b alsa-audio (1)
+$ edit/compile/test
+$ git checkout -- curses/ux_audio_oss.c (2)
+$ git add curses/ux_audio_alsa.c (3)
+$ edit/compile/test
+$ git diff (4)
+$ git commit -a -s (5)
+$ edit/compile/test
+$ git reset --soft HEAD^ (6)
+$ edit/compile/test
+$ git diff ORIG_HEAD (7)
+$ git commit -a -c ORIG_HEAD (8)
+$ git checkout master (9)
+$ git pull . alsa-audio (10)
+$ git log --since='3 days ago' (11)
+$ git log v2.43.. curses/ (12)
+
+(1) create a new topic branch.
+(2) revert your botched changes in "curses/ux_audio_oss.c".
+(3) you need to tell git if you added a new file; removal and
+modification will be caught if you do "commit -a" later.
+(4) to see what changes you are committing.
+(5) commit everything as you have tested, with your sign-off.
+(6) take the last commit back, keeping what is in the working tree.
+(7) look at the changes since the premature commit we took back.
+(8) redo the commit undone in the previous step, using the message
+you originally wrote.
+(9) switch to the master branch.
+(10) merge a topic branch into your master branch
+(11) review commit logs; other forms to limit output can be
+combined and include --max-count=10 (show 10 commits), --until='2005-12-10'.
+(12) view only the changes that touch what's in curses/
+directory, since v2.43 tag.

Individual Developer (Participant)

A developer working as a participant in a group project needs to +learn how to communicate with others, and uses these commands in +addition to the ones needed by a standalone developer.

+
+git-clone(1) from the upstream to prime your local + repository. +
+
+
+git-pull(1) and git-fetch(1) from "origin" + to keep up-to-date with the upstream. +
+
+
+git-push(1) to shared repository, if you adopt CVS + style shared repository workflow. +
+
+
+git-format-patch(1) to prepare e-mail submission, if + you adopt Linux kernel-style public forum workflow. +
+

Examples

+Clone the upstream and work on it. Feed changes to upstream. +

$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
+$ 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 pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL (5)
+$ git reset --hard ORIG_HEAD (6)
+$ git prune (7)
+$ git fetch --tags (8)
+
+(1) repeat as needed.
+(2) extract patches from your branch for e-mail submission.
+(3) "pull" fetches from "origin" by default and merges into the
+current branch.
+(4) immediately after pulling, look at the changes done upstream
+since last time we checked, only in the
+area we are interested in.
+(5) fetch from a specific branch from a specific repository and merge.
+(6) revert the pull.
+(7) garbage collect leftover objects from reverted pull.
+(8) from time to time, obtain official tags from the "origin"
+and store them under .git/refs/tags/.

+Push into another repository. +

satellite$ git clone mothership:frotz/.git frotz (1)
+satellite$ cd frotz
+satellite$ cat .git/remotes/origin (2)
+URL: mothership:frotz/.git
+Pull: master:origin
+satellite$ echo 'Push: master:satellite' >>.git/remotes/origin (3)
+satellite$ edit/compile/test/commit
+satellite$ git push origin (4)
+
+mothership$ cd frotz
+mothership$ git checkout master
+mothership$ git pull . satellite (5)
+
+(1) mothership machine has a frotz repository under your home
+directory; clone from it to start a repository on the satellite
+machine.
+(2) clone creates this file by default.  It arranges "git pull"
+to fetch and store the master branch head of mothership machine
+to local "origin" branch.
+(3) arrange "git push" to push local "master" branch to
+"satellite" branch of the mothership machine.
+(4) push will stash our work away on "satellite" branch on the
+mothership machine.  You could use this as a back-up method.
+(5) on mothership machine, merge the work done on the satellite
+machine into the master branch.

+Branch off of a specific tag. +

$ git checkout -b private2.6.14 v2.6.14 (1)
+$ edit/compile/test; git commit -a
+$ git checkout master
+$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
+  git am -3 -k (2)
+
+(1) create a private branch based on a well known (but somewhat behind)
+tag.
+(2) forward port all changes in private2.6.14 branch to master branch
+without a formal "merging".

Integrator

A fairly central person acting as the integrator in a group +project receives changes made by others, reviews and integrates +them and publishes the result for others to use, using these +commands in addition to the ones needed by participants.

+
+git-am(1) to apply patches e-mailed in from your + contributors. +
+
+
+git-pull(1) to merge from your trusted lieutenants. +
+
+
+git-format-patch(1) to prepare and send suggested + alternative to contributors. +
+
+
+git-revert(1) to undo botched commits. +
+
+
+git-push(1) to publish the bleeding edge. +
+

Examples

+My typical GIT day. +

$ git status (1)
+$ git show-branch (2)
+$ mailx (3)
+& s 2 3 4 5 ./+to-apply
+& s 7 8 ./+hold-linus
+& q
+$ git checkout master
+$ git am -3 -i -s -u ./+to-apply (4)
+$ compile/test
+$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus (5)
+$ git checkout topic/one && git rebase master (6)
+$ git checkout pu && git reset --hard master (7)
+$ git pull . topic/one topic/two && git pull . hold/linus (8)
+$ git checkout maint
+$ git cherry-pick master~4 (9)
+$ compile/test
+$ git tag -s -m 'GIT 0.99.9x' v0.99.9x (10)
+$ git fetch ko && git show-branch master maint 'tags/ko-*' (11)
+$ git push ko (12)
+$ git push ko v0.99.9x (13)
+
+(1) see what I was in the middle of doing, if any.
+(2) see what topic branches I have and think about how ready
+they are.
+(3) read mails, save ones that are applicable, and save others
+that are not quite ready.
+(4) apply them, interactively, with my sign-offs.
+(5) create topic branch as needed and apply, again with my
+sign-offs.
+(6) rebase internal topic branch that has not been merged to the
+master, nor exposed as a part of a stable branch.
+(7) restart "pu" every time from the master.
+(8) and bundle topic branches still cooking.
+(9) backport a critical fix.
+(10) create a signed tag.
+(11) make sure I did not accidentally rewind master beyond what I
+already pushed out.  "ko" shorthand points at the repository I have
+at kernel.org, and looks like this:
+    $ cat .git/remotes/ko
+    URL: kernel.org:/pub/scm/git/git.git
+    Pull: master:refs/tags/ko-master
+    Pull: maint:refs/tags/ko-maint
+    Push: master
+    Push: +pu
+    Push: maint
+In the output from "git show-branch", "master" should have
+everything "ko-master" has.
+(12) push out the bleeding edge.
+(13) push the tag out, too.

Repository Administration

A repository administrator uses the following tools to set up +and maintain access to the repository by developers.

+
+git-daemon(1) to allow anonymous download from + repository. +
+
+
+git-shell(1) can be used as a restricted login shell + for shared central repository users. +
+

update hook howto has a good +example of managing a shared central repository.

Examples

+Run git-daemon to serve /pub/scm from inetd. +

$ grep git /etc/inet.conf
+git     stream  tcp     nowait  nobody \
+  /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm

The actual configuration line should be on one line.

+Give push/pull only access to developers. +

$ grep git /etc/passwd (1)
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
+david:x:1003:1003::/home/david:/usr/bin/git-shell
+$ grep git /etc/shells (2)
+/usr/bin/git-shell
+
+(1) log-in shell is set to /usr/bin/git-shell, which does not
+allow anything but "git push" and "git pull".  The users should
+get an ssh access to the machine.
+(2) in many distributions /etc/shells needs to list what is used
+as the login shell.

+CVS-style shared repository. +

$ grep git /etc/group (1)
+git:x:9418:alice,bob,cindy,david
+$ cd /home/devo.git
+$ ls -l (2)
+  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
+  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
+  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
+  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
+  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
+  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
+$ ls -l hooks/update (3)
+  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
+$ cat info/allowed-users (4)
+refs/heads/master       alice\|cindy
+refs/heads/doc-update   bob
+refs/tags/v[0-9]*       david
+
+(1) place the developers into the same git group.
+(2) and make the shared repository writable by the group.
+(3) use update-hook example by Carl from Documentation/howto/
+for branch policy control.
+(4) alice and cindy can push into master, only bob can push into doc-update.
+david is the release manager and is the only person who can
+create and push version tags.

+HTTP server to support dumb protocol transfer. +

dev$ git update-server-info (1)
+dev$ ftp user@isp.example.com (2)
+ftp> cp -r .git /home/user/myproject.git
+
+(1) make sure your info/refs and objects/info/packs are up-to-date
+(2) upload to public HTTP server hosted by your ISP.

+ + + diff --git a/everyday.txt b/everyday.txt new file mode 100644 index 00000000..3ab9b916 --- /dev/null +++ b/everyday.txt @@ -0,0 +1,441 @@ +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. + +<> commands are needed by people who has a +repository --- that is everybody, because every working tree of +git is a repository. + +In addition, <> commands are +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 +<> section as well. + +People who play <> role need to learn some more +commands in addition to the above. + +<> commands are for system +administrators who are responsible to care and feed git +repositories to support developers. + + +Basic Repository[[Basic Repository]] +------------------------------------ + +Everybody uses these commands to feed and care 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-prune[1] to garbage collect crufts in the + repository. + + * gitlink:git-repack[1] to pack loose objects for efficiency. + +Examples +~~~~~~~~ + +Check health and remove cruft.:: ++ +------------ +$ git fsck-objects <1> +$ git prune +$ git count-objects <2> +$ git repack <3> +$ git prune <4> + +<1> running without "--full" is usually cheap and assures the +repository health reasonably well. +<2> check how many loose objects there are and how much +diskspace is wasted by not repacking. +<3> without "-a" repacks incrementally. repacking every 4-5MB +of loose objects accumulation may be a good rule of thumb. +<4> after repack, prune removes the duplicate loose objects. +------------ + +Repack a small project into single pack.:: ++ +------------ +$ git repack -a -d <1> +$ git prune + +<1> pack all the objects reachable from the refs into one pack +and remove unneeded other packs +------------ + + +Individual Developer (Standalone)[[Individual Developer (Standalone)]] +---------------------------------------------------------------------- + +A standalone individual developer does not exchange patches with +other poeple, and works alone in a single repository, using the +following commands. + + * gitlink:git-show-branch[1] to see where you are. + + * 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. + + * gitlink:git-add[1] and gitlink:git-update-index[1] to manage + the index file. + + * gitlink:git-diff[1] and gitlink:git-status[1] to see what + you are in the middle of doing. + + * gitlink:git-commit[1] to advance the current branch. + + * gitlink:git-reset[1] and gitlink:git-checkout[1] (with + pathname parameters) to undo changes. + + * gitlink:git-pull[1] with "." as the remote to merge between + local branches. + + * gitlink:git-rebase[1] to maintain topic branches. + + * gitlink:git-tag[1] to mark known point. + +Examples +~~~~~~~~ + +Extract a tarball and create a working tree and a new repository to keep track of it.:: ++ +------------ +$ tar zxf frotz.tar.gz +$ cd frotz +$ git-init-db +$ git add . <1> +$ git commit -m 'import of frotz source tree.' +$ git tag v2.43 <2> + +<1> add everything under the current directory. +<2> make a lightweight, unannotated tag. +------------ + +Create a topic branch and develop.:: ++ +------------ +$ git checkout -b alsa-audio <1> +$ edit/compile/test +$ git checkout -- curses/ux_audio_oss.c <2> +$ git add curses/ux_audio_alsa.c <3> +$ edit/compile/test +$ git diff <4> +$ git commit -a -s <5> +$ edit/compile/test +$ git reset --soft HEAD^ <6> +$ edit/compile/test +$ git diff ORIG_HEAD <7> +$ git commit -a -c ORIG_HEAD <8> +$ git checkout master <9> +$ git pull . alsa-audio <10> +$ git log --since='3 days ago' <11> +$ git log v2.43.. curses/ <12> + +<1> create a new topic branch. +<2> revert your botched changes in "curses/ux_audio_oss.c". +<3> you need to tell git if you added a new file; removal and +modification will be caught if you do "commit -a" later. +<4> to see what changes you are committing. +<5> commit everything as you have tested, with your sign-off. +<6> take the last commit back, keeping what is in the working tree. +<7> look at the changes since the premature commit we took back. +<8> redo the commit undone in the previous step, using the message +you originally wrote. +<9> switch to the master branch. +<10> merge a topic branch into your master branch +<11> review commit logs; other forms to limit output can be +combined and include --max-count=10 (show 10 commits), --until='2005-12-10'. +<12> view only the changes that touch what's in curses/ +directory, since v2.43 tag. +------------ + + +Individual Developer (Participant)[[Individual Developer (Participant)]] +------------------------------------------------------------------------ + +A developer working as a participant in a group project needs to +learn how to communicate with others, and uses these commands in +addition to the ones needed by a standalone developer. + + * gitlink:git-clone[1] from the upstream to prime your local + repository. + + * gitlink:git-pull[1] and gitlink:git-fetch[1] from "origin" + to keep up-to-date with the upstream. + + * gitlink:git-push[1] to shared repository, if you adopt CVS + style shared repository workflow. + + * gitlink:git-format-patch[1] to prepare e-mail submission, if + you adopt Linux kernel-style public forum workflow. + +Examples +~~~~~~~~ + +Clone the upstream and work on it. Feed changes to upstream.:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6 +$ 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 pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5> +$ git reset --hard ORIG_HEAD <6> +$ git prune <7> +$ git fetch --tags <8> + +<1> repeat as needed. +<2> extract patches from your branch for e-mail submission. +<3> "pull" fetches from "origin" by default and merges into the +current branch. +<4> immediately after pulling, look at the changes done upstream +since last time we checked, only in the +area we are interested in. +<5> fetch from a specific branch from a specific repository and merge. +<6> revert the pull. +<7> garbage collect leftover objects from reverted pull. +<8> from time to time, obtain official tags from the "origin" +and store them under .git/refs/tags/. +------------ + + +Push into another repository.:: ++ +------------ +satellite$ git clone mothership:frotz/.git frotz <1> +satellite$ cd frotz +satellite$ cat .git/remotes/origin <2> +URL: mothership:frotz/.git +Pull: master:origin +satellite$ echo 'Push: master:satellite' >>.git/remotes/origin <3> +satellite$ edit/compile/test/commit +satellite$ git push origin <4> + +mothership$ cd frotz +mothership$ git checkout master +mothership$ git pull . satellite <5> + +<1> mothership machine has a frotz repository under your home +directory; clone from it to start a repository on the satellite +machine. +<2> clone creates this file by default. It arranges "git pull" +to fetch and store the master branch head of mothership machine +to local "origin" branch. +<3> arrange "git push" to push local "master" branch to +"satellite" branch of the mothership machine. +<4> push will stash our work away on "satellite" branch on the +mothership machine. You could use this as a back-up method. +<5> on mothership machine, merge the work done on the satellite +machine into the master branch. +------------ + +Branch off of a specific tag.:: ++ +------------ +$ git checkout -b private2.6.14 v2.6.14 <1> +$ edit/compile/test; git commit -a +$ git checkout master +$ git format-patch -k -m --stdout v2.6.14..private2.6.14 | + git am -3 -k <2> + +<1> create a private branch based on a well known (but somewhat behind) +tag. +<2> forward port all changes in private2.6.14 branch to master branch +without a formal "merging". +------------ + + +Integrator[[Integrator]] +------------------------ + +A fairly central person acting as the integrator in a group +project receives changes made by others, reviews and integrates +them and publishes the result for others to use, using these +commands in addition to the ones needed by participants. + + * gitlink:git-am[1] to apply patches e-mailed in from your + contributors. + + * gitlink:git-pull[1] to merge from your trusted lieutenants. + + * gitlink:git-format-patch[1] to prepare and send suggested + alternative to contributors. + + * gitlink:git-revert[1] to undo botched commits. + + * gitlink:git-push[1] to publish the bleeding edge. + + +Examples +~~~~~~~~ + +My typical GIT day.:: ++ +------------ +$ git status <1> +$ git show-branch <2> +$ mailx <3> +& s 2 3 4 5 ./+to-apply +& s 7 8 ./+hold-linus +& q +$ git checkout master +$ git am -3 -i -s -u ./+to-apply <4> +$ compile/test +$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5> +$ git checkout topic/one && git rebase master <6> +$ git checkout pu && git reset --hard master <7> +$ git pull . topic/one topic/two && git pull . hold/linus <8> +$ git checkout maint +$ git cherry-pick master~4 <9> +$ compile/test +$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10> +$ git fetch ko && git show-branch master maint 'tags/ko-*' <11> +$ git push ko <12> +$ git push ko v0.99.9x <13> + +<1> see what I was in the middle of doing, if any. +<2> see what topic branches I have and think about how ready +they are. +<3> read mails, save ones that are applicable, and save others +that are not quite ready. +<4> apply them, interactively, with my sign-offs. +<5> create topic branch as needed and apply, again with my +sign-offs. +<6> rebase internal topic branch that has not been merged to the +master, nor exposed as a part of a stable branch. +<7> restart "pu" every time from the master. +<8> and bundle topic branches still cooking. +<9> backport a critical fix. +<10> create a signed tag. +<11> make sure I did not accidentally rewind master beyond what I +already pushed out. "ko" shorthand points at the repository I have +at kernel.org, and looks like this: + $ cat .git/remotes/ko + URL: kernel.org:/pub/scm/git/git.git + Pull: master:refs/tags/ko-master + Pull: maint:refs/tags/ko-maint + Push: master + Push: +pu + Push: maint +In the output from "git show-branch", "master" should have +everything "ko-master" has. +<12> push out the bleeding edge. +<13> push the tag out, too. +------------ + + +Repository Administration[[Repository Administration]] +------------------------------------------------------ + +A repository administrator uses the following tools to set up +and maintain access to the repository by developers. + + * gitlink:git-daemon[1] to allow anonymous download from + repository. + + * gitlink:git-shell[1] can be used as a 'restricted login shell' + for shared central repository users. + +link:howto/update-hook-example.txt[update hook howto] has a good +example of managing a shared central repository. + + +Examples +~~~~~~~~ + +Run git-daemon to serve /pub/scm from inetd.:: ++ +------------ +$ grep git /etc/inet.conf +git stream tcp nowait nobody \ + /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm +------------ ++ +The actual configuration line should be on one line. + +Give push/pull only access to developers.:: ++ +------------ +$ grep git /etc/passwd <1> +alice:x:1000:1000::/home/alice:/usr/bin/git-shell +bob:x:1001:1001::/home/bob:/usr/bin/git-shell +cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell +david:x:1003:1003::/home/david:/usr/bin/git-shell +$ grep git /etc/shells <2> +/usr/bin/git-shell + +<1> log-in shell is set to /usr/bin/git-shell, which does not +allow anything but "git push" and "git pull". The users should +get an ssh access to the machine. +<2> in many distributions /etc/shells needs to list what is used +as the login shell. +------------ + +CVS-style shared repository.:: ++ +------------ +$ grep git /etc/group <1> +git:x:9418:alice,bob,cindy,david +$ cd /home/devo.git +$ ls -l <2> + lrwxrwxrwx 1 david git 17 Dec 4 22:40 HEAD -> refs/heads/master + drwxrwsr-x 2 david git 4096 Dec 4 22:40 branches + -rw-rw-r-- 1 david git 84 Dec 4 22:40 config + -rw-rw-r-- 1 david git 58 Dec 4 22:40 description + drwxrwsr-x 2 david git 4096 Dec 4 22:40 hooks + -rw-rw-r-- 1 david git 37504 Dec 4 22:40 index + drwxrwsr-x 2 david git 4096 Dec 4 22:40 info + drwxrwsr-x 4 david git 4096 Dec 4 22:40 objects + drwxrwsr-x 4 david git 4096 Nov 7 14:58 refs + drwxrwsr-x 2 david git 4096 Dec 4 22:40 remotes +$ ls -l hooks/update <3> + -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update +$ cat info/allowed-users <4> +refs/heads/master alice\|cindy +refs/heads/doc-update bob +refs/tags/v[0-9]* david + +<1> place the developers into the same git group. +<2> and make the shared repository writable by the group. +<3> use update-hook example by Carl from Documentation/howto/ +for branch policy control. +<4> alice and cindy can push into master, only bob can push into doc-update. +david is the release manager and is the only person who can +create and push version tags. +------------ + +HTTP server to support dumb protocol transfer.:: ++ +------------ +dev$ git update-server-info <1> +dev$ ftp user@isp.example.com <2> +ftp> cp -r .git /home/user/myproject.git + +<1> make sure your info/refs and objects/info/packs are up-to-date +<2> upload to public HTTP server hosted by your ISP. +------------ diff --git a/fetch-options.txt b/fetch-options.txt new file mode 100644 index 00000000..200c9b24 --- /dev/null +++ b/fetch-options.txt @@ -0,0 +1,24 @@ +-a, \--append:: + Append ref names and object names of fetched refs to the + existing contents of `.git/FETCH_HEAD`. Without this + option old data in `.git/FETCH_HEAD` will be overwritten. + +-f, \--force:: + When `git-fetch` is used with `:` + refspec, it refuses to update the local branch + `` unless the remote branch `` it + fetches is a descendant of ``. This option + overrides that check. + +-t, \--tags:: + By default, the git core utilities will not fetch and store + tags under the same name as the remote repository; ask it + to do so using `--tags`. Using this option will bound the + list of objects pulled to the remote tags. Commits in branches + beyond the tags will be ignored. + +-u, \--update-head-ok:: + By default `git-fetch` refuses to update the head which + corresponds to the current branch. This flag disables the + check. Note that fetching into the current branch will not + update the index and working directory, so use it with care. diff --git a/git-add.html b/git-add.html new file mode 100644 index 00000000..875931a9 --- /dev/null +++ b/git-add.html @@ -0,0 +1,378 @@ + + + + + + +git-add(1) + + + +

SYNOPSIS

git-add [-n] [-v] <file>…

DESCRIPTION

A simple wrapper for git-update-index to add files to the index, +for people used to do "cvs add".

OPTIONS

+<file>… +: +
+ Files to add to the index. +
+
+-n +: +
+ Don't actually add the file(s), just show if they exist. +
+
+-v +: +
+ Be verbose. +
+

DISCUSSION

The list of <file> given to the command is fed to git-ls-files +command to list files that are not registerd in the index and +are not ignored/excluded by $GIT_DIR/info/exclude file or +.gitignore file in each directory. This means two things:

+
+You can put the name of a directory on the command line, and + the command will add all files in it and its subdirectories; +
+
+
+Giving the name of a file that is already in index does not + run git-update-index on that path. +
+

EXAMPLES

+git-add Documentation/\*.txt +

+ Adds all *.txt files that are not in the index under + Documentation directory and its subdirectories. +

Note that the asterisk * is quoted from the shell in this +example; this lets the command to include the files from +subdirectories of Documentation/ directory.

+git-add git-*.sh +

+ Adds all git-*.sh scripts that are not in the index. + Because this example lets shell expand the asterisk + (i.e. you are listing the files explicitly), it does not + add subdir/git-foo.sh to the index. +

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-add.txt b/git-add.txt new file mode 100644 index 00000000..4cae4126 --- /dev/null +++ b/git-add.txt @@ -0,0 +1,75 @@ +git-add(1) +========== + +NAME +---- +git-add - Add files to the index file. + +SYNOPSIS +-------- +'git-add' [-n] [-v] ... + +DESCRIPTION +----------- +A simple wrapper for git-update-index to add files to the index, +for people used to do "cvs add". + + +OPTIONS +------- +...:: + Files to add to the index. + +-n:: + Don't actually add the file(s), just show if they exist. + +-v:: + Be verbose. + + +DISCUSSION +---------- + +The list of given to the command is fed to `git-ls-files` +command to list files that are not registerd in the index and +are not ignored/excluded by `$GIT_DIR/info/exclude` file or +`.gitignore` file in each directory. This means two things: + +. You can put the name of a directory on the command line, and + the command will add all files in it and its subdirectories; + +. Giving the name of a file that is already in index does not + run `git-update-index` on that path. + + +EXAMPLES +-------- +git-add Documentation/\\*.txt:: + + Adds all `\*.txt` files that are not in the index under + `Documentation` directory and its subdirectories. ++ +Note that the asterisk `\*` is quoted from the shell in this +example; this lets the command to include the files from +subdirectories of `Documentation/` directory. + +git-add git-*.sh:: + + Adds all git-*.sh scripts that are not in the index. + Because this example lets shell expand the asterisk + (i.e. you are listing the files explicitly), it does not + add `subdir/git-foo.sh` to the index. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-am.html b/git-am.html new file mode 100644 index 00000000..83459576 --- /dev/null +++ b/git-am.html @@ -0,0 +1,414 @@ + + + + + + +git-am(1) + + + +

SYNOPSIS

git-am [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] <mbox>… +git-am [--skip | --resolved]

DESCRIPTION

Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch.

OPTIONS

+--signoff +: +
+ Add Signed-off-by: line to the commit message, using + the committer identity of yourself. +
+
+--dotest=<dir> +: +
+ Instead of .dotest directory, use <dir> as a working + area to store extracted patches. +
+
+--utf8, --keep +: +
+ Pass -u and -k flags to git-mailinfo (see + git-mailinfo(1)). +
+
+--binary +: +
+ Pass --allow-binary-replacement flag to git-apply + (see git-apply(1)). +
+
+--3way +: +
+ When the patch does not apply cleanly, fall back on + 3-way merge, if the patch records the identity of blobs + it is supposed to apply to, and we have those blobs + locally. +
+
+--skip +: +
+ Skip the current patch. This is only meaningful when + restarting an aborted patch. +
+
+--interactive +: +
+ Run interactively, just like git-applymbox. +
+
+--resolved +: +
+ After a patch failure (e.g. attempting to apply + conflicting patch), the user has applied it by hand and + the index file stores the result of the application. + Make a commit using the authorship and commit log + extracted from the e-mail message and the current index + file, and continue. +
+

DISCUSSION

When initially invoking it, you give it names of the mailboxes +to crunch. Upon seeing the first patch that does not apply, it +aborts in the middle, just like git-applymbox does. You can +recover from this in one of two ways:

+
+skip the current one by re-running the command with --skip + option. +
+
+
+hand resolve the conflict in the working directory, and update + the index file to bring it in a state that the patch should + have produced. Then run the command with --resolved option. +
+

The command refuses to process new mailboxes while .dotest +directory exists, so if you decide to start over from scratch, +run rm -f .dotest before running the command with mailbox +names.

Author

Written by Junio C Hamano <junkio@cox.net>

Documentation

Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-am.txt b/git-am.txt new file mode 100644 index 00000000..a415fe24 --- /dev/null +++ b/git-am.txt @@ -0,0 +1,96 @@ +git-am(1) +========= + +NAME +---- +git-am - Apply a series of patches in a mailbox + + +SYNOPSIS +-------- +'git-am' [--signoff] [--dotest=] [--utf8] [--binary] [--3way] ... +'git-am' [--skip | --resolved] + +DESCRIPTION +----------- +Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch. + +OPTIONS +------- +--signoff:: + Add `Signed-off-by:` line to the commit message, using + the committer identity of yourself. + +--dotest=:: + Instead of `.dotest` directory, use as a working + area to store extracted patches. + +--utf8, --keep:: + Pass `-u` and `-k` flags to `git-mailinfo` (see + gitlink:git-mailinfo[1]). + +--binary:: + Pass `--allow-binary-replacement` flag to `git-apply` + (see gitlink:git-apply[1]). + +--3way:: + When the patch does not apply cleanly, fall back on + 3-way merge, if the patch records the identity of blobs + it is supposed to apply to, and we have those blobs + locally. + +--skip:: + Skip the current patch. This is only meaningful when + restarting an aborted patch. + +--interactive:: + Run interactively, just like git-applymbox. + +--resolved:: + After a patch failure (e.g. attempting to apply + conflicting patch), the user has applied it by hand and + the index file stores the result of the application. + Make a commit using the authorship and commit log + extracted from the e-mail message and the current index + file, and continue. + +DISCUSSION +---------- + +When initially invoking it, you give it names of the mailboxes +to crunch. Upon seeing the first patch that does not apply, it +aborts in the middle, just like 'git-applymbox' does. You can +recover from this in one of two ways: + +. skip the current one by re-running the command with '--skip' + option. + +. hand resolve the conflict in the working directory, and update + the index file to bring it in a state that the patch should + have produced. Then run the command with '--resolved' option. + +The command refuses to process new mailboxes while `.dotest` +directory exists, so if you decide to start over from scratch, +run `rm -f .dotest` before running the command with mailbox +names. + + +SEE ALSO +-------- +gitlink:git-applymbox[1], gitlink:git-applypatch[1]. + + +Author +------ +Written by Junio C Hamano + +Documentation +-------------- +Documentation by Petr Baudis, Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-apply.html b/git-apply.html new file mode 100644 index 00000000..7153716a --- /dev/null +++ b/git-apply.html @@ -0,0 +1,433 @@ + + + + + + +git-apply(1) + + + +

SYNOPSIS

git-apply [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--index-info] [--allow-binary-replacement] [-z] [<patch>…]

DESCRIPTION

Reads supplied diff output and applies it on a git index file +and a work tree.

OPTIONS

+<patch>… +: +
+ The files to read patch from. - can be used to read + from the standard input. +
+
+--stat +: +
+ Instead of applying the patch, output diffstat for the + input. Turns off "apply". +
+
+--numstat +: +
+ Similar to --stat, but shows number of added and + deleted lines in decimal notation and pathname without + abbreviation, to make it more machine friendly. Turns + off "apply". +
+
+--summary +: +
+ Instead of applying the patch, output a condensed + summary of information obtained from git diff extended + headers, such as creations, renames and mode changes. + Turns off "apply". +
+
+--check +: +
+ Instead of applying the patch, see if the patch is + applicable to the current work tree and/or the index + file and detects errors. Turns off "apply". +
+
+--index +: +
+ When --check is in effect, or when applying the patch + (which is the default when none of the options that + disables it is in effect), make sure the patch is + applicable to what the current index file records. If + the file to be patched in the work tree is not + up-to-date, it is flagged as an error. This flag also + causes the index file to be updated. +
+
+--index-info +: +
+ Newer git-diff output has embedded index information + for each blob to help identify the original version that + the patch applies to. When this flag is given, and if + the original version of the blob is available locally, + outputs information about them to the standard output. +
+
+-z +: +
+ When showing the index information, do not munge paths, + but use NUL terminated machine readable format. Without + this flag, the pathnames output will have TAB, LF, and + backslash characters replaced with \t, \n, and \\, + respectively. +
+
+--apply +: +
+ If you use any of the options marked “Turns off + "apply"” above, git-apply reads and outputs the + information you asked without actually applying the + patch. Give this flag after those flags to also apply + the patch. +
+
+--no-add +: +
+ When applying a patch, ignore additions made by the + patch. This can be used to extract common part between + two files by first running diff on them and applying + the result with this option, which would apply the + deletion part but not addition part. +
+
+--allow-binary-replacement +: +
+ When applying a patch, which is a git-enhanced patch + that was prepared to record the pre- and post-image object + name in full, and the path being patched exactly matches + the object the patch applies to (i.e. "index" line's + pre-image object name is what is in the working tree), + and the post-image object is available in the object + database, use the post-image object as the patch + result. This allows binary files to be patched in a + very limited way. +
+

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by Junio C Hamano

GIT

Part of the git(7) suite

+ + + diff --git a/git-apply.txt b/git-apply.txt new file mode 100644 index 00000000..626e2815 --- /dev/null +++ b/git-apply.txt @@ -0,0 +1,104 @@ +git-apply(1) +============ + +NAME +---- +git-apply - Apply patch on a git index file and a work tree + + +SYNOPSIS +-------- +'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--index-info] [--allow-binary-replacement] [-z] [...] + +DESCRIPTION +----------- +Reads supplied diff output and applies it on a git index file +and a work tree. + +OPTIONS +------- +...:: + The files to read patch from. '-' can be used to read + from the standard input. + +--stat:: + Instead of applying the patch, output diffstat for the + input. Turns off "apply". + +--numstat:: + Similar to \--stat, but shows number of added and + deleted lines in decimal notation and pathname without + abbreviation, to make it more machine friendly. Turns + off "apply". + +--summary:: + Instead of applying the patch, output a condensed + summary of information obtained from git diff extended + headers, such as creations, renames and mode changes. + Turns off "apply". + +--check:: + Instead of applying the patch, see if the patch is + applicable to the current work tree and/or the index + file and detects errors. Turns off "apply". + +--index:: + When --check is in effect, or when applying the patch + (which is the default when none of the options that + disables it is in effect), make sure the patch is + applicable to what the current index file records. If + the file to be patched in the work tree is not + up-to-date, it is flagged as an error. This flag also + causes the index file to be updated. + +--index-info:: + Newer git-diff output has embedded 'index information' + for each blob to help identify the original version that + the patch applies to. When this flag is given, and if + the original version of the blob is available locally, + outputs information about them to the standard output. + +-z:: + When showing the index information, do not munge paths, + but use NUL terminated machine readable format. Without + this flag, the pathnames output will have TAB, LF, and + backslash characters replaced with `\t`, `\n`, and `\\`, + respectively. + +--apply:: + If you use any of the options marked ``Turns off + "apply"'' above, git-apply reads and outputs the + information you asked without actually applying the + patch. Give this flag after those flags to also apply + the patch. + +--no-add:: + When applying a patch, ignore additions made by the + patch. This can be used to extract common part between + two files by first running `diff` on them and applying + the result with this option, which would apply the + deletion part but not addition part. + +--allow-binary-replacement:: + When applying a patch, which is a git-enhanced patch + that was prepared to record the pre- and post-image object + name in full, and the path being patched exactly matches + the object the patch applies to (i.e. "index" line's + pre-image object name is what is in the working tree), + and the post-image object is available in the object + database, use the post-image object as the patch + result. This allows binary files to be patched in a + very limited way. + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-applymbox.html b/git-applymbox.html new file mode 100644 index 00000000..9c83ace0 --- /dev/null +++ b/git-applymbox.html @@ -0,0 +1,398 @@ + + + + + + +git-applymbox(1) + + + +

SYNOPSIS

git-applymbox [-u] [-k] [-q] [-m] ( -c .dotest/<num> | <mbox> ) [ <signoff> ]

DESCRIPTION

Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch.

OPTIONS

+-q +: +
+ Apply patches interactively. The user will be given + opportunity to edit the log message and the patch before + attempting to apply it. +
+
+-k +: +
+ Usually the program cleans up the Subject: header line + to extract the title line for the commit log message, + among which (1) remove Re: or re:, (2) leading + whitespaces, (3) [ up to ], typically [PATCH], and + then prepends "[PATCH] ". This flag forbids this + munging, and is most useful when used to read back git + format-patch --mbox output. +
+
+-m +: +
+ Patches are applied with git-apply command, and unless + it cleanly applies without fuzz, the processing fails. + With this flag, if a tree that the patch applies cleanly + is found in a repository, the patch is applied to the + tree and then a 3-way merge between the resulting tree + and the current tree. +
+
+-u +: +
+ By default, the commit log message, author name and + author email are taken from the e-mail without any + charset conversion, after minimally decoding MIME + transfer encoding. This flag causes the resulting + commit to be encoded in utf-8 by transliterating them. + Note that the patch is always used as is without charset + conversion, even with this flag. +
+
+-c .dotest/<num> +: +
+ When the patch contained in an e-mail does not cleanly + apply, the command exits with an error message. The + patch and extracted message are found in .dotest/, and + you could re-run git applymbox with -c .dotest/<num> + flag to restart the process after inspecting and fixing + them. +
+
+<mbox> +: +
+ The name of the file that contains the e-mail messages + with patches. This file should be in the UNIX mailbox + format. See SubmittingPatches document to learn about + the formatting convention for e-mail submission. +
+
+<signoff> +: +
+ The name of the file that contains your "Signed-off-by" + line. See SubmittingPatches document to learn what + "Signed-off-by" line means. You can also just say + yes, true, me, or please to use an automatically + generated "Signed-off-by" line based on your committer + identity. +
+

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-applymbox.txt b/git-applymbox.txt new file mode 100644 index 00000000..f74c6a49 --- /dev/null +++ b/git-applymbox.txt @@ -0,0 +1,92 @@ +git-applymbox(1) +================ + +NAME +---- +git-applymbox - Apply a series of patches in a mailbox + + +SYNOPSIS +-------- +'git-applymbox' [-u] [-k] [-q] [-m] ( -c .dotest/ | ) [ ] + +DESCRIPTION +----------- +Splits mail messages in a mailbox into commit log message, +authorship information and patches, and applies them to the +current branch. + + +OPTIONS +------- +-q:: + Apply patches interactively. The user will be given + opportunity to edit the log message and the patch before + attempting to apply it. + +-k:: + Usually the program 'cleans up' the Subject: header line + to extract the title line for the commit log message, + among which (1) remove 'Re:' or 're:', (2) leading + whitespaces, (3) '[' up to ']', typically '[PATCH]', and + then prepends "[PATCH] ". This flag forbids this + munging, and is most useful when used to read back 'git + format-patch --mbox' output. + +-m:: + Patches are applied with `git-apply` command, and unless + it cleanly applies without fuzz, the processing fails. + With this flag, if a tree that the patch applies cleanly + is found in a repository, the patch is applied to the + tree and then a 3-way merge between the resulting tree + and the current tree. + +-u:: + By default, the commit log message, author name and + author email are taken from the e-mail without any + charset conversion, after minimally decoding MIME + transfer encoding. This flag causes the resulting + commit to be encoded in utf-8 by transliterating them. + Note that the patch is always used as is without charset + conversion, even with this flag. + +-c .dotest/:: + When the patch contained in an e-mail does not cleanly + apply, the command exits with an error message. The + patch and extracted message are found in .dotest/, and + you could re-run 'git applymbox' with '-c .dotest/' + flag to restart the process after inspecting and fixing + them. + +:: + The name of the file that contains the e-mail messages + with patches. This file should be in the UNIX mailbox + format. See 'SubmittingPatches' document to learn about + the formatting convention for e-mail submission. + +:: + The name of the file that contains your "Signed-off-by" + line. See 'SubmittingPatches' document to learn what + "Signed-off-by" line means. You can also just say + 'yes', 'true', 'me', or 'please' to use an automatically + generated "Signed-off-by" line based on your committer + identity. + + +SEE ALSO +-------- +gitlink:git-am[1], gitlink:git-applypatch[1]. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-applypatch.html b/git-applypatch.html new file mode 100644 index 00000000..21551645 --- /dev/null +++ b/git-applypatch.html @@ -0,0 +1,336 @@ + + + + + + +git-applypatch(1) + + + +

SYNOPSIS

git-applypatch <msg> <patch> <info> [<signoff>]

DESCRIPTION

Takes three files <msg>, <patch>, and <info> prepared from an +e-mail message by git-mailinfo, and creates a commit. It is +usually not necessary to use this command directly.

This command can run applypatch-msg, pre-applypatch, and +post-applypatch hooks. See hooks for more +information.

OPTIONS

+<msg> +: +
+ Commit log message (sans the first line, which comes + from e-mail Subject stored in <info>). +
+
+<patch> +: +
+ The patch to apply. +
+
+<info> +: +
+ Author and subject information extracted from e-mail, + used on "author" line and as the first line of the + commit log message. +
+

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-applypatch.txt b/git-applypatch.txt new file mode 100644 index 00000000..5b9037de --- /dev/null +++ b/git-applypatch.txt @@ -0,0 +1,50 @@ +git-applypatch(1) +================= + +NAME +---- +git-applypatch - Apply one patch extracted from an e-mail. + + +SYNOPSIS +-------- +'git-applypatch' [] + +DESCRIPTION +----------- +Takes three files , , and prepared from an +e-mail message by 'git-mailinfo', and creates a commit. It is +usually not necessary to use this command directly. + +This command can run `applypatch-msg`, `pre-applypatch`, and +`post-applypatch` hooks. See link:hooks.html[hooks] for more +information. + + +OPTIONS +------- +:: + Commit log message (sans the first line, which comes + from e-mail Subject stored in ). + +:: + The patch to apply. + +:: + Author and subject information extracted from e-mail, + used on "author" line and as the first line of the + commit log message. + + +Author +------ +Written by Linus Torvalds + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-archimport.html b/git-archimport.html new file mode 100644 index 00000000..c9046603 --- /dev/null +++ b/git-archimport.html @@ -0,0 +1,417 @@ + + + + + + +git-archimport(1) + + + +

SYNOPSIS

git-archimport [ -h ] [ -v ] [ -o ] [ -a ] [ -f ] [ -T ] + [ -D depth ] [ -t tempdir ] + <archive/branch> [ <archive/branch> ]

DESCRIPTION

Imports a project from one or more Arch repositories. It will follow branches +and repositories within the namespaces defined by the <archive/branch> +parameters suppplied. If it cannot find the remote branch a merge comes from +it will just import it as a regular commit. If it can find it, it will mark it +as a merge whenever possible (see discussion below).

The script expects you to provide the key roots where it can start the import +from an initial import or tag type of Arch commit. It will follow and +import new branches within the provided roots.

It expects to be dealing with one project only. If it sees +branches that have different roots, it will refuse to run. In that case, +edit your <archive/branch> parameters to define clearly the scope of the +import.

git-archimport uses tla extensively in the background to access the +Arch repository. +Make sure you have a recent version of tla available in the path. tla must +know about the repositories you pass to git-archimport.

For the initial import git-archimport expects to find itself in an empty +directory. To follow the development of a project that uses Arch, rerun +git-archimport with the same parameters as the initial import to perform +incremental imports.

MERGES

Patch merge data from Arch is used to mark merges in git as well. git +does not care much about tracking patches, and only considers a merge when a +branch incorporates all the commits since the point they forked. The end result +is that git will have a good idea of how far branches have diverged. So the +import process does lose some patch-trading metadata.

Fortunately, when you try and merge branches imported from Arch, +git will find a good merge base, and it has a good chance of identifying +patches that have been traded out-of-sequence between the branches.

OPTIONS

+-h +: +
+ Display usage. +
+
+-v +: +
+ Verbose output. +
+
+-T +: +
+ Many tags. Will create a tag for every commit, reflecting the commit + name in the Arch repository. +
+
+-f +: +
+ Use the fast patchset import strategy. This can be significantly + faster for large trees, but cannot handle directory renames or + permissions changes. The default strategy is slow and safe. +
+
+-o +: +
+ Use this for compatibility with old-style branch names used by + earlier versions of git-archimport. Old-style branch names + were category--branch, whereas new-style branch names are + archive,category--branch--version. +
+
+-D <depth> +: +
+ Follow merge ancestry and attempt to import trees that have been + merged from. Specify a depth greater than 1 if patch logs have been + pruned. +
+
+-a +: +
+ Attempt to auto-register archives at http://mirrors.sourcecontrol.net + This is particularly useful with the -D option. +
+
+-t <tmpdir> +: +
+ Override the default tempdir. +
+
+<archive/branch> +: +
+ Archive/branch identifier in a format that tla log understands. +
+

Author

Written by Martin Langhoff <martin@catalyst.net.nz>.

Documentation

Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-archimport.txt b/git-archimport.txt new file mode 100644 index 00000000..a2bd788f --- /dev/null +++ b/git-archimport.txt @@ -0,0 +1,106 @@ +git-archimport(1) +================= + +NAME +---- +git-archimport - Import an Arch repository into git + + +SYNOPSIS +-------- +`git-archimport` [ -h ] [ -v ] [ -o ] [ -a ] [ -f ] [ -T ] + [ -D depth ] [ -t tempdir ] + [ ] + +DESCRIPTION +----------- +Imports a project from one or more Arch repositories. It will follow branches +and repositories within the namespaces defined by the +parameters suppplied. If it cannot find the remote branch a merge comes from +it will just import it as a regular commit. If it can find it, it will mark it +as a merge whenever possible (see discussion below). + +The script expects you to provide the key roots where it can start the import +from an 'initial import' or 'tag' type of Arch commit. It will follow and +import new branches within the provided roots. + +It expects to be dealing with one project only. If it sees +branches that have different roots, it will refuse to run. In that case, +edit your parameters to define clearly the scope of the +import. + +`git-archimport` uses `tla` extensively in the background to access the +Arch repository. +Make sure you have a recent version of `tla` available in the path. `tla` must +know about the repositories you pass to `git-archimport`. + +For the initial import `git-archimport` expects to find itself in an empty +directory. To follow the development of a project that uses Arch, rerun +`git-archimport` with the same parameters as the initial import to perform +incremental imports. + +MERGES +------ +Patch merge data from Arch is used to mark merges in git as well. git +does not care much about tracking patches, and only considers a merge when a +branch incorporates all the commits since the point they forked. The end result +is that git will have a good idea of how far branches have diverged. So the +import process does lose some patch-trading metadata. + +Fortunately, when you try and merge branches imported from Arch, +git will find a good merge base, and it has a good chance of identifying +patches that have been traded out-of-sequence between the branches. + +OPTIONS +------- + +-h:: + Display usage. + +-v:: + Verbose output. + +-T:: + Many tags. Will create a tag for every commit, reflecting the commit + name in the Arch repository. + +-f:: + Use the fast patchset import strategy. This can be significantly + faster for large trees, but cannot handle directory renames or + permissions changes. The default strategy is slow and safe. + +-o:: + Use this for compatibility with old-style branch names used by + earlier versions of git-archimport. Old-style branch names + were category--branch, whereas new-style branch names are + archive,category--branch--version. + +-D :: + Follow merge ancestry and attempt to import trees that have been + merged from. Specify a depth greater than 1 if patch logs have been + pruned. + +-a:: + Attempt to auto-register archives at http://mirrors.sourcecontrol.net + This is particularly useful with the -D option. + +-t :: + Override the default tempdir. + + +:: + Archive/branch identifier in a format that `tla log` understands. + + +Author +------ +Written by Martin Langhoff . + +Documentation +-------------- +Documentation by Junio C Hamano, Martin Langhoff and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-bisect.html b/git-bisect.html new file mode 100644 index 00000000..36659105 --- /dev/null +++ b/git-bisect.html @@ -0,0 +1,392 @@ + + + + + + +git-bisect(1) + + + +

SYNOPSIS

git bisect <subcommand> <options>

DESCRIPTION

The command takes various subcommands, and different options +depending on the subcommand:

git bisect start [<paths>...]
+git bisect bad <rev>
+git bisect good <rev>
+git bisect reset [<branch>]
+git bisect visualize
+git bisect replay <logfile>
+git bisect log

This command uses git-rev-list --bisect option to help drive +the binary search process to find which change introduced a bug, +given an old "good" commit object name and a later "bad" commit +object name.

The way you use it is:

$ git bisect start
+$ git bisect bad                        # Current version is bad
+$ git bisect good v2.6.13-rc2           # v2.6.13-rc2 was the last version
+                                        # tested that was good

When you give at least one bad and one good versions, it will +bisect the revision tree and say something like:

Bisecting: 675 revisions left to test after this

and check out the state in the middle. Now, compile that kernel, and boot +it. Now, let's say that this booted kernel works fine, then just do

$ git bisect good                       # this one is good

which will now say

Bisecting: 337 revisions left to test after this

and you continue along, compiling that one, testing it, and depending on +whether it is good or bad, you say "git bisect good" or "git bisect bad", +and ask for the next bisection.

Until you have no more left, and you'll have been left with the first bad +kernel rev in "refs/bisect/bad".

Oh, and then after you want to reset to the original head, do a

$ git bisect reset

to get back to the master branch, instead of being in one of the bisection +branches ("git bisect start" will do that for you too, actually: it will +reset the bisection state, and before it does that it checks that you're +not using some old bisection branch).

During the bisection process, you can say

$ git bisect visualize

to see the currently remaining suspects in gitk.

The good/bad input is logged, and git bisect +log shows what you have done so far. You can truncate its +output somewhere and save it in a file, and run

$ git bisect replay that-file

if you find later you made a mistake telling good/bad about a +revision.

If in a middle of bisect session, you know what the bisect +suggested to try next is not a good one to test (e.g. the change +the commit introduces is known not to work in your environment +and you know it does not have anything to do with the bug you +are chasing), you may want to find a near-by commit and try that +instead. It goes something like this:

$ git bisect good/bad                   # previous round was good/bad.
+Bisecting: 337 revisions left to test after this
+$ git bisect visualize                  # oops, that is uninteresting.
+$ git reset --hard HEAD~3               # try 3 revs before what
+                                        # was suggested

Then compile and test the one you chose to try. After that, +tell bisect what the result was as usual.

You can further cut down the number of trials if you know what +part of the tree is involved in the problem you are tracking +down, by giving paths parameters when you say bisect start, +like this:

$ git bisect start arch/i386 include/asm-i386

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-bisect.txt b/git-bisect.txt new file mode 100644 index 00000000..ac4b4965 --- /dev/null +++ b/git-bisect.txt @@ -0,0 +1,136 @@ +git-bisect(1) +============= + +NAME +---- +git-bisect - Find the change that introduced a bug + + +SYNOPSIS +-------- +'git bisect' + +DESCRIPTION +----------- +The command takes various subcommands, and different options +depending on the subcommand: + + git bisect start [...] + git bisect bad + git bisect good + git bisect reset [] + git bisect visualize + git bisect replay + git bisect log + +This command uses 'git-rev-list --bisect' option to help drive +the binary search process to find which change introduced a bug, +given an old "good" commit object name and a later "bad" commit +object name. + +The way you use it is: + +------------------------------------------------ +$ git bisect start +$ git bisect bad # Current version is bad +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version + # tested that was good +------------------------------------------------ + +When you give at least one bad and one good versions, it will +bisect the revision tree and say something like: + +------------------------------------------------ +Bisecting: 675 revisions left to test after this +------------------------------------------------ + +and check out the state in the middle. Now, compile that kernel, and boot +it. Now, let's say that this booted kernel works fine, then just do + +------------------------------------------------ +$ git bisect good # this one is good +------------------------------------------------ + +which will now say + +------------------------------------------------ +Bisecting: 337 revisions left to test after this +------------------------------------------------ + +and you continue along, compiling that one, testing it, and depending on +whether it is good or bad, you say "git bisect good" or "git bisect bad", +and ask for the next bisection. + +Until you have no more left, and you'll have been left with the first bad +kernel rev in "refs/bisect/bad". + +Oh, and then after you want to reset to the original head, do a + +------------------------------------------------ +$ git bisect reset +------------------------------------------------ + +to get back to the master branch, instead of being in one of the bisection +branches ("git bisect start" will do that for you too, actually: it will +reset the bisection state, and before it does that it checks that you're +not using some old bisection branch). + +During the bisection process, you can say + +------------ +$ git bisect visualize +------------ + +to see the currently remaining suspects in `gitk`. + +The good/bad input is logged, and `git bisect +log` shows what you have done so far. You can truncate its +output somewhere and save it in a file, and run + +------------ +$ git bisect replay that-file +------------ + +if you find later you made a mistake telling good/bad about a +revision. + +If in a middle of bisect session, you know what the bisect +suggested to try next is not a good one to test (e.g. the change +the commit introduces is known not to work in your environment +and you know it does not have anything to do with the bug you +are chasing), you may want to find a near-by commit and try that +instead. It goes something like this: + +------------ +$ git bisect good/bad # previous round was good/bad. +Bisecting: 337 revisions left to test after this +$ git bisect visualize # oops, that is uninteresting. +$ git reset --hard HEAD~3 # try 3 revs before what + # was suggested +------------ + +Then compile and test the one you chose to try. After that, +tell bisect what the result was as usual. + +You can further cut down the number of trials if you know what +part of the tree is involved in the problem you are tracking +down, by giving paths parameters when you say `bisect start`, +like this: + +------------ +$ git bisect start arch/i386 include/asm-i386 +------------ + + +Author +------ +Written by Linus Torvalds + +Documentation +------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-branch.html b/git-branch.html new file mode 100644 index 00000000..fb41e087 --- /dev/null +++ b/git-branch.html @@ -0,0 +1,371 @@ + + + + + + +git-branch(1) + + + +

SYNOPSIS

git-branch [-d | -D] [<branchname> [start-point]]

DESCRIPTION

If no argument is provided, show available branches and mark current +branch with star. Otherwise, create a new branch of name <branchname>.

If a starting point is also specified, that will be where the branch is +created, otherwise it will be created at the current HEAD.

OPTIONS

+-d +: +
+ Delete a branch. The branch must be fully merged. +
+
+-D +: +
+ Delete a branch irrespective of its index status. +
+
+<branchname> +: +
+ The name of the branch to create or delete. +
+
+start-point +: +
+ Where to create the branch; defaults to HEAD. This + option has no meaning with -d and -D. +
+

Examples

+Start development off of a know tag +

$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ git branch my2.6.14 v2.6.14 (1)
+$ git checkout my2.6.14
+
+(1) These two steps are the same as "checkout -b my2.6.14 v2.6.14".

+Delete unneeded branch +

$ git clone git://git.kernel.org/.../git.git my.git
+$ cd my.git
+$ git branch -D todo (1)
+
+(1) delete todo branch even if the "master" branch does not have all
+commits from todo branch.

Author

Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>

Documentation

Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-branch.txt b/git-branch.txt new file mode 100644 index 00000000..d20b4757 --- /dev/null +++ b/git-branch.txt @@ -0,0 +1,72 @@ +git-branch(1) +============= + +NAME +---- +git-branch - Create a new branch, or remove an old one. + +SYNOPSIS +-------- +'git-branch' [-d | -D] [ [start-point]] + +DESCRIPTION +----------- +If no argument is provided, show available branches and mark current +branch with star. Otherwise, create a new branch of name . + +If a starting point is also specified, that will be where the branch is +created, otherwise it will be created at the current HEAD. + +OPTIONS +------- +-d:: + Delete a branch. The branch must be fully merged. + +-D:: + Delete a branch irrespective of its index status. + +:: + The name of the branch to create or delete. + +start-point:: + Where to create the branch; defaults to HEAD. This + option has no meaning with -d and -D. + + +Examples +~~~~~~~~ + +Start development off of a know tag:: ++ +------------ +$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 +$ cd my2.6 +$ git branch my2.6.14 v2.6.14 <1> +$ git checkout my2.6.14 + +<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14". +------------ + +Delete unneeded branch:: ++ +------------ +$ git clone git://git.kernel.org/.../git.git my.git +$ cd my.git +$ git branch -D todo <1> + +<1> delete todo branch even if the "master" branch does not have all +commits from todo branch. +------------ + +Author +------ +Written by Linus Torvalds and Junio C Hamano + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list . + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/git-cat-file.html b/git-cat-file.html new file mode 100644 index 00000000..00b05e3b --- /dev/null +++ b/git-cat-file.html @@ -0,0 +1,362 @@ + + + + + + +git-cat-file(1) + + + +

SYNOPSIS

git-cat-file (-t | -s | -e | <type>) <object>

DESCRIPTION

Provides content or type of objects in the repository. The type +is required unless -t is used to find the object type, +or -s is used to find the object size.

OPTIONS

+<object> +: +
+ The sha1 identifier of the object. +
+
+-t +: +
+ Instead of the content, show the object type identified by + <object>. +
+
+-s +: +
+ Instead of the content, show the object size identified by + <object>. +
+
+-e +: +
+ Suppress all output; instead exit with zero status if <object> + exists and is a valid object. +
+
+<type> +: +
+ Typically this matches the real type of <object> but asking + for a type that can trivially be dereferenced from the given + <object> is also permitted. An example is to ask for a + "tree" with <object> being a commit object that contains it, + or to ask for a "blob" with <object> being a tag object that + points at it. +
+

OUTPUT

If -t is specified, one of the <type>.

If -s is specified, the size of the <object> in bytes.

If -e is specified, no output.

Otherwise the raw (though uncompressed) contents of the <object> will +be returned.

Author

Written by Linus Torvalds <torvalds@osdl.org>

Documentation

Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT

Part of the git(7) suite

+ + + diff --git a/git-cat-file.txt b/git-cat-file.txt new file mode 100644 index 00000000..9a7700fa --- /dev/null +++ b/git-cat-file.txt @@ -0,0 +1,67 @@ +git-cat-file(1) +=============== + +NAME +---- +git-cat-file - Provide content or type information for repository objects + + +SYNOPSIS +-------- +'git-cat-file' (-t | -s | -e | )

+<old\|new>-file +	+are files GIT_EXTERNAL_DIFF can use to read the + contents of <old\|new>, +
+<old\|new>-hex +	+are the 40-hexdigit SHA1 hashes, +
+<old\|new>-mode +	+are the octal representation of the file modes. +

+<old\|new>-file +	+are files GIT_EXTERNAL_DIFF can use to read the + contents of <old\|new>, +
+<old\|new>-hex +	+are the 40-hexdigit SHA1 hashes, +
+<old\|new>-mode +	+are the octal representation of the file modes. +

+<old\|new>-file +	+are files GIT_EXTERNAL_DIFF can use to read the + contents of <old\|new>, +
+<old\|new>-hex +	+are the 40-hexdigit SHA1 hashes, +
+<old\|new>-mode +	+are the octal representation of the file modes. +

+<old\|new>-file +	+are files GIT_EXTERNAL_DIFF can use to read the + contents of <old\|new>, +
+<old\|new>-hex +	+are the 40-hexdigit SHA1 hashes, +
+<old\|new>-mode +	+are the octal representation of the file modes. +

+H +	+cached +
+M +	+unmerged +
+R +	+removed/deleted +
+C +	+modifed/changed +
+K +	+to be killed + ? other +

git for CVS users

Importing a CVS archive

Emulating CVS behaviour

CVS annotate

Tweaking diff output

Introduction

The chain of operation

diffcore-pathspec: For Ignoring Files Outside Our Consideration

diffcore-break: For Splitting Up "Complete Rewrites"

diffcore-rename: For Detection Renames and Copies

diffcore-merge-broken: For Putting "Complete Rewrites" Back Together

diffcore-pickaxe: For Detecting Addition/Deletion of Specified String

diffcore-order: For Sorting the Output Based on Filenames

Everyday GIT With 20 Commands Or So

Basic Repository

Examples

Individual Developer (Standalone)

Examples

Individual Developer (Participant)

Examples

Integrator

Examples

Repository Administration

Examples

+git-add(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

DISCUSSION

EXAMPLES

Author

Documentation

GIT

+git-am(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

DISCUSSION

SEE ALSO

Author

Documentation

GIT

+git-apply(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Author

Documentation

GIT

+git-applymbox(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

SEE ALSO

Author

Documentation

GIT

+git-applypatch(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Author

Documentation

GIT

+git-archimport(1) Manual Page +

NAME

SYNOPSIS

DESCRIPTION

MERGES

OPTIONS

Author

Documentation

GIT

+git-bisect(1) Manual Page +

NAME