{"thread":{"id":"6980","subject":"[PATCH] Merge doc/ and Documentation/ directories.","startedAt":"2007-02-26T22:09:30Z","lastAt":"2007-02-26T22:14:32Z","messageCount":2,"participants":["Yann Dirson","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"35549","messageId":"20070226220929.12064.98992.stgit@gandelf.nowhere.earth","threadId":"6980","inReplyTo":null,"subject":"[PATCH] Merge doc/ and Documentation/ directories.","fromName":"Yann Dirson","fromEmail":"ydirson@altern.org","sentAt":"2007-02-26T22:09:30Z","receivedAt":"2007-02-26T22:09:30Z","isPatch":true,"sender":{"key":"ydirson@altern.org","avatar":"https://avatars.githubusercontent.com/u/1190950?v=4"},"body":"\nThis merges everything into Documentation, to match the GIT layout\n(\"make doc\" did not work anyway since \"doc\" was not marked phony).\n\nSigned-off-by: Yann Dirson <ydirson@altern.org>\n---\n\n Documentation/.gitignore    |    5 +\n Documentation/Makefile      |   19 ++\n Documentation/tutorial.conf |    3 \n Documentation/tutorial.txt  |  413 +++++++++++++++++++++++++++++++++++++++++++\n Makefile                    |    6 -\n doc/.gitignore              |    2 \n doc/Makefile                |   17 --\n doc/asciidoc.conf           |    3 \n doc/tutorial.txt            |  413 -------------------------------------------\n 9 files changed, 443 insertions(+), 438 deletions(-)\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nnew file mode 100644\nindex 0000000..6da6dc4\n--- /dev/null\n+++ b/Documentation/.gitignore\n@@ -0,0 +1,5 @@\n+*.html\n+*.pdf\n+*.7\n+*.1\n+doc.dep\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 7f5520c..ea387e7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,6 +3,13 @@ MAN7_TXT=stg.txt\n \n DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))\n \n+ARTICLES = \n+# with their own formatting rules.\n+SP_ARTICLES = tutorial\n+\n+DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))\n+DOC_PDF += $(patsubst %,%.pdf,$(ARTICLES) $(SP_ARTICLES))\n+\n DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))\n DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))\n \n@@ -28,6 +35,7 @@ INSTALL?=install\n all: html man\n \n html: $(DOC_HTML)\n+pdf: $(DOC_PDF)\n \n $(DOC_HTML) $(DOC_MAN1) $(DOC_MAN7): asciidoc.conf\n \n@@ -50,7 +58,7 @@ doc.dep : $(wildcard *.txt) build-docdep.perl\n -include doc.dep\n \n clean:\n-\trm -f *.xml *.html *.1 *.7 doc.dep\n+\trm -f *.xml *.html *.pdf *.1 *.7 doc.dep\n \n %.html : %.txt\n \t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<\n@@ -60,3 +68,12 @@ clean:\n \n %.xml : %.txt\n \t$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<\n+\n+%.pdf: %.xml\n+\txmlto pdf $<\n+\n+# special formatting rules\n+tutorial.html : %.html : %.txt\n+\t$(ASCIIDOC) -b xhtml11 -d article -f tutorial.conf $(ASCIIDOC_EXTRA) $<\n+tutorial.xml : %.xml : %.txt\n+\t$(ASCIIDOC) -b docbook -d article -f tutorial.conf $<\ndiff --git a/Documentation/tutorial.conf b/Documentation/tutorial.conf\nnew file mode 100644\nindex 0000000..5b8d95f\n--- /dev/null\n+++ b/Documentation/tutorial.conf\n@@ -0,0 +1,3 @@\n+[titles]\n+underlines=\"##\",\"==\",\"--\",\"~~\",\"^^\"\n+\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nnew file mode 100644\nindex 0000000..5899c38\n--- /dev/null\n+++ b/Documentation/tutorial.txt\n@@ -0,0 +1,413 @@\n+StGIT Tutorial\n+##############\n+\n+\n+StGIT is a Python application that provides functionality similar to\n+quilt (i.e. pushing/popping patches to/from a stack) using GIT instead\n+of 'diff' and 'patch'. StGIT stores its patches in a GIT repository as\n+normal GIT commit objects.\n+StGIT is not an SCM interface on top of GIT. For standard SCM\n+operations, either use GIT's porcelain commands or the Cogito tool.\n+StGIT is available for download at http://www.procode.org/stgit/ .\n+This tutorial assumes you are already familiar with GIT. For more\n+information on GIT, see the GIT_tutorial or git(7) .\n+\n+\n+Basic Operation\n+===============\n+\n+Help\n+----\n+\n+For a full list of StGIT commands:\n+\n+  stg help\n+\n+For help on individual subcommands:\n+\n+  stg <cmd> (-h | --help)\n+\n+\n+Repository initialisation\n+-------------------------\n+\n+In stand-alone mode, StGIT is used in conjunction with a GIT repository\n+that is already initialised (using 'git-init-db'). StGIT cannot be used\n+outside of a GIT repository.\n+Any branch in a GIT repository may be managed by StGIT. Each branch\n+managed by StGIT contains an independent series of StGIT patches.\n+To initialise an existing GIT branch to be managed by StGIT, cd into the\n+top of your GIT repository, check out the branch you'd like to manage\n+with StGIT, and type:\n+\n+  stg init\n+\n+Run the 'stg init' command for any pre-existing GIT branches intended to\n+be used with StGIT.\n+You can switch between GIT branches with:\n+\n+  stg branch [<branch name>]\n+\n+This checks out the named branch and places you at the topmost applied\n+StGIT patch in that branch.\n+Alternately, you can create branches using only StGIT commands, which\n+will automatically prepare them for use with StGIT:\n+\n+  stg branch --create <new branch>\n+\n+\n+Working with remote repositories\n+--------------------------------\n+\n+With a single command, StGIT can create and initialize a GIT repository\n+which mirrors a remote GIT repository. This is known as cloning. All GIT\n+transports are supported.\n+To clone a repository, use:\n+\n+  stg clone <repository> <local-dir>\n+\n+This creates a fresh local repository, initialises a GIT database in it,\n+pulls the latest version of the remote, and creates and initialises a\n+'master' branch for use with StGIT.\n+At any time you can pull the latest changes from the remote repository.\n+By default, StGIT pulls from the location stored in .git/branches/\n+origin, and updates the base of the current branch.\n+To pull the latest changes from a remote repository, use:\n+\n+  stg pull [<branch> or 'origin']\n+\n+This command removes all applied StGIT patches from the current branch,\n+updates the branch's base commit, then attempts to re-apply the patches.\n+Any merge conflicts will halt this process, allowing you to clean up the\n+conflicts and continue (see below).\n+If the maintainer of the remote repository includes one of your patches\n+in the published repository that you pull from, StGIT can usually\n+recognize that an incoming patch from the remote matches one of yours,\n+and it turns your local version into an empty patch.\n+To automatically delete empty patches after a pull, use:\n+\n+  stg clean\n+\n+As a convention, you should avoid working in the 'master' branch and use\n+it only as a reference, since it reflects someone else's work. If you\n+decide to publish your GIT repository, you'll want your own work\n+separated into its own branch to make it convenient for others to pull\n+just your patches.\n+\n+Getting started: creating a patch\n+---------------------------------\n+\n+Changes to your working directory are saved in a patch. An StGIT patch\n+is simply a saved set of modifications to your working directory, plus a\n+saved description. To create an empty StGIT patch in the current branch:\n+\n+  stg new <name>\n+\n+To save the changes you've made (that is, to refresh a patch), use:\n+\n+  stg refresh\n+\n+To discard changes in your working directory, use:\n+\n+  git checkout -f\n+\n+This restores your working directory to the state it was in the last\n+time the patch was refreshed.\n+Modified files that haven't been saved via a refresh operation can be\n+viewed with:\n+\n+  stg status\n+\n+You can view modified files that have already been saved into a patch:\n+\n+  stg files\n+\n+The 'stg refresh' command automatically notes changes to files that\n+already exist in the working directory, but you have to tell StGIT\n+explicitly if you add, remove, or rename files.\n+To record the addition or deletion of files in your new patch:\n+\n+  stg add [<file>*]\n+  stg rm [<file>*]\n+\n+To record the renaming of a file in your new patch, issue both of these\n+commands:\n+\n+  stg rm <oldfilename>\n+  stg add <newfilename>\n+\n+\n+Stack manipulation: managing multiple patches\n+---------------------------------------------\n+\n+StGIT can manage more than one patch at a time. A series of StGIT\n+patches in a GIT branch are known collectively as a stack. The new patch\n+you created above is now the topmost patch in your stack. You can always\n+see the name of the topmost (current) patch with:\n+\n+  stg top\n+\n+The topmost patch is used as the default patch for most StGIT\n+operations. It is the default target of the 'stg refresh' command, for\n+example.\n+Patches that are pushed onto the stack are referred to as applied, and\n+patches that are popped off the stack are referred to as unapplied.\n+To push/pop a patch to/from a stack:\n+\n+  stg push [--all | <name>]\n+  stg pop [--all]\n+\n+The last patch you pushed is the topmost patch. This patch is always in\n+the applied list; StGIT can't operate on an unapplied patch unless you\n+apply it first.\n+You can display the order of patches in a stack with one of these\n+commands:\n+\n+  stg series\n+  stg applied\n+  stg unapplied\n+\n+By default the 'stg push' command applies the first patch in the\n+unapplied list, but you can push any patch in the unapplied list by\n+giving the name of the patch. This is useful if you want to reorder the\n+patches in a stack.\n+During a push operation, merge conflicts can occur (especially if you\n+are changing the order of the patches in your stack). If the push causes\n+merge conflicts, they need to be fixed and 'stg resolved' run (see\n+below). A 'push' operation can also be reverted with 'stg push --undo'.\n+A few more stack basics; to rename a patch:\n+\n+  stg rename <old-name> <new-name>\n+\n+To delete a patch:\n+\n+  stg delete <name>\n+\n+This permanently discards the named patch. In other words, the patch no\n+longer appears in either the applied or unapplied lists, and cannot be\n+reapplied to the series.\n+You may want to make patches in your stack a permanent part of your GIT\n+repository, for example if you are publishing your repository to others.\n+To do this, use:\n+\n+  stg commit\n+\n+This merges all applied patches in your patch series into the GIT\n+repository and removes them from your stack. Use this command only if\n+you want to permanently store the applied patches and no longer manage\n+them with StGIT.\n+\n+Converting between StGIT patches and text diffs\n+-----------------------------------------------\n+\n+As mentioned in the introduction, StGIT stores modifications to your\n+working tree in the form of GIT commits. This means if you want to apply\n+your changes to a tree not managed by GIT, or send your changes to\n+someone else in e-mail, you need to convert your StGIT patches into\n+normal textual diffs that can be applied with the GNU 'patch' command.\n+The 'stg diff' command is a powerful way to generate and view textual\n+diffs of patches managed by StGIT.\n+To view a diff of the topmost patch:\n+\n+  stg diff -r /\n+\n+Observe that this does not show any changes in the working directory\n+that have not been saved by a 'refresh'. To view just the changes you've\n+made since the last refresh, use:\n+\n+  stg diff -r /top\n+\n+If you want to see the changes made by the patch combined with any\n+unsaved changes in the working directory, try:\n+\n+  stg diff -r /bottom\n+\n+You can also show the changes to any patch in your stack with:\n+\n+  stg diff -r <patch>/\n+\n+Use this command to view all the changes in your stack up through the\n+current patch:\n+\n+  stg diff -r base\n+\n+The 'stg diff' command supports a number of other features that are very\n+useful. Be sure to take a look at the help information for this command.\n+To convert your StGIT patches into patch files:\n+\n+  stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]\n+\n+The 'export' command supports options to automatically number the\n+patches (-n) or add the '.diff' extension (-d). If you don't tell \"stg\n+export\" where to put the patches, it will create directory named \"patch-\n+branchname\" in your current directory, and store the patches there.\n+To e-mail a patch or range of patches:\n+\n+  stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)\n+\n+\"stg mail\" has a lot of options, so read the output of \"stg mail -h\" for\n+more information.\n+You can also import an existing GNU diff patch file as a new StGIT patch\n+with a single command. \"stg import\" will automatically parse through the\n+patch file and extract a patch description. Use:\n+\n+  stg import [<file>]\n+\n+This is the equivalent of \"stg new\" followed by \"patch -i <file>\", then\n+\"stg refresh -e\".\n+Sometimes the patch file won't apply cleanly. In that case, \"stg import\"\n+will leave you with an empty StGIT patch, to which you then apply the\n+patch file by hand using \"patch -i\" and your favorite editor.\n+To merge a GNU diff file (defaulting to the standard input) into the\n+topmost patch:\n+\n+  stg fold [<file>]\n+\n+This command supports a '--threeway' option which applies the patch onto\n+the bottom of the topmost one and performs a three-way merge.\n+\n+\n+Advanced Usage\n+==============\n+\n+Handling merge conflicts\n+------------------------\n+\n+Pushing a patch on the stack can fail if the patch cannot be applied\n+cleanly. This usually happens if there are overlapping changes in the\n+tree, the patch depends on another patch which is not applied, or if a\n+patch was not merged upstream in the exact form it was sent.\n+The 'push' operation stops after the first patch with conflicts. The\n+'status' command shows the conflict files by marking them with a 'C'. If\n+the 'keeporig' options is set to 'yes' (the default), the original files\n+involved in the merge operations are left in the tree as <file>.older,\n+<file>.local and <file>.remote for better analysis of the conflict. If\n+'diff3' is used as the merger (the default), markers are added to the\n+conflicted files as well.\n+Run the 'resolved' command to mark the conflicts resolved and remove the\n+temporary merge files from the working tree. Then run the 'refresh'\n+command to update the StGIT patch with the modifications you made to\n+resolve the conflict.\n+\n+\n+Configuration file\n+------------------\n+\n+StGIT tries to read the configuration options from the following files:\n+/etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the\n+options in the former files. If no file is found, the defaults are used.\n+An example configuration file with options description can be found in\n+the examples/ directory. Most users would probably only define the\n+'smtpserver' option used by the 'mail' command.\n+The gitmergeonefile.py script does the three-way merging on individual\n+files using the tool specified by the 'merger' option. The user can\n+specify a smarter tool to be used.\n+\n+\n+Templates\n+---------\n+\n+The 'export' and 'mail' commands use templates for generating the patch\n+files or e-mails. The default templates are installed under <prefix>/\n+share/stgit/templates/ and, combined with the extra options available\n+for the commands, should be enough for most users. The template format\n+uses the standard Python string formatting rules. The variables\n+available are shown in the the help message for the commands.\n+The 'mail' command can also send an initial e-mail for which there is no\n+default template. The <prefix>/share/stgit/examples/firstmail.tmpl file\n+can be used as an example.\n+A default description for new patches can be defined in the .git/\n+patchdescr.tmpl file. This is useful for things like signed-off-by\n+lines.\n+\n+\n+Merging two patches into one\n+----------------------------\n+\n+There is no command to do this directly at the moment but one can export\n+the patch to be merged and use the 'stg fold' command on the generated\n+diff file. Assuming that the merged patch was not already applied, the\n+operation will succeed. Pushing the merged patch onto the stack will\n+result in an empty patch (StGIT notifying the user) that can be safely\n+deleted.\n+\n+\n+Technical Information\n+=====================\n+\n+A bit of StGIT patch theory\n+---------------------------\n+\n+We assume that a patch is a diff between two nodes - bottom and top. A\n+node is a commit SHA1 id or tree SHA1 id in the GIT terminology:\n+\n+  P - patch\n+  N - node\n+\n+  P = diff(Nt, Nb)\n+\n+  \tNb - bottom (start) node\n+  \tNt - top (end) node\n+  \tNf - first node (for log generation)\n+\n+For an ordered stack of patches:\n+\n+  P1 = diff(N1, N0)\n+  P2 = diff(N2, N1)\n+  ...\n+\n+\n+  Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)\n+\n+  \tPs  - the big patch of the whole stack\n+  \tNsb - bottom stack node (= N0)\n+  \tNst - top stack node (= Nn)\n+\n+Applying (pushing) a patch on the stack (Nst can differ from Nb) is done\n+by diff3 merging. The new patch becomes:\n+\n+  P' = diff(Nt', Nb')\n+  Nb' = Nst\n+  Nt' = diff3(Nst, Nb, Nt)\n+\n+(note that the diff3 parameters order is: branch1, ancestor, branch2)\n+The above operation allows easy patch re-ordering.\n+Removing (popping) a patch from the stack is done by simply setting the\n+Nst to Nb.\n+\n+\n+Layout of the .git directory\n+----------------------------\n+\n+  HEAD\t\t\t-> refs/heads/<something>\n+  objects/\n+    ??/\n+    ...\n+  refs/\n+    heads/\n+      master\t\t- the master commit id\n+      ...\n+    bases/\n+      master\t\t- the bottom id of the stack (to get a big diff)\n+      ...\n+    tags/\n+      ...\n+    branches/\n+      ...\n+    patches/\n+      master/\n+        applied\t\t- list of applied patches\n+        unapplied\t\t- list of not-yet applied patches\n+        current\t\t- name of the topmost patch\n+        patch1/\n+          bottom\t\t- the bottom id of the patch\n+          top\t\t- the top id of the patch\n+  \tdescription\t- the patch description\n+  \tauthname\t- author's name\n+  \tauthemail\t- author's e-mail\n+  \tcommname\t- committer's name\n+  \tcommemail\t- committer's e-mail\n+        patch2/\n+          ...\n+        ...\n+      ...\ndiff --git a/Makefile b/Makefile\nindex df77d97..8cd5813 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -9,15 +9,17 @@ install:\n \t$(PYTHON) setup.py install --prefix=$(PREFIX) --root=$(DESTDIR)\n \n doc:\n-\tcd doc && $(MAKE) all\n+\tcd Documentation && $(MAKE) all\n \n test:\n \tcd t && $(MAKE) all\n \n clean:\n-\tfor dir in doc t; do \\\n+\tfor dir in Documentation t; do \\\n \t\t(cd $$dir && $(MAKE) clean); \\\n \tdone\n \trm -rf build\n \trm -f stgit/*.pyc\n \trm -f stgit/commands/*.pyc\n+\n+.PHONY: all install doc test clean\ndiff --git a/doc/.gitignore b/doc/.gitignore\ndeleted file mode 100644\nindex 15ba6af..0000000\n--- a/doc/.gitignore\n+++ /dev/null\n@@ -1,2 +0,0 @@\n-tutorial.html\n-tutorial.pdf\ndiff --git a/doc/Makefile b/doc/Makefile\ndeleted file mode 100644\nindex 07704b8..0000000\n--- a/doc/Makefile\n+++ /dev/null\n@@ -1,17 +0,0 @@\n-DOCS = tutorial.txt\n-DOCS_HTML = $(DOCS:.txt=.html)\n-DOCS_PDF = $(DOCS:.txt=.pdf)\n-\n-all: $(DOCS_HTML) $(DOCS_PDF)\n-\n-%.html: %.txt\n-\tasciidoc $<\n-\n-%.xml: %.txt\n-\tasciidoc --backend=docbook $<\n-\n-%.pdf: %.xml\n-\txmlto pdf $<\n-\n-clean:\n-\trm -f *.xml *.html *.pdf\ndiff --git a/doc/asciidoc.conf b/doc/asciidoc.conf\ndeleted file mode 100644\nindex 5b8d95f..0000000\n--- a/doc/asciidoc.conf\n+++ /dev/null\n@@ -1,3 +0,0 @@\n-[titles]\n-underlines=\"##\",\"==\",\"--\",\"~~\",\"^^\"\n-\ndiff --git a/doc/tutorial.txt b/doc/tutorial.txt\ndeleted file mode 100644\nindex 5899c38..0000000\n--- a/doc/tutorial.txt\n+++ /dev/null\n@@ -1,413 +0,0 @@\n-StGIT Tutorial\n-##############\n-\n-\n-StGIT is a Python application that provides functionality similar to\n-quilt (i.e. pushing/popping patches to/from a stack) using GIT instead\n-of 'diff' and 'patch'. StGIT stores its patches in a GIT repository as\n-normal GIT commit objects.\n-StGIT is not an SCM interface on top of GIT. For standard SCM\n-operations, either use GIT's porcelain commands or the Cogito tool.\n-StGIT is available for download at http://www.procode.org/stgit/ .\n-This tutorial assumes you are already familiar with GIT. For more\n-information on GIT, see the GIT_tutorial or git(7) .\n-\n-\n-Basic Operation\n-===============\n-\n-Help\n-----\n-\n-For a full list of StGIT commands:\n-\n-  stg help\n-\n-For help on individual subcommands:\n-\n-  stg <cmd> (-h | --help)\n-\n-\n-Repository initialisation\n--------------------------\n-\n-In stand-alone mode, StGIT is used in conjunction with a GIT repository\n-that is already initialised (using 'git-init-db'). StGIT cannot be used\n-outside of a GIT repository.\n-Any branch in a GIT repository may be managed by StGIT. Each branch\n-managed by StGIT contains an independent series of StGIT patches.\n-To initialise an existing GIT branch to be managed by StGIT, cd into the\n-top of your GIT repository, check out the branch you'd like to manage\n-with StGIT, and type:\n-\n-  stg init\n-\n-Run the 'stg init' command for any pre-existing GIT branches intended to\n-be used with StGIT.\n-You can switch between GIT branches with:\n-\n-  stg branch [<branch name>]\n-\n-This checks out the named branch and places you at the topmost applied\n-StGIT patch in that branch.\n-Alternately, you can create branches using only StGIT commands, which\n-will automatically prepare them for use with StGIT:\n-\n-  stg branch --create <new branch>\n-\n-\n-Working with remote repositories\n---------------------------------\n-\n-With a single command, StGIT can create and initialize a GIT repository\n-which mirrors a remote GIT repository. This is known as cloning. All GIT\n-transports are supported.\n-To clone a repository, use:\n-\n-  stg clone <repository> <local-dir>\n-\n-This creates a fresh local repository, initialises a GIT database in it,\n-pulls the latest version of the remote, and creates and initialises a\n-'master' branch for use with StGIT.\n-At any time you can pull the latest changes from the remote repository.\n-By default, StGIT pulls from the location stored in .git/branches/\n-origin, and updates the base of the current branch.\n-To pull the latest changes from a remote repository, use:\n-\n-  stg pull [<branch> or 'origin']\n-\n-This command removes all applied StGIT patches from the current branch,\n-updates the branch's base commit, then attempts to re-apply the patches.\n-Any merge conflicts will halt this process, allowing you to clean up the\n-conflicts and continue (see below).\n-If the maintainer of the remote repository includes one of your patches\n-in the published repository that you pull from, StGIT can usually\n-recognize that an incoming patch from the remote matches one of yours,\n-and it turns your local version into an empty patch.\n-To automatically delete empty patches after a pull, use:\n-\n-  stg clean\n-\n-As a convention, you should avoid working in the 'master' branch and use\n-it only as a reference, since it reflects someone else's work. If you\n-decide to publish your GIT repository, you'll want your own work\n-separated into its own branch to make it convenient for others to pull\n-just your patches.\n-\n-Getting started: creating a patch\n----------------------------------\n-\n-Changes to your working directory are saved in a patch. An StGIT patch\n-is simply a saved set of modifications to your working directory, plus a\n-saved description. To create an empty StGIT patch in the current branch:\n-\n-  stg new <name>\n-\n-To save the changes you've made (that is, to refresh a patch), use:\n-\n-  stg refresh\n-\n-To discard changes in your working directory, use:\n-\n-  git checkout -f\n-\n-This restores your working directory to the state it was in the last\n-time the patch was refreshed.\n-Modified files that haven't been saved via a refresh operation can be\n-viewed with:\n-\n-  stg status\n-\n-You can view modified files that have already been saved into a patch:\n-\n-  stg files\n-\n-The 'stg refresh' command automatically notes changes to files that\n-already exist in the working directory, but you have to tell StGIT\n-explicitly if you add, remove, or rename files.\n-To record the addition or deletion of files in your new patch:\n-\n-  stg add [<file>*]\n-  stg rm [<file>*]\n-\n-To record the renaming of a file in your new patch, issue both of these\n-commands:\n-\n-  stg rm <oldfilename>\n-  stg add <newfilename>\n-\n-\n-Stack manipulation: managing multiple patches\n----------------------------------------------\n-\n-StGIT can manage more than one patch at a time. A series of StGIT\n-patches in a GIT branch are known collectively as a stack. The new patch\n-you created above is now the topmost patch in your stack. You can always\n-see the name of the topmost (current) patch with:\n-\n-  stg top\n-\n-The topmost patch is used as the default patch for most StGIT\n-operations. It is the default target of the 'stg refresh' command, for\n-example.\n-Patches that are pushed onto the stack are referred to as applied, and\n-patches that are popped off the stack are referred to as unapplied.\n-To push/pop a patch to/from a stack:\n-\n-  stg push [--all | <name>]\n-  stg pop [--all]\n-\n-The last patch you pushed is the topmost patch. This patch is always in\n-the applied list; StGIT can't operate on an unapplied patch unless you\n-apply it first.\n-You can display the order of patches in a stack with one of these\n-commands:\n-\n-  stg series\n-  stg applied\n-  stg unapplied\n-\n-By default the 'stg push' command applies the first patch in the\n-unapplied list, but you can push any patch in the unapplied list by\n-giving the name of the patch. This is useful if you want to reorder the\n-patches in a stack.\n-During a push operation, merge conflicts can occur (especially if you\n-are changing the order of the patches in your stack). If the push causes\n-merge conflicts, they need to be fixed and 'stg resolved' run (see\n-below). A 'push' operation can also be reverted with 'stg push --undo'.\n-A few more stack basics; to rename a patch:\n-\n-  stg rename <old-name> <new-name>\n-\n-To delete a patch:\n-\n-  stg delete <name>\n-\n-This permanently discards the named patch. In other words, the patch no\n-longer appears in either the applied or unapplied lists, and cannot be\n-reapplied to the series.\n-You may want to make patches in your stack a permanent part of your GIT\n-repository, for example if you are publishing your repository to others.\n-To do this, use:\n-\n-  stg commit\n-\n-This merges all applied patches in your patch series into the GIT\n-repository and removes them from your stack. Use this command only if\n-you want to permanently store the applied patches and no longer manage\n-them with StGIT.\n-\n-Converting between StGIT patches and text diffs\n------------------------------------------------\n-\n-As mentioned in the introduction, StGIT stores modifications to your\n-working tree in the form of GIT commits. This means if you want to apply\n-your changes to a tree not managed by GIT, or send your changes to\n-someone else in e-mail, you need to convert your StGIT patches into\n-normal textual diffs that can be applied with the GNU 'patch' command.\n-The 'stg diff' command is a powerful way to generate and view textual\n-diffs of patches managed by StGIT.\n-To view a diff of the topmost patch:\n-\n-  stg diff -r /\n-\n-Observe that this does not show any changes in the working directory\n-that have not been saved by a 'refresh'. To view just the changes you've\n-made since the last refresh, use:\n-\n-  stg diff -r /top\n-\n-If you want to see the changes made by the patch combined with any\n-unsaved changes in the working directory, try:\n-\n-  stg diff -r /bottom\n-\n-You can also show the changes to any patch in your stack with:\n-\n-  stg diff -r <patch>/\n-\n-Use this command to view all the changes in your stack up through the\n-current patch:\n-\n-  stg diff -r base\n-\n-The 'stg diff' command supports a number of other features that are very\n-useful. Be sure to take a look at the help information for this command.\n-To convert your StGIT patches into patch files:\n-\n-  stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]\n-\n-The 'export' command supports options to automatically number the\n-patches (-n) or add the '.diff' extension (-d). If you don't tell \"stg\n-export\" where to put the patches, it will create directory named \"patch-\n-branchname\" in your current directory, and store the patches there.\n-To e-mail a patch or range of patches:\n-\n-  stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)\n-\n-\"stg mail\" has a lot of options, so read the output of \"stg mail -h\" for\n-more information.\n-You can also import an existing GNU diff patch file as a new StGIT patch\n-with a single command. \"stg import\" will automatically parse through the\n-patch file and extract a patch description. Use:\n-\n-  stg import [<file>]\n-\n-This is the equivalent of \"stg new\" followed by \"patch -i <file>\", then\n-\"stg refresh -e\".\n-Sometimes the patch file won't apply cleanly. In that case, \"stg import\"\n-will leave you with an empty StGIT patch, to which you then apply the\n-patch file by hand using \"patch -i\" and your favorite editor.\n-To merge a GNU diff file (defaulting to the standard input) into the\n-topmost patch:\n-\n-  stg fold [<file>]\n-\n-This command supports a '--threeway' option which applies the patch onto\n-the bottom of the topmost one and performs a three-way merge.\n-\n-\n-Advanced Usage\n-==============\n-\n-Handling merge conflicts\n-------------------------\n-\n-Pushing a patch on the stack can fail if the patch cannot be applied\n-cleanly. This usually happens if there are overlapping changes in the\n-tree, the patch depends on another patch which is not applied, or if a\n-patch was not merged upstream in the exact form it was sent.\n-The 'push' operation stops after the first patch with conflicts. The\n-'status' command shows the conflict files by marking them with a 'C'. If\n-the 'keeporig' options is set to 'yes' (the default), the original files\n-involved in the merge operations are left in the tree as <file>.older,\n-<file>.local and <file>.remote for better analysis of the conflict. If\n-'diff3' is used as the merger (the default), markers are added to the\n-conflicted files as well.\n-Run the 'resolved' command to mark the conflicts resolved and remove the\n-temporary merge files from the working tree. Then run the 'refresh'\n-command to update the StGIT patch with the modifications you made to\n-resolve the conflict.\n-\n-\n-Configuration file\n-------------------\n-\n-StGIT tries to read the configuration options from the following files:\n-/etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the\n-options in the former files. If no file is found, the defaults are used.\n-An example configuration file with options description can be found in\n-the examples/ directory. Most users would probably only define the\n-'smtpserver' option used by the 'mail' command.\n-The gitmergeonefile.py script does the three-way merging on individual\n-files using the tool specified by the 'merger' option. The user can\n-specify a smarter tool to be used.\n-\n-\n-Templates\n----------\n-\n-The 'export' and 'mail' commands use templates for generating the patch\n-files or e-mails. The default templates are installed under <prefix>/\n-share/stgit/templates/ and, combined with the extra options available\n-for the commands, should be enough for most users. The template format\n-uses the standard Python string formatting rules. The variables\n-available are shown in the the help message for the commands.\n-The 'mail' command can also send an initial e-mail for which there is no\n-default template. The <prefix>/share/stgit/examples/firstmail.tmpl file\n-can be used as an example.\n-A default description for new patches can be defined in the .git/\n-patchdescr.tmpl file. This is useful for things like signed-off-by\n-lines.\n-\n-\n-Merging two patches into one\n-----------------------------\n-\n-There is no command to do this directly at the moment but one can export\n-the patch to be merged and use the 'stg fold' command on the generated\n-diff file. Assuming that the merged patch was not already applied, the\n-operation will succeed. Pushing the merged patch onto the stack will\n-result in an empty patch (StGIT notifying the user) that can be safely\n-deleted.\n-\n-\n-Technical Information\n-=====================\n-\n-A bit of StGIT patch theory\n----------------------------\n-\n-We assume that a patch is a diff between two nodes - bottom and top. A\n-node is a commit SHA1 id or tree SHA1 id in the GIT terminology:\n-\n-  P - patch\n-  N - node\n-\n-  P = diff(Nt, Nb)\n-\n-  \tNb - bottom (start) node\n-  \tNt - top (end) node\n-  \tNf - first node (for log generation)\n-\n-For an ordered stack of patches:\n-\n-  P1 = diff(N1, N0)\n-  P2 = diff(N2, N1)\n-  ...\n-\n-\n-  Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)\n-\n-  \tPs  - the big patch of the whole stack\n-  \tNsb - bottom stack node (= N0)\n-  \tNst - top stack node (= Nn)\n-\n-Applying (pushing) a patch on the stack (Nst can differ from Nb) is done\n-by diff3 merging. The new patch becomes:\n-\n-  P' = diff(Nt', Nb')\n-  Nb' = Nst\n-  Nt' = diff3(Nst, Nb, Nt)\n-\n-(note that the diff3 parameters order is: branch1, ancestor, branch2)\n-The above operation allows easy patch re-ordering.\n-Removing (popping) a patch from the stack is done by simply setting the\n-Nst to Nb.\n-\n-\n-Layout of the .git directory\n-----------------------------\n-\n-  HEAD\t\t\t-> refs/heads/<something>\n-  objects/\n-    ??/\n-    ...\n-  refs/\n-    heads/\n-      master\t\t- the master commit id\n-      ...\n-    bases/\n-      master\t\t- the bottom id of the stack (to get a big diff)\n-      ...\n-    tags/\n-      ...\n-    branches/\n-      ...\n-    patches/\n-      master/\n-        applied\t\t- list of applied patches\n-        unapplied\t\t- list of not-yet applied patches\n-        current\t\t- name of the topmost patch\n-        patch1/\n-          bottom\t\t- the bottom id of the patch\n-          top\t\t- the top id of the patch\n-  \tdescription\t- the patch description\n-  \tauthname\t- author's name\n-  \tauthemail\t- author's e-mail\n-  \tcommname\t- committer's name\n-  \tcommemail\t- committer's e-mail\n-        patch2/\n-          ...\n-        ...\n-      ...\n"},{"id":"35551","messageId":"Pine.LNX.4.63.0702262312100.22628@wbgn013.biozentrum.uni-wuerzburg.de","threadId":"6980","inReplyTo":"20070226220929.12064.98992.stgit@gandelf.nowhere.earth","subject":"Re: [PATCH] Merge doc/ and Documentation/ directories.","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-02-26T22:14:32Z","receivedAt":"2007-02-26T22:14:32Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 26 Feb 2007, Yann Dirson wrote:\n\n>  Documentation/tutorial.txt  |  413 +++++++++++++++++++++++++++++++++++++++++++\n>  doc/tutorial.txt            |  413 -------------------------------------------\n>\n> [...]\n> \n> diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\n> new file mode 100644\n> index 0000000..5899c38\n\nAFAICT the diff option \"--no-renames\" can override \"-M\", so why turn \"-M\" \non by default for format-patch and show?\n\nCiao,\nDscho\n"}]}