[StGIT PATCH v2] Document patch syntax.

[StGIT PATCH v2] Document patch syntax.

[Yann Dirson]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=utf-8, Size: 1731 bytes --]


Acked-by: Karl Hasselström <kha@treskal.com>

Signed-off-by: Yann Dirson <ydirson@altern.org>
---

 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
 -------
 

Re: [StGIT PATCH v2] Document patch syntax.

[Karl Hasselström]

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

> Acked-by: Karl Hasselstr?m <kha@treskal.com>

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 <kha@treskal.com>

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

Re: [StGIT PATCH v2] Document patch syntax.

[Yann Dirson]

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:
> 
> > Acked-by: Karl Hasselstr?m <kha@treskal.com>
> 
> 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 <kha@treskal.com>
> 
> 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.

Re: [StGIT PATCH v2] Document patch syntax.

[Karl Hasselström]

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