[StGIT PATCH v2] Document patch syntax.

Acked-by: Karl Hasselstr�m <redacted>

Signed-off-by: Yann Dirson <redacted>
---

 Documentation/stg.txt |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/Documentation/stg.txt b/Documentation/stg.txt
index af57c37..bc2a6fe 100644
--- a/Documentation/stg.txt
+++ b/Documentation/stg.txt

@@ -51,6 +51,31 @@ Development branch::
 In such a setup, not all commits on your branch need to be StGIT
 patches; there may be regular GIT commits below your stack base.
 
+Patches
+~~~~~~~
+
+Many StGIT commands take references to StGIT patches as arguments.
+Patches in the stack are identified with a short name, which must be
+unique in the stack.
+
+Patches in the current stack are just refered to by their name.  Some
+commands allow you to specify a patch in another stack of the repository;
+this is done by suffixing the patch name with an '@' sign followed by the
+branch name (eg. 'thispatch@otherbranch').
+
+A number of positions in the stack related to the patch are also
+accessible through '//' suffixes.  For example, 'patch//top' is
+equivalent to 'patch', and 'patch//bottom' refers to the commit below
+'patch' (i.e. the patch below, or the stack base if this is the
+bottom-most patch).  Similarly '//top.old' and '//bottom.old'
+refer to the previous version of the patch (before the last
+stglink:push[] or stglink:refresh[] operation).  When referring to the
+current patch, its name can be omitted (eg. 'currentpatch//bottom.old'
+can be abbreviated as 'bottom.old').
+
+If you need to pass a given StGIT reference to a git command,
+stglink:id[] will convert it to a git commit id.
+
 OPTIONS
 -------
 

On 2007-05-12 20:59:30 +0200, Yann Dirson wrote:

Acked-by: Karl Hasselstr?m <redacted>

Your mail headers say

  Content-Type:   text/plain; charset=utf-8
  Content-Transfer-Encoding: QUOTED-PRINTABLE

but the body contains

  Acked-by: Karl Hasselstr=F6m [off-list ref]

which is QP-encoded latin1, not utf8. (It's an illegal utf8 byte
sequence, which is why it showed up as a question mark in my MUA.)

+Patches in the current stack are just refered to by their name.  Some

s/refered/referred/. I missed this the first time -- sorry.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle

On Sat, May 12, 2007 at 10:43:52PM +0200, Karl Hasselström wrote:

On 2007-05-12 20:59:30 +0200, Yann Dirson wrote:

quoted

Acked-by: Karl Hasselstr?m <redacted>

Your mail headers say

  Content-Type:   text/plain; charset=utf-8
  Content-Transfer-Encoding: QUOTED-PRINTABLE

but the body contains

  Acked-by: Karl Hasselstr=F6m [off-list ref]

which is QP-encoded latin1, not utf8. (It's an illegal utf8 byte
sequence, which is why it showed up as a question mark in my MUA.)

Right, I have seen that in gitk as well.  My LC_CTYPE is "french",
which is an iso8859-1 locale.  I have not touched i18n.commitEncoding,
which should then default to utf-8.  Shouldn't a conversion to utf8
have happenned ?  Things may be made different from standard git,
since this commit was handled by stgit - we may have something to fix
here :)

s/refered/referred/. I missed this the first time -- sorry.

OK

Jeff wrote:

Karl's version is more correct (but your version might be used by many
native speakers). The second half of the sentence is correct because
'must' conjugates the same for singular and plural use; however, it
might be more clear to say "...short name, each of which must be unique
in the stack."

OK as well

Best regards,
-- 
Yann.

On 2007-05-13 15:03:54 +0200, Yann Dirson wrote:

My LC_CTYPE is "french", which is an iso8859-1 locale.

I bit the bullet a year or so ago and switched over to a utf8 locale.
It's becoming increasingly hard to use non-utf8 locales: Gnome wants
utf8, Ubuntu comes with only utf8 locales installed by default, etc. I
figured that it had become less work to convert than to stay with
latin1 (but I still have a few relics, such as the system I'm writing
this mail on).

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle