diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 23 | ||||
| -rw-r--r-- | Documentation/fetch-options.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-fetch.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 17 | ||||
| -rw-r--r-- | Documentation/merge-options.txt | 16 | ||||
| -rw-r--r-- | Documentation/merge-pull-opts.txt | 14 | ||||
| -rw-r--r-- | Documentation/tutorial.txt | 167 |
8 files changed, 214 insertions, 55 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 741f14c..bb9533f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -49,22 +49,25 @@ install: man $(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1) $(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7) -# 'include' dependencies -$(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \ - diff-format.txt diff-options.txt -$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \ - diff-format.txt diff-options.txt -$(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt -$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt +# +# Determine "include::" file references in asciidoc files. +# +TEXTFILES = $(wildcard *.txt) +DEPFILES = $(TEXTFILES:%.txt=%.dep) -$(patsubst %,%.1,git-merge git-pull): merge-pull-opts.txt -$(patsubst %,%.html,git-merge git-pull): merge-pull-opts.txt +%.dep : %.txt + @rm -f $@ + @$(foreach dep, $(shell grep include:: $< | sed -e 's/include::/ /' -e 's/\[\]//'), \ + echo $(<:%.txt=%.html) $(<:%.txt=%.1) : $(dep) >> $@; ) + +-include $(DEPFILES) git.7: ../README + clean: - rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html + rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html *.dep %.html : %.txt asciidoc -b xhtml11 -d manpage -f asciidoc.conf $< diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt new file mode 100644 index 0000000..12d12b2 --- /dev/null +++ b/Documentation/fetch-options.txt @@ -0,0 +1,14 @@ +-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:: + +-t, \--tags:: + +-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/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 73f8a99..438240c 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,7 +8,7 @@ git-fetch - Download objects and a head from another repository. SYNOPSIS -------- -'git-fetch' <repository> <refspec>... +'git-fetch' <options> <repository> <refspec>... DESCRIPTION @@ -17,24 +17,16 @@ Fetches named heads or tags from another repository, along with the objects necessary to complete them. The ref names and their object names of fetched refs are stored -in $GIT_DIR/FETCH_HEAD. This information is left for a later merge +in `.git/FETCH_HEAD`. This information is left for a later merge operation done by "git resolve" or "git octopus". OPTIONS ------- -include::pull-fetch-param.txt[] +include::fetch-options.txt[] --a, \--append:: - Append ref names and object names of fetched refs to the - existing contents of $GIT_DIR/FETCH_HEAD. Without this - option old data in $GIT_DIR/FETCH_HEAD will be overwritten. +include::pull-fetch-param.txt[] --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. SEE ALSO diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index b3ef19b..904e2fc 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -19,7 +19,7 @@ which drives multiple merge strategy scripts. OPTIONS ------- -include::merge-pull-opts.txt[] +include::merge-options.txt[] <msg>:: The commit message to be used for the merge commit (in case diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 7ebb08d..c65ca9a 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -20,21 +20,18 @@ Note that you can use `.` (current directory) as the <repository> to pull from the local repository -- this is useful when merging local branches into the current branch. + OPTIONS ------- -include::pull-fetch-param.txt[] +include::merge-options.txt[] --a, \--append:: - Append ref names and object names of fetched refs to the - existing contents of `$GIT_DIR/FETCH_HEAD`. Without this - option old data in `$GIT_DIR/FETCH_HEAD` will be overwritten. +include::fetch-options.txt[] -include::merge-pull-opts.txt[] +include::pull-fetch-param.txt[] include::merge-strategies.txt[] - EXAMPLES -------- @@ -72,7 +69,7 @@ $ git fetch origin master:origin +pu:pu maint:maint $ git pull . origin ------------------------------------------------ + -Here, a typical `$GIT_DIR/remotes/origin` file from a +Here, a typical `.git/remotes/origin` file from a `git-clone` operation is used in combination with command line options to `git-fetch` to first update multiple branches of the local repository and then @@ -85,7 +82,7 @@ known to have already obtained and made available all the necessary objects. -Pull of multiple branches from one repository using `$GIT_DIR/remotes` file:: +Pull of multiple branches from one repository using `.git/remotes` file:: + ------------------------------------------------ $ cat .git/remotes/origin @@ -98,7 +95,7 @@ $ git checkout master $ git pull origin ------------------------------------------------ + -Here, a typical `$GIT_DIR/remotes/origin` file from a +Here, a typical `.git/remotes/origin` file from a `git-clone` operation has been hand-modified to include the branch-mapping of additional remote and local heads directly. A single `git-pull` operation while diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt new file mode 100644 index 0000000..eebaf3a --- /dev/null +++ b/Documentation/merge-options.txt @@ -0,0 +1,16 @@ +-n, \--no-summary:: + Do not show diffstat at the end of the merge. + +--no-commit:: + Perform the merge but pretend the merge failed and do + not autocommit, to give the user a chance to inspect and + further tweak the merge result before committing. + + +-s <strategy>, \--strategy=<strategy>:: + Use the given merge strategy; can be supplied more than + once to specify them in the order they should be tried. + If there is no `-s` option, a built-in list of strategies + is used instead (`git-merge-resolve` when merging a single + head, `git-merge-octopus` otherwise). + diff --git a/Documentation/merge-pull-opts.txt b/Documentation/merge-pull-opts.txt deleted file mode 100644 index d9164a0..0000000 --- a/Documentation/merge-pull-opts.txt +++ /dev/null @@ -1,14 +0,0 @@ --n, --no-summary:: - Do not show diffstat at the end of the merge. - ---no-commit:: - Perform the merge but pretend the merge failed and do - not autocommit, to give the user a chance to inspect and - further tweak the merge result before committing. - --s <strategy>:: - use that merge strategy; can be given more than once to - specify them in the order they should be tried. If - there is no `-s` option, built-in list of strategies is - used instead (`git-merge-resolve` when merging a single - head, `git-merge-octopus` otherwise). diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 214673d..6d2c153 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -301,7 +301,7 @@ all with a sequence of simple shell commands: ------------------------------------------------ tree=$(git-write-tree) commit=$(echo 'Initial commit' | git-commit-tree $tree) -git-update-ref HEAD $(commit) +git-update-ref HEAD $commit ------------------------------------------------ which will say: @@ -836,14 +836,14 @@ source. Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want to merge the work we did on the `mybranch` branch into the `master` branch (which is currently our `HEAD` too). To do that, there's a nice -script called `git resolve`, which wants to know which branches you want +script called `git merge`, which wants to know which branches you want to resolve and what the merge is all about: ------------ -git resolve HEAD mybranch "Merge work in mybranch" +git merge "Merge work in mybranch" HEAD mybranch ------------ -where the third argument is going to be used as the commit message if +where the first argument is going to be used as the commit message if the merge can be resolved automatically. Now, in this case we've intentionally created a situation where the @@ -851,12 +851,14 @@ merge will need to be fixed up by hand, though, so git will do as much of it as it can automatically (which in this case is just merge the `example` file, which had no differences in the `mybranch` branch), and say: - Simple merge failed, trying Automatic merge - Auto-merging hello. + Trying really trivial in-index merge... + fatal: Merge requires file-level merging + Nope. + ... merge: warning: conflicts during merge ERROR: Merge conflict in hello. fatal: merge program failed - Automatic merge failed, fix up by hand + Automatic merge failed/prevented; fix up by hand which is way too verbose, but it basically tells you that it failed the really trivial merge ("Simple merge") and did an "Automatic merge" @@ -928,7 +930,7 @@ resolve to get the "upstream changes" back to your branch. ------------ git checkout mybranch -git resolve HEAD master "Merge upstream changes." +git merge "Merge upstream changes." HEAD master ------------ This outputs something like this (the actual commit object names @@ -1103,6 +1105,155 @@ the above are equivalent to: . `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100` +How does the merge work? +------------------------ + +We said this tutorial shows what plumbing does to help you cope +with the porcelain that isn't flushing, but we so far did not +talk about how the merge really works. If you are following +this tutorial the first time, I'd suggest to skip to "Publishing +your work" section and come back here later. + +OK, still with me? To give us an example to look at, let's go +back to the earlier repository with "hello" and "example" file, +and bring ourselves back to the pre-merge state: + +------------ +$ git show-branch --more=3 master mybranch +! [master] Merge work in mybranch + * [mybranch] Merge work in mybranch +-- +++ [master] Merge work in mybranch +++ [master^2] Some work. +++ [master^] Some fun. +------------ + +Remember, before running `git merge`, our `master` head was at +"Some fun." commit, while our `mybranch` head was at "Some +work." commit. + +------------ +$ git checkout mybranch +$ git reset --hard master^2 +$ git checkout master +$ git reset --hard master^ +------------ + +After rewinding, the commit structure should look like this: + +------------ +$ git show-branch +* [master] Some fun. + ! [mybranch] Some work. +-- + + [mybranch] Some work. ++ [master] Some fun. +++ [mybranch^] New day. +------------ + +Now we are ready to experiment with the merge by hand. + +`git merge` command, when merging two branches, uses 3-way merge +algorithm. First, it finds the common ancestor between them. +The command it uses is `git-merge-base`: + +------------ +$ mb=$(git-merge-base HEAD mybranch) +------------ + +The command writes the commit object name of the common ancestor +to the standard output, so we captured its output to a variable, +because we will be using it in the next step. BTW, the common +ancestor commit is the "New day." commit in this case. You can +tell it by: + +------------ +$ git-name-rev $mb +my-first-tag +------------ + +After finding out a common ancestor commit, the second step is +this: + +------------ +$ git-read-tree -m -u $mb HEAD mybranch +------------ + +This is the same `git-read-tree` command we have already seen, +but it takes three trees, unlike previous examples. This reads +the contents of each tree into different 'stage' in the index +file (the first tree goes to stage 1, the second stage 2, +etc.). After reading three trees into three stages, the paths +that are the same in all three stages are 'collapsed' into stage +0. Also paths that are the same in two of three stages are +collapsed into stage 0, taking the SHA1 from either stage 2 or +stage 3, whichever is different from stage 1 (i.e. only one side +changed from the common ancestor). + +After 'collapsing' operation, paths that are different in three +trees are left in non-zero stages. At this point, you can +inspect the index file with this command: + +------------ +$ git-ls-files --stage +100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello +------------ + +In our example of only two files, we did not have unchanged +files so only 'example' resulted in collapsing, but in real-life +large projects, only small number of files change in one commit, +and this 'collapsing' tends to trivially merge most of the paths +fairly quickly, leaving only the real changes in non-zero stages. + +To look at only non-zero stages, use `\--unmerged` flag: + +------------ +$ git-ls-files --unmerged +100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello +100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello +------------ + +The next step of merging is to merge these three versions of the +file, using 3-way merge. This is done by giving +`git-merge-one-file` command as one of the arguments to +`git-merge-index` command: + +------------ +$ git-merge-index git-merge-one-file hello +Auto-merging hello. +merge: warning: conflicts during merge +ERROR: Merge conflict in hello. +fatal: merge program failed +------------ + +`git-merge-one-file` script is called with parameters to +describe those three versions, and is responsible to leave the +merge results in the working tree and register it in the index +file. It is a fairly straightforward shell script, and +eventually calls `merge` program from RCS suite to perform the +file-level 3-way merge. In this case, `merge` detects +conflicts, and the merge result with conflict marks is left in +the working tree, while the index file is updated with the +version from the current branch (this is to make `git diff` +useful after this step). This can be seen if you run `ls-files +--stage` again at this point: + +------------ +$ git-ls-files --stage +100644 7f8b141b65fdcee47321e399a2598a235a032422 0 example +100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 0 hello +------------ + +As you can see, there is no unmerged paths in the index file. +This is the state of the index file and the working file after +`git merge` returns control back to you, leaving the conflicting +merge for you to resolve. + + Publishing your work -------------------- |