From 7b8988e113b44b9a2d806dde6161c133750c14e5 Mon Sep 17 00:00:00 2001 From: Thomas Rast Date: Thu, 28 May 2009 11:40:15 +0200 Subject: Documentation: teach stash/pop workflow instead of stash/apply Recent discussion on the list showed some comments in favour of a stash/pop workflow: http://marc.info/?l=git&m=124234911423358&w=2 http://marc.info/?l=git&m=124235348327711&w=2 Change the stash documentation and examples to document pop in its own right (and apply in terms of pop), and use stash/pop in the examples. Signed-off-by: Thomas Rast Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index dbbeb7e7c7..0b88a51d0b 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1520,10 +1520,10 @@ $ git commit -a -m "blorpl: typofix" ------------------------------------------------ After that, you can go back to what you were working on with -`git stash apply`: +`git stash pop`: ------------------------------------------------ -$ git stash apply +$ git stash pop ------------------------------------------------ -- cgit v1.2.3 From 57f6ec029090f64377ec5c0926b6e2e39b0caa4f Mon Sep 17 00:00:00 2001 From: Ori Avtalion Date: Fri, 7 Aug 2009 17:24:21 +0300 Subject: Change mentions of "git programs" to "git commands" Most of the docs and printouts refer to "commands" when discussing what the end users call via the "git" top-level program. We should refer them as "git programs" when we discuss the fact that the commands are implemented as separate programs, but in other contexts, it is better to use the term "git commands" consistently. Signed-off-by: Ori Avtalion Signed-off-by: Nanako Shiraishi Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 0b88a51d0b..67ebffa568 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4131,7 +4131,7 @@ What does this mean? `git rev-list` is the original version of the revision walker, which _always_ printed a list of revisions to stdout. It is still functional, -and needs to, since most new Git programs start out as scripts using +and needs to, since most new Git commands start out as scripts using `git rev-list`. `git rev-parse` is not as important any more; it was only used to filter out -- cgit v1.2.3 From a75d7b54097ef0d0945cbe673a9940d6c561f95c Mon Sep 17 00:00:00 2001 From: Felipe Contreras Date: Sat, 24 Oct 2009 11:31:32 +0300 Subject: Use 'fast-forward' all over the place It's a compound word. Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 67ebffa568..269ec475e6 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1384,7 +1384,7 @@ were merged. However, if the current branch is a descendant of the other--so every commit present in the one is already contained in the other--then git -just performs a "fast forward"; the head of the current branch is moved +just performs a "fast-forward"; the head of the current branch is moved forward to point at the head of the merged-in branch, without any new commits being created. @@ -1719,7 +1719,7 @@ producing a default commit message documenting the branch and repository that you pulled from. (But note that no such commit will be created in the case of a -<>; instead, your branch will just be +<>; instead, your branch will just be updated to point to the latest commit from the upstream branch.) The `git pull` command can also be given "." as the "remote" repository, @@ -1943,7 +1943,7 @@ $ git push ssh://yourserver.com/~you/proj.git master ------------------------------------------------- As with `git fetch`, `git push` will complain if this does not result in a -<>; see the following section for details on +<>; see the following section for details on handling this case. Note that the target of a "push" is normally a @@ -1976,7 +1976,7 @@ details. What to do when a push fails ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a push would not result in a <> of the +If a push would not result in a <> of the remote branch, then it will fail with an error like: ------------------------------------------------- @@ -2115,7 +2115,7 @@ $ git checkout release && git pull Important note! If you have any local changes in these branches, then this merge will create a commit object in the history (with no local -changes git will simply do a "Fast forward" merge). Many people dislike +changes git will simply do a "fast-forward" merge). Many people dislike the "noise" that this creates in the Linux history, so you should avoid doing this capriciously in the "release" branch, as these noisy commits will become part of the permanent history when you ask Linus to pull @@ -2729,9 +2729,9 @@ In the previous example, when updating an existing branch, "git fetch" checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new -commit. Git calls this process a <>. +commit. Git calls this process a <>. -A fast forward looks something like this: +A fast-forward looks something like this: ................................................ o--o--o--o <-- old head of the branch -- cgit v1.2.3 From e63ec003b2a0c89f0c1cbc4862dcef7c4a14a785 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Sun, 22 Nov 2009 23:26:18 +0100 Subject: user-manual: Document that "git merge" doesn't like uncommited changes. We explain the user why uncommited changes can be problematic with merge, and point to "commit" and "stash" for the solution. While talking about commited Vs uncommited changes, we also make it clear that the result of a merge is normally commited. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 67ebffa568..c32dd87c8b 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1183,7 +1183,23 @@ $ git merge branchname ------------------------------------------------- merges the development in the branch "branchname" into the current -branch. If there are conflicts--for example, if the same file is +branch. + +A merge is made by combining the changes made in "branchname" and the +changes made up to the latest commit in your current branch since +their histories forked. The work tree is overwritten by the result of +the merge when this combining is done cleanly, or overwritten by a +half-merged results when this combining results in conflicts. +Therefore, if you have uncommitted changes touching the same files as +the ones impacted by the merge, Git will refuse to proceed. Most of +the time, you will want to commit your changes before you can merge, +and if you don't, then linkgit:git-stash[1] can take these changes +away while you're doing the merge, and reapply them afterwards. + +If the changes are independant enough, Git will automatically complete +the merge and commit the result (or reuse an existing commit in case +of <>, see below). On the other hand, +if there are conflicts--for example, if the same file is modified in two different ways in the remote branch and the local branch--then you are warned; the output may look something like this: @@ -1679,7 +1695,7 @@ Sharing development with others Getting updates with git pull ----------------------------- -After you clone a repository and make a few changes of your own, you +After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates and merge them into your own work. -- cgit v1.2.3 From 73a1d050c47dfa0fc758eedd9d3bb60b7449e14f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Sun, 22 Nov 2009 10:47:04 +0100 Subject: User Manual: Write "Git" instead of "GIT" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In the Table of Contents, there is a notable inconsistency: first there is "GIT Glossary", followed by "Git Quick Reference" on the very next line. Running "grep -c" on user-manual.txt, I find 780 occurrrences of "git", 37 occurrences of "Git", and 9 occurrences of "GIT". In general, "git" is the preferred spelling, except at the beginning of a sentence. Therefore, change "GIT Glossary" to "Git Glossary" for consistency with the rest of the document. Looking at the other eight occurrences of "GIT" I found one other occurrence that should be changed: * The mention of "StGIT". Looking at the web pages for "Stacked Git" at http://www.procode.org/stgit, I only saw the spelling "StGit", except in http://wiki.procode.org/cgi-bin/wiki.cgi/StGIT_Tutorial, but that page was last updated in 2006. The other seven occurrences should not be changed: * Three occurrences were in the output of 'git show-branch' run on the git.git repository. * One occurrence was in the output of 'git cat-file'. * One occurrence was as part of the file name "GIT-VERSION-GEN". * Two occurrences were in comments in scripts quoted in a description of Tony Luck's workflow. Signed-off-by: Björn Gustavsson Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 269ec475e6..27d97b6d1e 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2569,7 +2569,7 @@ them again with linkgit:git-am[1]. Other tools ----------- -There are numerous other tools, such as StGIT, which exist for the +There are numerous other tools, such as StGit, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. @@ -4275,7 +4275,7 @@ You see, Git is actually the best tool to find out about the source of Git itself! [[glossary]] -GIT Glossary +Git Glossary ============ include::glossary-content.txt[] -- cgit v1.2.3 From 6a5d0b0a90789ed92cb87f1b69cfeef2a1db3566 Mon Sep 17 00:00:00 2001 From: Ralf Wildenhues Date: Sun, 31 Jan 2010 14:24:39 +0100 Subject: Fix typos in technical documentation. Signed-off-by: Ralf Wildenhues Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index b169836684..517daca08d 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1196,7 +1196,7 @@ the time, you will want to commit your changes before you can merge, and if you don't, then linkgit:git-stash[1] can take these changes away while you're doing the merge, and reapply them afterwards. -If the changes are independant enough, Git will automatically complete +If the changes are independent enough, Git will automatically complete the merge and commit the result (or reuse an existing commit in case of <>, see below). On the other hand, if there are conflicts--for example, if the same file is -- cgit v1.2.3 From 8d9e7d5293d6a8b50c9e0eb8e23ef5fed45c86d0 Mon Sep 17 00:00:00 2001 From: Jens Lehmann Date: Mon, 1 Feb 2010 19:09:39 +0100 Subject: Updates for dirty submodules in release notes and user manual In the release notes "git status" was not mentioned, also shortly explain the "-dirty" output generated by diff. Added a paragraph to the "Pitfalls with submodules" section in user-manual.txt describing new and old behavior of "git status" and "git diff" for dirty submodules. Signed-off-by: Jens Lehmann Signed-off-by: Junio C Hamano --- Documentation/user-manual.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'Documentation/user-manual.txt') diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 517daca08d..fe6fb722da 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3640,6 +3640,26 @@ Did you forget to 'git add'? Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' ------------------------------------------------- +In older git versions it could be easily forgotten to commit new or modified +files in a submodule, which silently leads to similar problems as not pushing +the submodule changes. Starting with git 1.7.0 both "git status" and "git diff" +in the superproject show submodules as modified when they contain new or +modified files to protect against accidentally committing such a state. "git +diff" will also add a "-dirty" to the work tree side when generating patch +output or used with the --submodule option: + +------------------------------------------------- +$ git diff +diff --git a/sub b/sub +--- a/sub ++++ b/sub +@@ -1 +1 @@ +-Subproject commit 3f356705649b5d566d97ff843cf193359229a453 ++Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty +$ git diff --submodule +Submodule sub 3f35670..3f35670-dirty: +------------------------------------------------- + You also should not rewind branches in a submodule beyond commits that were ever recorded in any superproject. -- cgit v1.2.3