[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, master, updated. gawk-4.1.0-2461-g6de370
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, master, updated. gawk-4.1.0-2461-g6de370d |
|
Date: |
Fri, 7 Apr 2017 02:08:53 -0400 (EDT) |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, master has been updated
via 6de370d832e5145ed6a4cb05099f51192773a4b1 (commit)
from 4271b995d64430e794e344f0c4985162eb991052 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=6de370d832e5145ed6a4cb05099f51192773a4b1
commit 6de370d832e5145ed6a4cb05099f51192773a4b1
Author: Arnold D. Robbins <address@hidden>
Date: Fri Apr 7 09:08:22 2017 +0300
Remove using-git.texi. Add gawkworkflow.texi.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 142f035..dd3e1c9 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2017-04-07 Arnold D. Robbins <address@hidden>
+
+ * using-git.texi: Removed.
+ * gawkworkflow.texi: Added. New file.
+ * wordlist2: New file.
+ * Makefile.am: Revised for new document. Copyright years updated.
+
2017-03-17 Arnold D. Robbins <address@hidden>
* gawktexi.in: Improve the discussion of quoting on
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 002fafa..76ba824 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,7 @@
#
# doc/Makefile.am --- automake input file for gawk
#
-# Copyright (C) 2000, 2001, 2002, 2004, 2005, 2007, 2010, 2011
+# Copyright (C) 2000, 2001, 2002, 2004, 2005, 2007, 2010, 2011, 2016, 2017
# the Free Software Foundation, Inc.
#
# This file is part of GAWK, the GNU implementation of the
@@ -24,7 +24,7 @@
## process this file with automake to produce Makefile.in
-info_TEXINFOS = gawk.texi gawkinet.texi using-git.texi
+info_TEXINFOS = gawk.texi gawkinet.texi gawkworkflow.texi
man_MANS = gawk.1
@@ -51,7 +51,7 @@ EXTRA_DIST = ChangeLog ChangeLog.0 README.card ad.block
setter.outline \
bc_notes
# Get rid of generated files when cleaning
-CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf
using-git.pdf awkcard.pdf gawk.1.pdf
+CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf
gawkworkflow.pdf awkcard.pdf gawk.1.pdf
MAKEINFO = @MAKEINFO@ --no-split --force
@@ -77,7 +77,7 @@ AWKCARD = awkcard.ps
gawk.texi: $(srcdir)/gawktexi.in $(srcdir)/sidebar.awk
awk -f $(srcdir)/sidebar.awk < $(srcdir)/gawktexi.in > gawk.texi
-postscript: gawk.ps gawkinet.ps using-git.ps gawk.1.ps $(AWKCARD)
+postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps $(AWKCARD)
pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf
@@ -87,8 +87,8 @@ gawk.ps: gawk.dvi
gawkinet.ps: gawkinet.dvi
TEXINPUTS=$(srcdir): dvips -o gawkinet.ps gawkinet.dvi
-using-git.ps: using-git.dvi
- TEXINPUTS=$(srcdir): dvips -o using-git.ps using-git.dvi
+gawkworkflow.ps: gawkworkflow.dvi
+ TEXINPUTS=$(srcdir): dvips -o gawkworkflow.ps gawkworkflow.dvi
gawk.1.ps: gawk.1
-groff -man $(srcdir)/gawk.1 > gawk.1.ps
@@ -108,6 +108,14 @@ awkcard.nc: $(CARDFILES)
awkcard.pdf: awkcard.ps
ps2pdf awkcard.ps awkcard.pdf
-spell:
+spell: spellmanual spell workflow
+
+spellmanual:
+ @echo ==== gawktexi.in ====;
export LC_ALL=C ; spell "$(srcdir)"/gawktexi.in | \
sort -u | comm -23 - "$(srcdir)"/wordlist
+
+spellworkflow:
+ @echo ==== gawkworkflow.texi ====
+ export LC_ALL=C ; spell "$(srcdir)"/gawkworkflow.texi | \
+ sort -u | comm -23 - "$(srcdir)"/wordlist2
diff --git a/doc/Makefile.in b/doc/Makefile.in
index b3523a2..fd4f47a 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -17,7 +17,7 @@
#
# doc/Makefile.am --- automake input file for gawk
#
-# Copyright (C) 2000, 2001, 2002, 2004, 2005, 2007, 2010, 2011
+# Copyright (C) 2000, 2001, 2002, 2004, 2005, 2007, 2010, 2011, 2016, 2017
# the Free Software Foundation, Inc.
#
# This file is part of GAWK, the GNU implementation of the
@@ -174,13 +174,13 @@ am__v_texidevnull_ = $(address@hidden@)
am__v_texidevnull_0 = > /dev/null
am__v_texidevnull_1 =
INFO_DEPS = $(srcdir)/gawk.info $(srcdir)/gawkinet.info \
- $(srcdir)/using-git.info
+ $(srcdir)/gawkworkflow.info
am__TEXINFO_TEX_DIR = $(srcdir)
-DVIS = gawk.dvi gawkinet.dvi using-git.dvi
-PDFS = gawk.pdf gawkinet.pdf using-git.pdf
-PSS = gawk.ps gawkinet.ps using-git.ps
-HTMLS = gawk.html gawkinet.html using-git.html
-TEXINFOS = gawk.texi gawkinet.texi using-git.texi
+DVIS = gawk.dvi gawkinet.dvi gawkworkflow.dvi
+PDFS = gawk.pdf gawkinet.pdf gawkworkflow.pdf
+PSS = gawk.ps gawkinet.ps gawkworkflow.ps
+HTMLS = gawk.html gawkinet.html gawkworkflow.html
+TEXINFOS = gawk.texi gawkinet.texi gawkworkflow.texi
TEXI2DVI = texi2dvi
TEXI2PDF = $(TEXI2DVI) --pdf --batch
MAKEINFOHTML = $(MAKEINFO) --html
@@ -354,7 +354,7 @@ target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
-info_TEXINFOS = gawk.texi gawkinet.texi using-git.texi
+info_TEXINFOS = gawk.texi gawkinet.texi gawkworkflow.texi
man_MANS = gawk.1
EXTRA_DIST = ChangeLog ChangeLog.0 README.card ad.block setter.outline \
awkcard.in awkforai.txt texinfo.tex cardfonts \
@@ -380,7 +380,7 @@ EXTRA_DIST = ChangeLog ChangeLog.0 README.card ad.block
setter.outline \
# Get rid of generated files when cleaning
-CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf
using-git.pdf awkcard.pdf gawk.1.pdf
+CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf
gawkworkflow.pdf awkcard.pdf gawk.1.pdf
TROFF = groff -t -Tps -U
SEDME = sed -e "s/^level0 restore/level0 restore flashme 100 72 moveto
(Copyright `date '+%m-%d-%y %T'`, FSF, Inc. (all)) show/" \
-e "s/^\/level0 save def/\/level0 save def 30 -48 translate/"
@@ -478,10 +478,10 @@ $(srcdir)/gawkinet.info: gawkinet.texi
gawkinet.dvi: gawkinet.texi
gawkinet.pdf: gawkinet.texi
gawkinet.html: gawkinet.texi
-$(srcdir)/using-git.info: using-git.texi
-using-git.dvi: using-git.texi
-using-git.pdf: using-git.texi
-using-git.html: using-git.texi
+$(srcdir)/gawkworkflow.info: gawkworkflow.texi
+gawkworkflow.dvi: gawkworkflow.texi
+gawkworkflow.pdf: gawkworkflow.texi
+gawkworkflow.html: gawkworkflow.texi
.dvi.ps:
$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
$(DVIPS) $(AM_V_texinfo) -o $@ $<
@@ -563,16 +563,16 @@ dist-info: $(INFO_DEPS)
done
mostlyclean-aminfo:
- -rm -rf gawk.t2d gawk.t2p gawkinet.t2d gawkinet.t2p using-git.t2d \
- using-git.t2p
+ -rm -rf gawk.t2d gawk.t2p gawkinet.t2d gawkinet.t2p gawkworkflow.t2d \
+ gawkworkflow.t2p
clean-aminfo:
-test -z "gawk.dvi gawk.pdf gawk.ps gawk.html gawkinet.dvi gawkinet.pdf
\
- gawkinet.ps gawkinet.html using-git.dvi using-git.pdf \
- using-git.ps using-git.html" \
+ gawkinet.ps gawkinet.html gawkworkflow.dvi gawkworkflow.pdf \
+ gawkworkflow.ps gawkworkflow.html" \
|| rm -rf gawk.dvi gawk.pdf gawk.ps gawk.html gawkinet.dvi gawkinet.pdf
\
- gawkinet.ps gawkinet.html using-git.dvi using-git.pdf \
- using-git.ps using-git.html
+ gawkinet.ps gawkinet.html gawkworkflow.dvi gawkworkflow.pdf \
+ gawkworkflow.ps gawkworkflow.html
maintainer-clean-aminfo:
@list='$(INFO_DEPS)'; for i in $$list; do \
@@ -891,7 +891,7 @@ uninstall-man: uninstall-man1
gawk.texi: $(srcdir)/gawktexi.in $(srcdir)/sidebar.awk
awk -f $(srcdir)/sidebar.awk < $(srcdir)/gawktexi.in > gawk.texi
-postscript: gawk.ps gawkinet.ps using-git.ps gawk.1.ps $(AWKCARD)
+postscript: gawk.ps gawkinet.ps gawkworkflow.ps gawk.1.ps $(AWKCARD)
pdf-local: postscript gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf
@@ -901,8 +901,8 @@ gawk.ps: gawk.dvi
gawkinet.ps: gawkinet.dvi
TEXINPUTS=$(srcdir): dvips -o gawkinet.ps gawkinet.dvi
-using-git.ps: using-git.dvi
- TEXINPUTS=$(srcdir): dvips -o using-git.ps using-git.dvi
+gawkworkflow.ps: gawkworkflow.dvi
+ TEXINPUTS=$(srcdir): dvips -o gawkworkflow.ps gawkworkflow.dvi
gawk.1.ps: gawk.1
-groff -man $(srcdir)/gawk.1 > gawk.1.ps
@@ -922,10 +922,18 @@ awkcard.nc: $(CARDFILES)
awkcard.pdf: awkcard.ps
ps2pdf awkcard.ps awkcard.pdf
-spell:
+spell: spellmanual spell workflow
+
+spellmanual:
+ @echo ==== gawktexi.in ====;
export LC_ALL=C ; spell "$(srcdir)"/gawktexi.in | \
sort -u | comm -23 - "$(srcdir)"/wordlist
+spellworkflow:
+ @echo ==== gawkworkflow.texi ====
+ export LC_ALL=C ; spell "$(srcdir)"/gawkworkflow.texi | \
+ sort -u | comm -23 - "$(srcdir)"/wordlist2
+
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
diff --git a/doc/gawkworkflow.info b/doc/gawkworkflow.info
new file mode 100644
index 0000000..64e13a1
--- /dev/null
+++ b/doc/gawkworkflow.info
@@ -0,0 +1,1980 @@
+This is gawkworkflow.info, produced by makeinfo version 6.1 from
+gawkworkflow.texi.
+
+Copyright (C) 2017 Free Software Foundation, Inc.
+
+
+ This is Edition 0.7 of 'Participating in 'gawk' Development'.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", with the
+Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as
+in (a) below. A copy of the license is included in the section entitled
+"GNU Free Documentation License".
+
+ a. The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+INFO-DIR-SECTION Text creation and manipulation
+START-INFO-DIR-ENTRY
+* Gawk Work Flow: (gawkworkflow). Participating in 'gawk'
development.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* Gawk Work Flow: (gawkworkflow)Overview. Participating in 'gawk'
development.
+END-INFO-DIR-ENTRY
+
+
+File: gawkworkflow.info, Node: Top, Next: Preface, Up: (dir)
+
+General Introduction
+********************
+
+This file describes how to participate in software development for GNU
+Awk ('gawk') (http://www.gnu.org/software/gawk).
+
+ Copyright (C) 2017 Free Software Foundation, Inc.
+
+
+ This is Edition 0.7 of 'Participating in 'gawk' Development'.
+
+ Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "GNU General Public License", with the
+Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as
+in (a) below. A copy of the license is included in the section entitled
+"GNU Free Documentation License".
+
+ a. The FSF's Back-Cover Text is: "You have the freedom to copy and
+ modify this GNU manual."
+
+* Menu:
+
+* Preface:: Some introductory remarks.
+* Contributing:: How to contribute to 'gawk'
+ development.
+* Using Git:: Getting started with Git.
+* Configuring git:: Configuring Git.
+* Development without commit access:: How to wwork without commit access.
+* Development with commit access:: How to work with commit access.
+* General practices:: How things should usually be done.
+* Repo Maintenance:: Tips for keeping your repo clean.
+* Development Stuff:: Things you need to know to be a
+ 'gawk' developer.
+* Cheat Sheet:: Git command summary.
+* Resources:: Some further resources.
+* TODO:: Stuff still to do.
+* Index:: The index.
+
+* This Manual:: How to use this manual.
+* Conventions:: Typographical Conventions.
+* Acknowledgments:: Acknowledgments.
+* Reviewers:: A note to reviewers.
+* Push Pull:: The push/pull software development model.
+* Repo Copies:: What it means to have a copy of a repo.
+* Local Branches:: How to best use local branches.
+* Branches are state:: Branches represent development state.
+* Repo State:: The different branch types in the repo.
+* Local State:: Managing local branches.
+* Remotes:: What a "remote" is.
+* Cloning:: Cloning the repo the first time.
+* Switching Branches:: Moving from one branch to another.
+* Starting A New Branch:: Starting a new branch for development.
+* Undoing a change:: Throwing away changes.
+* Updating:: Keeping in sync with the upstream repo.
+* Rebasing:: Rebasing A Local Branch.
+* Merge Conflicts:: Dealing With Merge Conflicts.
+* Submitting Changes:: How to submit your changes.
+* Removing Branches:: Getting rid of unneeded branches.
+* Points to remember:: Things you need to keep in mind.
+* Initial setup:: Getting started with commit access.
+* ssh clone:: Cloning using an 'ssh://' URL.
+* Developing patches:: Developing patches.
+* Developing new features:: Developing new features.
+* Developing fixes:: Developing fixes.
+* Coding style:: Where to read up on the coding style.
+* Doing paperwork:: Legal stuff in order to contribute.
+* Tools:: Tools to have on your system for
+ development.
+* GNU Tools:: The GNU Autotools.
+* Compilers:: A discussion of compilers that can be
+ used.
+* Debugging:: Compiling for debugging.
+
+
+File: gawkworkflow.info, Node: Preface, Next: Contributing, Prev: Top, Up:
Top
+
+Preface
+*******
+
+This Info file describes how to participate in development of GNU Awk
+('gawk'). GNU Awk is a Free Software project belonging to the Free
+Software Foundation's GNU project.
+
+ The Info file focuses on participation in the project (that is, how
+to work most effectively if you wish to contribute to it) and also
+describes how to make use of the Git (http://git-scm.org) distributed
+source code management system for 'gawk' development.
+
+ You should be comfortable working with traditional UNIX-style tools
+and with the C language and standard library facilities.
+
+* Menu:
+
+* This Manual:: How to use this manual.
+* Conventions:: Typographical Conventions.
+* Acknowledgments:: Acknowledgments.
+* Reviewers:: A note to reviewers.
+
+
+File: gawkworkflow.info, Node: This Manual, Next: Conventions, Up: Preface
+
+Using This Book
+===============
+
+This Info file has the following chapters and appendices:
+
+ * *note Contributing:: describes how to start contributing to the
+ 'gawk' project.
+
+ * *note Using Git:: introduces the Git distributed source code
+ management system.
+
+ * *note Configuring git:: describes some initial set-up you need to
+ do before using Git seriously.
+
+ * *note Development without commit access:: gets into the meat of the
+ development workflow, describing how to work if you don't have
+ commit access to the Savannah repository.
+
+ * *note Development with commit access:: continues the discussion,
+ covering what's different when you can commit directly to the
+ Savannah repository.
+
+ * *note General practices:: describes general development practices
+ used by the 'gawk' development team.
+
+ * *note Repo Maintenance:: presents several different things you need
+ to know about to keep your repo in good shape.
+
+ * *note Development Stuff:: describes some important points you
+ should be familiar with in order to participate in 'gawk'
+ development and presents some tools that may make your work easier.
+
+ * *note Cheat Sheet:: provides a short "cheat sheet" summarizing all
+ the Git commands referenced in this Info file.
+
+ * *note Resources:: provides a few pointers to Internet resources for
+ learning more about Git.
+
+
+File: gawkworkflow.info, Node: Conventions, Next: Acknowledgments, Prev:
This Manual, Up: Preface
+
+Typographical Conventions
+=========================
+
+This Info file is written in Texinfo
+(http://www.gnu.org/software/texinfo/), the GNU documentation formatting
+language. A single Texinfo source file is used to produce both the
+printed and online versions of the documentation. This minor node
+briefly documents the typographical conventions used in Texinfo.
+
+ Examples you would type at the command line are preceded by the
+common shell primary and secondary prompts, '$' and '>'. Input that you
+type is shown 'like this'. Output from the command is preceded by the
+glyph "-|". This typically represents the command's standard output.
+Error messages and other output on the command's standard error are
+preceded by the glyph "error->". For example:
+
+ $ echo hi on stdout
+ -| hi on stdout
+ $ echo hello on stderr 1>&2
+ error-> hello on stderr
+
+ Characters that you type at the keyboard look 'like this'. In
+particular, there are special characters called "control characters."
+These are characters that you type by holding down both the 'CONTROL'
+key and another key, at the same time. For example, a 'Ctrl-d' is typed
+by first pressing and holding the 'CONTROL' key, next pressing the 'd'
+key, and finally releasing both keys.
+
+ NOTE: Notes of interest look like this.
+
+ CAUTION: Cautionary or warning notes look like this.
+
+
+File: gawkworkflow.info, Node: Acknowledgments, Next: Reviewers, Prev:
Conventions, Up: Preface
+
+Acknowledgments
+===============
+
+Thanks to Ju"rgen Kahrs for his initial efforts to write a document like
+this. Although his prose has not survived, his material was helpful in
+preparing this Info file.
+
+ Thanks to Yehezkel Bernat for reviewing this document and in general
+for his good intentions.
+
+ *FIXME:* YOUR NAME HERE...
+
+
+File: gawkworkflow.info, Node: Reviewers, Prev: Acknowledgments, Up: Preface
+
+Notes to Reviewers
+==================
+
+Please let me know if anything is missing, or unclear. Real errors with
+respect Git commands and usage are very important as well.
+
+ Spelling errors and typo fixes welcome, but not as important.
+
+
+File: gawkworkflow.info, Node: Contributing, Next: Using Git, Prev:
Preface, Up: Top
+
+1 How to Start Contributing
+***************************
+
+'gawk' development is distributed. It's done using electronic mail
+(email) and via branches in the Git repo(1) on Savannah
+(http://savannah.gnu.org), the GNU project's source code management
+site.
+
+ In this major node we use some Git terminology. If you're not at all
+familiar with Git, then skim this major node and come back after reading
+the rest of the Info file.
+
+ 'gawk' is similar to many other Free Software projects. To begin
+contributing, simply start! Take a look at the 'TODO' file in the
+distribution, see if there is something of interest to you, and ask on
+the <address@hidden> mailing list if anyone else is working on it. If
+not, then go for it! (*Note Development Stuff:: for a discussion of
+some of the technical things you'll need to do. Here we describe the
+process in general.)
+
+ Your contribution can be almost anything that is relevant for 'gawk',
+such as code fixes, documentation fixes, and/or new features.
+
+ NOTE: If possible, new features should be done using 'gawk''s
+ extension mechanism. If you want to add a user-visible language
+ change to the 'gawk' core, you're going to have to convince the
+ maintainer and other developers that it's really worthwile to do
+ so.
+
+ Changes that improve performance or portability, or that fix bugs,
+ or that enable more things in extensions, will require less
+ convincing, of course.
+
+ As you complete a task, submit patches for review to the
+<address@hidden> mailing list, where you'll be given feedback about
+your work. Once your changes are acceptable, the maintainer will commit
+them to the Git repository.
+
+ Over time, as the maintainer and development team gain confidence in
+your ability to contribute, you may be asked to join the private 'gawk'
+developers' mailing list, and/or be granted commit access to the Git
+repository on Savannah. This has happened to more than one person who
+just "came out of the woodwork."
+
+ Until that happens, or if you don't want to join the list, you should
+continue to work with private branches and submission of patches to the
+mailing list.
+
+ Once you have commit access, if you want to make a major change or
+add a major feature, where the patch(es) would be very large, it has
+become the practice to create a separate branch, based off of 'master',
+to host the feature. This way the maintainer can review it, and you can
+continue to improve it, until it's ready for integration into 'master'.
+
+ NOTE: Because of the GNU project's requirements for signed
+ paperwork for contributions, the 'gawk' project will *not* work
+ with pull requests from GitHub (http://github.com) or any other
+ Git-based software hosting service. You must submit patches to the
+ mailing list, and be willing to sign paperwork for large patches.
+
+ The <address@hidden> mailing list is not private. Anyone may send
+mail to it, and anyone may subscribe to it. To subscribe, go to the
+list's web page (https://lists.gnu.org/mailman/listinfo/bug-gawk) and
+follow the instructions there. If you plan to be involved long-term
+with 'gawk' development, then you probably should subscribe to the list.
+
+ ---------- Footnotes ----------
+
+ (1) Short for "repository".
+
+
+File: gawkworkflow.info, Node: Using Git, Next: Configuring git, Prev:
Contributing, Up: Top
+
+2 Using Git
+***********
+
+This chapter provides an introduction to using Git. Our point is _not_
+to rave about how wonderful Git is, nor to go into painful detail about
+how it works. Rather we want to give you enough background to
+understand how to use Git effectively for bug fix and feature
+development and to interact ("play nicely") with the development team.
+
+* Menu:
+
+* Push Pull:: The push/pull software development model.
+* Repo Copies:: What it means to have a copy of a repo.
+* Local Branches:: How to best use local branches.
+* Branches are state:: Branches represent development state.
+
+
+File: gawkworkflow.info, Node: Push Pull, Next: Repo Copies, Up: Using Git
+
+2.1 The "Push/Pull" Model of Software Development
+=================================================
+
+Git is a powerful, distributed source code management system. However,
+the way it's used for 'gawk' development purposely does not take
+advantage of all its features.
+
+ Instead, the model is rather simple, and in many ways much like more
+traditional distributed systems such as the Concurrent Versions System
+(http://www.nongnu.org/cvs) (CVS) or Subversion
+(http://subversion.apache.org) (SVN).
+
+ The central idea can be termed "push/pull." You _pull_ updates down
+from the central repository to your local copy, and if you have commit
+rights, you _push_ your changes or updates up to the central repository.
+
+ Where Git does stand out is in its management of multiple branches of
+development. Git makes it very easy to set up a separate branch for use
+in fixing a bug or developing a feature. You can then easily keep that
+branch up to date with respect to the main development branch(es), and
+eventually merge the changes from your branch into the main branch.
+
+ Almost always Git does these merges for you without problem. When
+there is a problem (a "merge conflict"), usually it is very easy for you
+to "resolve" them and then complete the merge. We talk about this in
+more detail later (*note Merge Conflicts::).
+
+
+File: gawkworkflow.info, Node: Repo Copies, Next: Local Branches, Prev:
Push Pull, Up: Using Git
+
+2.2 How Git Stores Branches and Their Copies
+============================================
+
+So how does Git work?(1)
+
+ A repository consists of a collection of "branches". Each branch
+represents the history of a collection of files and directories (a file
+"tree"). Each combined set of changes to this collection (files and
+directories added or deleted, and/or file contents changed) is termed a
+"commit".
+
+ When you first create a local copy of a remote repository ("clone the
+repo"), Git copies all of the original repository's branches to your
+local system. The original remote repository is referred to as being
+"upstream", and your local repo is "downstream" from it. Git
+distinguishes branches from the upstream repo by prefixing their names
+with 'origin/'. Let's draw some pictures. *note Figure 2.1:
+savannah-repo. represents the state of the repo on Savannah:
+
+ +======================+
+ | Branches |
+ +======================+
+ | master |
+ +----------------------+
+ | gawk-4.1-stable |
+ +----------------------+
+ | gawk-4.0-stable |
+ +----------------------+
+ | feature/fix-comments |
+ +----------------------+
+ | ... |
+ +----------------------+
+
+Figure 2.1: The Savannah 'gawk' Repository
+
+ After you clone the repo, on your local system you will have a single
+branch named 'master' that's visible when you use 'git branch' to see
+your branches.
+
+ $ git clone http://git.savannah.gnu.org/r/gawk.git Clone the repo
+ $ cd gawk Change to local copy
+ $ git branch See branch information
+ -| * master
+
+The current branch is always indicated with a leading asterisk ('*').
+
+ Pictorially, the local repo looks like *note Figure 2.2: your-repo.
+(you can ignore the 'T' column for the moment):
+
+ +===+======================++=============================+
+ | T | Local Branches || Remote Branches |
+ +===+======================++=============================+
+ | X | master || origin/master |
+ +---+----------------------++-----------------------------+
+ | | || origin/gawk-4.1-stable |
+ +---+----------------------++-----------------------------+
+ | | || origin/gawk-4.0-stable |
+ +---+----------------------++-----------------------------+
+ | | || origin/feature/fix-comments |
+ +---+----------------------++-----------------------------+
+ | | || ... |
+ +---+----------------------++-----------------------------+
+
+Figure 2.2: Your Local 'gawk' Repository
+
+Note that what is simply 'gawk-4.1-stable' in the upstream repo is now
+referred to as 'origin/gawk-4.1-stable'. The 'origin/' branches are a
+snapshot of the state of the upstream repo. This is how Git allows you
+to see what changes you've made with respect to the upstream repo,
+without having to actually communicate with the upstream repo over the
+Internet. (When files are identical, Git is smart enough to not have
+two separate physical copies on your local disk.)
+
+ If you're working on a simple bug fix or change, you can do so
+directly in your local 'master' branch. You can then commit your
+changes, and if you have access rights, push them upstream to the
+Savannah repo. (However, there is a process to follow. Please read the
+rest of this Info file.)
+
+ ---------- Footnotes ----------
+
+ (1) The following description is greatly simplified.
+
+
+File: gawkworkflow.info, Node: Local Branches, Next: Branches are state,
Prev: Repo Copies, Up: Using Git
+
+2.3 Local Branches
+==================
+
+Let's talk about local branches in more detail. (The terminology used
+here is my own, not official Git jargon.) There are two kinds of local
+branches:
+
+"Tracking Branches"
+ Tracking branches track branches from the upstream repository. You
+ first create a tracking branch simply by checking out a branch from
+ the upstream. You use the branch name without the leading
+ 'origin/' prefix. For example, 'git checkout gawk-4.1-stable'.
+
+ You can then work on this branch, making commitments to it as you
+ wish. Once things are ready to move upstream, you simply use 'git
+ push', and your changes will be pushed up to the main repo.(1)
+
+ You should *never* checkout a branch using the 'origin/' prefix.
+ Things will get very confused. Always work on local tracking
+ branches.
+
+"Purely Local Branches"
+ A "purely local branch" exists only on your system. You may be
+ developing some large new feature, or fixing a very difficult bug,
+ or have a change for which paperwork has not yet been completed.
+
+ In such a case, you would keep your changes on a local branch, and
+ periodically synchronize it with 'master' (or whichever upstream
+ branch you started from).
+
+ This may seem somewhat abstract so far. We demonstrate with commands
+and branches in *note Development without commit access::, later in this
+Info file.
+
+ Let's say you have checked out a copy of 'gawk-4.1-stable' and have
+created a purely local branch named 'better-random'. Then our picture
+now looks like *note Figure 2.3: your-repo-2, where the 'T' column
+indicates a tracking branch.
+
+ +===+======================++=============================+
+ | T | Local Branches || Remote Branches |
+ +===+======================++=============================+
+ | X | master || origin/master |
+ +---+----------------------++-----------------------------+
+ | X | gawk-4.1-stable || origin/gawk-4.1-stable |
+ +---+----------------------++-----------------------------+
+ | | || origin/gawk-4.0-stable |
+ +---+----------------------++-----------------------------+
+ | | || origin/feature/fix-comments |
+ +---+----------------------++-----------------------------+
+ | | || ... |
+ +---+----------------------++-----------------------------+
+ | | better-random || |
+ +---+----------------------++-----------------------------+
+
+Figure 2.3: Your Local 'gawk' Repository With a Purely Local Branch
+
+ ---------- Footnotes ----------
+
+ (1) Assuming you have permission to do so, of course.
+
+
+File: gawkworkflow.info, Node: Branches are state, Prev: Local Branches,
Up: Using Git
+
+2.4 Branches Represent Development State
+========================================
+
+Branches represent development state. At any given time, when you
+checkout a particular branch (or create a new one), you have a copy of
+the 'gawk' source tree that you should be able to build and test.
+
+ The following minor nodes describe the different branches in the
+'gawk' repository and what they are for, as well as how to use your own
+branches.
+
+* Menu:
+
+* Repo State:: The different branch types in the repo.
+* Local State:: Managing local branches.
+* Remotes:: What a "remote" is.
+
+
+File: gawkworkflow.info, Node: Repo State, Next: Local State, Up: Branches
are state
+
+2.4.1 Branches in the Savannah Repository
+-----------------------------------------
+
+There are several kinds of branches in the Savannah repository.
+
+"Dead Branches"
+ Branches with the prefix 'dead-branches/' (such as
+ 'dead-branches/const') hold code that was never merged into the
+ main code base. For example, a feature which was started, but
+ later deemed to be unwise to add. These branches keep the code
+ available, but they are not updated.
+
+"Stable Branches"
+ These branches are used for bug fixes to released versions of
+ 'gawk'. Sometimes new development (i.e., user-visible changes)
+ also occurs on these branches, although in a perfect world they
+ would be used only for bug fixes.
+
+ These branches have names like 'gawk-4.1-stable',
+ 'gawk-4.0-stable', and so on. Once a release has been made from
+ 'master', the previous stable branch is not updated. For example,
+ once 'gawk' 4.1.0 was released, no more work was done on
+ 'gawk-4.0-stable'.
+
+"The Main Branch"
+ This is the 'master' branch. Here is where most new feature
+ development takes place, and releases of new major versions are
+ based off of this branch.
+
+ Feature branches are typically based off this branch as well, and
+ when the feature is deemed complete, merged back into it.
+
+"Feature Branches"
+ Often, a proposed new feature or code improvement is quite
+ involved. It may take some time to perfect, or the 'gawk'
+ development team may not be convinced that the feature should be
+ kept.
+
+ For this purpose, the team uses branches prefixed with 'feature/'.
+ This prefix is used even for code that simply improves the
+ internals and does not make a user-visible change.
+
+ Having large changes on separate branches makes it easier for
+ members of the team to review the code, and also makes it easier to
+ keep the changes up-to-date with respect to 'master', since Git
+ excels at merging commits from one branch to another.
+
+
+File: gawkworkflow.info, Node: Local State, Next: Remotes, Prev: Repo
State, Up: Branches are state
+
+2.4.2 Branches in Your Local Repository
+---------------------------------------
+
+Purely local branches are where you do your own development. You may
+use purely local branches because you don't have commit rights to the
+Savannah repo. You may also use them if you are doing some work that
+isn't ready for sharing with the rest of the team, or cannot be
+committed for some other reason.
+
+ For example, for around a nine-month period, the maintainer kept a
+purely local branch for some contributed changes for which paperwork had
+not yet been completed.
+
+
+File: gawkworkflow.info, Node: Remotes, Prev: Local State, Up: Branches are
state
+
+2.4.3 A Closer Look at Branch Naming
+------------------------------------
+
+Earlier, we said that Git maintains copies of the branches in the
+upstream repo, as well as manages your local branches. You can see all
+these branches with 'git branch -a':
+
+ $ git branch -a
+ -| gawk-4.1-stable
+ -| * master
+ -| remotes/origin/HEAD -> origin/master
+ -| remotes/origin/dead-branches/async-events
+ -| ...
+ -| remotes/origin/feature/api-mpfr
+ -| remotes/origin/feature/array-iface
+ -| remotes/origin/feature/fix-comments
+ -| ...
+
+ You'll note that what we've referred to as 'origin/' branches appear
+in the output with an additional prefix: 'remotes/'. Up to this point,
+we've treated Git as if it allowed only a singled upstream repository.
+But in fact, you can configure it to use more than one. All the known
+upstream repositories are grouped under the 'remotes/' prefix, with
+'remotes/origin' being the one from which you initially cloned your
+local repository.
+
+ The ability to work with multiple upstream repositories is an
+advanced one; 'gawk' development does not make use of it. The intent of
+this node is to explain the output from 'git branch -a', nothing more.
+
+
+File: gawkworkflow.info, Node: Configuring git, Next: Development without
commit access, Prev: Using Git, Up: Top
+
+3 Configuring Global Settings For Git
+*************************************
+
+Before starting to use Git, you should configure it with some important
+settings that won't change as you use Git. You may configure options
+both globally, and on a per-repository basis. Here, we discuss only
+global configuration settings.
+
+ You can configure Git using either 'git config', or by editing the
+relevant files with your favorite text editor.(1)
+
+ The first things to set are your email address and your real name:
+
+ $ git config --global user.name "J.P. Developer" Set full name
+ $ git config --global user.email address@hidden Set email address
+
+ Setting these two items are an absolute requirement. *Note*: No
+aliases are allowed. If you can't supply your real name, you cannot
+contribute to the project. Other options that the 'gawk' maintainer
+recommends that you use are:
+
+ $ git config --global push.default=simple Only push current branch
+ $ git config --global pager.status=true Use pager for output of git
status
+
+ The global settings are stored in the '.gitconfig' file in your home
+directory. The file looks like this:
+
+ [user]
+ name = J.P. Developer
+ email = address@hidden
+ [push]
+ default = simple
+ [pager]
+ status = true
+
+ The 'push.default=simple' setting ensures that older versions of Git
+only push the current branch up to the Savannah repo. This is the
+safest way to operate, and is the default in current Git versions.
+
+ There may be other settings in your configuration file as well. Use
+'git config' to see your settings:
+
+ $ git config --list
+ -| user.name=J.P. Developer
+ -| address@hidden
+ -| push.default=simple
+
+ Here are the 'gawk' maintainer's settings:
+
+ $ git config --global --list
+ -| user.name=Arnold D. Robbins
+ -| address@hidden
+ -| credential.helper=cache --timeout=3600
+ -| push.default=simple
+ -| color.ui=false
+ -| core.autocrlf=input
+ -| pager.status=true
+ -| log.decorate=auto
+
+ Additional, per-project ("local") settings are stored in each repo's
+'.git/config' file.
+
+ ---------- Footnotes ----------
+
+ (1) You are required to use either Vim or Emacs, other text editors
+are not allowed. Of course, reasonable developers wouldn't want to use
+any other editor anyway.
+
+
+File: gawkworkflow.info, Node: Development without commit access, Next:
Development with commit access, Prev: Configuring git, Up: Top
+
+4 Development Without Commit Access
+***********************************
+
+In this chapter we present step-by-step recipes for checking out and
+working with a local copy of the Savannah Git repo for 'gawk'. The
+presentation is for when you do not have commit access to the Git repo,
+and so you cannot push your changes directly.
+
+* Menu:
+
+* Cloning:: Cloning the repo the first time.
+* Switching Branches:: Moving from one branch to another.
+* Starting A New Branch:: Starting a new branch for development.
+* Undoing a change:: Throwing away changes.
+* Updating:: Keeping in sync with the upstream repo.
+* Submitting Changes:: How to submit your changes.
+* Removing Branches:: Getting rid of unneeded branches.
+* Points to remember:: Things you need to keep in mind.
+
+
+File: gawkworkflow.info, Node: Cloning, Next: Switching Branches, Up:
Development without commit access
+
+4.1 Cloning The Repo
+====================
+
+Clone the Savannah repo using 'git clone'. You may do so using either
+the native Git protocol, or using HTTP if you must go through a gateway
+or firewall that won't pass the Git protocol.
+
+ To choose which method, you supply a "URL" for the repo when you
+clone it, as follows.
+
+ * Clone via the Git native protocol:
+
+ $ git clone git://git.savannah.gnu.org/gawk.git Clone the repo
+ -| ...
+ $ cd gawk Start working
+
+ This will be faster, but not all firewalls pass the Git protocol on
+ through.
+
+ * Clone via the HTTP protocol:
+
+ $ git clone http://git.savannah.gnu.org/r/gawk.git Clone the repo
+ -| ...
+ $ cd gawk Start working
+
+ _You only need to clone the repo once._ From then on, you update its
+contents using other Git commands. For example, after coming back from
+your vacation in the Bahamas:
+
+ $ cd gawk Move to the repo
+ $ make distclean A good idea before updating
+ -| ...
+ $ git pull Update it
+
+ To build, you should generally follow this recipe:
+
+ $ ./bootstrap.sh && ./configure && make -j && make check
+
+ NOTE: Unless you have installed all the tools described in *note
+ GNU Tools::, you _must_ run './bootstrap.sh' every time you clone a
+ repo, do a 'git pull' or checkout a different branch. (In the
+ latter case, do 'make distclean' first.) Otherwise things will get
+ messy very quickly. The 'bootstrap.sh' script ensures that all of
+ the file time stamps are up to date so that it's not necessary to
+ run the various configuration tools.
+
+
+File: gawkworkflow.info, Node: Switching Branches, Next: Starting A New
Branch, Prev: Cloning, Up: Development without commit access
+
+4.2 Switching Branches
+======================
+
+So far, we've been working in the default 'master' branch. Let's check
+what's happening in the 'gawk-4.1-stable' branch:
+
+ $ make distclean Clean up
+ $ git checkout gawk-4.1-stable Checkout a
different branch
+ -| ...
+ $ git pull Get up to date
+ -| ...
+ $ ./bootstrap.sh && ./configure && make -j && make check Start working
+
+
+File: gawkworkflow.info, Node: Starting A New Branch, Next: Undoing a
change, Prev: Switching Branches, Up: Development without commit access
+
+4.3 Starting A New Branch
+=========================
+
+Let's say you want to work on a new feature. For example, you might
+decide to add Python syntax support.(1) You should create a new branch
+on which to work. First, switch back to 'master':
+
+ $ make distclean
+ $ git checkout master
+
+ Now, create a new branch. The easiest way to do that is with the
+'-b' option to 'git checkout':
+
+ $ git checkout -b feature/python
+ -| ...
+
+ You now do massive amounts of work in order to add Python syntax
+support. As you do each defined chunk of work, you update the
+'ChangeLog' file with your changes before "committing" them to the repo.
+
+ Let's say you've added a new file 'python.c' and updated several
+others. Use 'git status' to see what's changed:
+
+ $ git status
+ -| ...
+
+ Before committing the current set of changes, you can use 'git diff'
+to view the changes. You may also use 'git difftool'(2) to run an
+external 'diff' command, such as 'meld' on GNU/Linux:
+
+ $ git diff Regular built-in tool
+ $ git difftool --tool=meld GUI diff tool
+
+ When you're happy with the changes, use 'git add' to tell Git which
+of the changed and/or new files you wish to have ready to be committed:
+
+ $ git add ...
+
+ Use 'git status' to see that your changes are scheduled for
+committing:
+
+ $ git status
+ -|
+
+ Now you can commit your changes to your branch:
+
+ $ git commit
+
+Running 'git commit' causes Git to invoke an editor (typically from the
+'$EDITOR' environment variable) in which you can compose a commit
+message. Please supply a short message summarizing the commit. This
+message will be visible via 'git log'.
+
+ ---------- Footnotes ----------
+
+ (1) Just joking. Please don't attempt this for real.
+
+ (2) Don't run 'git difftool' in the background; it works
+interactively.
+
+
+File: gawkworkflow.info, Node: Undoing a change, Next: Updating, Prev:
Starting A New Branch, Up: Development without commit access
+
+4.4 Undoing A Change
+====================
+
+Should you need to undo a change that you have not yet committed (so
+that you can start over), you can do so on per-file basis by simply
+checking out the file again:
+
+ git checkout awkgram.y Undo changes to awkgram.y. There is no output
+
+ To start over completely, use 'git reset --hard'. Note that this
+will _throw away_ all your changes, with no chance for recovery, so be
+sure you really want to do it.
+
+
+File: gawkworkflow.info, Node: Updating, Next: Submitting Changes, Prev:
Undoing a change, Up: Development without commit access
+
+4.5 Updating and Merging
+========================
+
+As you work on your branch, you will occasionally want to bring it up to
+date with respect to 'master'. This minor node dicusses updating locale
+branches and handling merge conflicts.
+
+* Menu:
+
+* Rebasing:: Rebasing A Local Branch.
+* Merge Conflicts:: Dealing With Merge Conflicts.
+
+
+File: gawkworkflow.info, Node: Rebasing, Next: Merge Conflicts, Up: Updating
+
+4.5.1 Rebasing A Local Branch
+-----------------------------
+
+For purely local branches, bringing your branch up to date is called
+"rebasing", which causes the branch to look _as if_ you had started from
+the latest version of 'master'. The steps are as follows:
+
+ $ git checkout master Checkout master
+ $ git pull Update it
+ $ git checkout feature/python Move back to new, purely local branch
+ $ git rebase master "Start over" from current master
+
+
+File: gawkworkflow.info, Node: Merge Conflicts, Prev: Rebasing, Up: Updating
+
+4.5.2 Dealing With Merge Conflicts
+----------------------------------
+
+Sometimes, when merging from 'master' into your branch, or from a branch
+into 'master', there will be "merge conflicts". These are one or more
+areas within a file where there are conflicting sets of changes, and Git
+could not do the merge for you. In this case, the conflicted area will
+be delimited by the traditional conflict markers, '<<<', '===' and
+'>>>'.
+
+ Your mission is then to edit the file and "resolve" the conflict by
+fixing the order of additions (such as in a 'ChangeLog' file), or fixing
+the code to take new changes into account.
+
+ Once you have done so, you tell Git that everything is OK using 'git
+add' and 'git commit':
+
+ $ git checkout feature/python Move back to new, purely local branch
+ $ git rebase master "Start over" from current master
+ -| ... Kaboom! Conflict. FIXME: Show real output here
+ $ gvim main.c Edit the file and fix the problem
+ $ git add main.c Tell Git everything is OK now ...
+ $ git commit ... and it's settled
+ $ git rebase --continue Continue the rebase
+
+ The 'git rebase --continue' then continues the process of rebasing
+the current branch that we started in *note Rebasing::. It's not
+necessary if you are using 'git merge' (*note Points to remember::).
+
+
+File: gawkworkflow.info, Node: Submitting Changes, Next: Removing Branches,
Prev: Updating, Up: Development without commit access
+
+4.6 Submitting Your Changes
+===========================
+
+So now your feature is complete. You've added test cases for it to the
+test suite(1), you have 'ChangeLog' entries that describe all the
+changes(2), you have documented the new feature(3), and everything works
+great. You're ready to submit the changes for review, and with any
+luck, inclusion into 'gawk'.
+
+ There are two ways to submit your changes for review.
+
+_Generate a single large patch_
+ To do this, simply compare your branch to the branch off which it
+ is based:
+
+ $ git checkout feature/python
+ $ git diff master > /tmp/python.diff
+
+ Mail the 'python.diff' file to the appropriate mailing list along
+ with a description of what you've changed and why.
+
+_Generate a set of patches that in toto comprise your changes_
+ To do this, use 'git format-patch':
+
+ $ git checkout feature/python
+ $ git format-patch
+
+ This creates a set of patch files, one per commit that isn't on the
+ original branch. Mail these patches, either separately, or as a
+ set of attachments, to the appropriate mailing list along with a
+ description of what you've changed and why.
+
+ Either way you choose to submit your changes, the 'gawk' maintainer
+and development team will review your changes and provide feedback. If
+you have signed paperwork with the FSF for 'gawk' and the maintainer
+approves your changes, he will apply the patch(es) and commit the
+changes.
+
+ Which list should you send mail to? If you are just starting to
+contribute, use <address@hidden>. After making enough contributions,
+you may be invited to join the private 'gawk' developers' mailing list.
+If you do so, then submit your changes to that list.
+
+ If you make any substantial changes, you will need to assign
+copyright in those changes to the Free Software Foundation before the
+maintainer can commit those changes. *Note Doing paperwork::, for more
+information.
+
+ ---------- Footnotes ----------
+
+ (1) You did do this, didn't you?
+
+ (2) You remembered this, right?
+
+ (3) You wouldn't neglect this, would you?
+
+
+File: gawkworkflow.info, Node: Removing Branches, Next: Points to remember,
Prev: Submitting Changes, Up: Development without commit access
+
+4.7 Removing Branches
+=====================
+
+Once the maintainer has integrated your changes, you can get rid of your
+local branch:
+
+ $ git checkout master Move to upstream branch
+ $ git pull Update
+ $ gvim ChangeLog ... Verify your changes are in
+ $ git branch -d feature/python Remove your local branch
+
+
+File: gawkworkflow.info, Node: Points to remember, Prev: Removing Branches,
Up: Development without commit access
+
+4.8 Points to Remember
+======================
+
+There are some important points to remember:
+
+ * Always do a 'make distclean' before switching between branches.
+ Things will get really confused if you don't.
+
+ * For upstream branches, _always_ work with tracking branches.
+ _Never_ use 'git checkout origin/WHATEVER'. Git will happily let
+ you do something like that, but it's just plain asking for trouble.
+
+ * Make sure your tracking branches are up-to-date before doing
+ anything with them, particularly using them as the basis for a
+ rebase or merge. This typically means a three-step process:
+
+ $ git checkout master Get to local copy
+ $ git pull Bring it up to date
+ $ git checkout feature/python Go back to your branch
+
+ You can then do the actual rebase:
+
+ $ git rebase master Now rebase your feature off of
master
+
+ * Git always treats the currently checked-out branch as the object of
+ operations. For example, when comparing files with the regular
+ 'diff' command, the usage is 'diff OLDFILE NEWFILE'. For 'git
+ diff', the current branch takes the place of NEWFILE, thus:
+
+ $ git checkout feature/python
+ $ git diff master Compare master to current branch
+
+ or if merging:
+
+ $ git checkout master Checkout master
+ $ git pull Update tracking branch
+ $ git merge feature/python Merge changes into master
+
+
+File: gawkworkflow.info, Node: Development with commit access, Next: General
practices, Prev: Development without commit access, Up: Top
+
+5 Development With Commit Access
+********************************
+
+This major node describes how to do development when you _do_ have
+commit access to the 'gawk' repo on Savannah.
+
+* Menu:
+
+* Initial setup:: Getting started with commit access.
+* ssh clone:: Cloning using an 'ssh://' URL.
+* Developing patches:: Developing patches.
+* Developing new features:: Developing new features.
+* Developing fixes:: Developing fixes.
+
+
+File: gawkworkflow.info, Node: Initial setup, Next: ssh clone, Up:
Development with commit access
+
+5.1 Initial Setup
+=================
+
+Congratulations! After becoming a quality contributor to 'gawk'
+development, you've been invited to join the private development list
+and to accept having commit access to the repo.
+
+ The first thing to do is to create an account on Savannah, choosing a
+unique user name. To do so, go to the Savannah home page
+(http://savannah.gnu.org) and click on the "New User" link. The setup
+will include uploading of your 'ssh' key, as per the instructions on the
+Savannah web page.
+
+ After you've done all this, send email to the maintainer with your
+Savannah user name, and he will add you to the list of users who have
+commit access to the repo.
+
+
+File: gawkworkflow.info, Node: ssh clone, Next: Developing patches, Prev:
Initial setup, Up: Development with commit access
+
+5.2 Cloning The Repo With An 'ssh' URL
+======================================
+
+In order to be able to commit changes to the repo, you must clone it
+using an 'ssh://' URL. Cloning the repo with 'ssh' is similar to cloning
+with the Git protocol or with HTTP, but the URL is different:
+
+ $ git clone ssh://address@hidden/srv/git/gawk.git
+ -| ...
+
+ Here, you should replace 'yourname' in the command with the user name
+you chose for use on Savannah.
+
+
+File: gawkworkflow.info, Node: Developing patches, Next: Developing new
features, Prev: ssh clone, Up: Development with commit access
+
+5.3 Developing Patches
+======================
+
+The first part of developing a patch is the same as for developers
+without commit access:
+
+ 1. Develop the code and test it.
+
+ 2. Update the 'ChangeLog'.
+
+ 3. If necessary, update the documentation: 'doc/gawktexi.in' and/or
+ 'doc/gawk.1'.
+
+ 4. Use 'git diff > mychange.diff' to create a patch file.
+
+ 5. Send it to the mailing list for discussion.
+
+ 6. Iterate until the patch is ready to be committed.
+
+ However, now that you have commit access, you can commit the fix and
+push it up to the repo yourself! Let's assume you've made a bug fix
+directly on 'master'. Here's how to commit your changes:
+
+ $ git diff Review the patch one more time
+ $ git add ... Add any files for committing
+ $ git commit Commit the files. Include a commit message.
+ $ git push Push the files up to the repo. Ta da!
+
+ The first three steps are the same described earlier (*note Starting
+A New Branch::). The 'git push' is what's new, and it updates the repo
+on Savannah. Congratulations!
+
+ As a courtesy, you should send a note to the mailing list indicating
+that you have pushed your change.
+
+
+File: gawkworkflow.info, Node: Developing new features, Next: Developing
fixes, Prev: Developing patches, Up: Development with commit access
+
+5.4 Developing New Features
+===========================
+
+Developing a new feature can be easier once you have commit access to
+the repo. First, create a new branch to hold your feature:
+
+ $ git checkout master Start from master
+ $ git pull Be sure to be up to date
+ $ git checkout -b feature/python Create and switch to a new
branch
+
+ Now, you can develop as normal, adding new files if necessary (such
+as new tests), modifying code, updating the 'ChangeLog' and
+documentation, and so on.
+
+ You can share changes with the mailing list as diffs, as usual.
+However, especially for a large feature, it would be better to push your
+branch up to Savannah. Then, everyone else can simply pull it down to
+their local systems and review your changes at their leisure.
+
+ To push your branch up initially:
+
+ $ git diff Review your changes
+ $ git add ... Add any files for committing
+ $ git commit Commit the files. Include a
commit message
+ $ git push -u origin feature/python Push the branch up to the repo
+
+ When you use 'push -u origin', Git helpfully converts your purely
+local branch into a tracking branch. It becomes as if the branch had
+originated from the upstream repo and you checked it out locally.
+
+ _You only need to do 'git push -u origin' once._ As you continue to
+work on your branch, the workflow simplifies into this:
+
+ $ git diff Review your changes
+ $ git add ... Add any files for committing
+ $ git commit Commit the files
+ $ git push Push your changes to the branch upstream
+
+
+File: gawkworkflow.info, Node: Developing fixes, Prev: Developing new
features, Up: Development with commit access
+
+5.5 Developing Fixes
+====================
+
+If you want to make a fix on 'master' or on the current stable branch,
+you work the same way, by producing and discussing a diff on the mailing
+list. Once it's approved, you can commit it yourself:
+
+ $ git checkout master Move to master
+ $ git pull Make sure we're up to date with the maintainer
+ $ gvim ... Make any fixes, compile, test
+ $ git diff Review your changes
+ $ git add ... Add any files for committing
+ $ git commit Commit the files. Include a commit message.
+
+ When you're ready to push your changes:
+
+ $ git pull Download latest version; Git will merge
+ $ gvim ... Resolve any merge conflicts with git add and
git commit
+ $ git push Now you can push your changes upstream
+
+ *Note Merge Conflicts:: for instructions on dealing with merge
+conflicts.
+
+
+File: gawkworkflow.info, Node: General practices, Next: Repo Maintenance,
Prev: Development with commit access, Up: Top
+
+6 General Development Practices
+*******************************
+
+This major node discusses general practices for 'gawk' development. The
+discussion here is mainly for developers with commit access to the
+Savannah repo.
+
+"Propagating Fixes"
+ Usually, bug fixes should be made on the current "stable" branch.
+ Once a fix has been reviewed and approved, you can commit it and
+ push it yourself. Typically, the maintainer then takes care to
+ merge the fix to 'master' and from there to any other branches.
+ However, you are welcome to save him the time and do this yourself.
+
+"Directory ownership"
+ Some developers "own" certain parts of the tree, such as the 'pc'
+ and 'vms' directories. They are allowed to commit changes to those
+ directories without review by the mailing list, but changes that
+ also touch the mainline code should be submitted for review.
+
+"New feature development"
+ Unless you can convince the maintainer (and the other developers!)
+ otherwise, you should _always_ start branches for new features from
+ 'master', and not from the current "stable" branch.
+
+ Use 'checkout -b feature/FEATURE_NAME' to create the initial
+ branch. You may then elect to keep it purely local, or to push it
+ up to Savannah for review, even if the feature is not yet totally
+ "ready for prime time."
+
+ During development of a new feature, you will most likely wish to
+keep your feature branch up to date with respect to ongoing improvements
+in 'master'. This is generally easy to do. There are two different
+mechanisms, and which one you use depends upon the nature of your new
+feature branch.
+
+"As long as your branch is purely local"
+ You should use 'git rebase' to the keep the branch synchronized
+ with the original branch from which it was forked:
+
+ $ git checkout master Move to master
+ $ git pull Bring it up to date
+ $ git checkout feature/python Move to your new feature branch
+ $ git rebase master Rebase from master
+
+ The rebasing operation may require that you resolve conflicts
+ (*note Merge Conflicts::). Edit any conflicted files and resolve
+ the problem(s). Compile and test your changes, then use 'git add'
+ and 'git commit' to indicate resolution, and then use 'git rebase
+ --continue' to continue the rebasing. Git is very good about
+ providing short instructions on how to continue when such conflicts
+ occur.
+
+"Once the branch has been pushed up to Savannah"
+ You _must_ use 'git merge' to bring your feature branch up to date.
+ That flow looks like this:
+
+ $ git checkout master Move to master
+ $ git pull Bring it up to date
+ $ git checkout feature/python Move to your new feature branch
+ $ git merge master Merge from master
+
+ Here too, you may have to resolve any merge conflicts (*note Merge
+ Conflicts::). Once that's done, you can push the changes up to
+ Savannah.
+
+ When the changes on your branch are complete, usually the
+ maintainer merges the branch to 'master'. But there's really no
+ magic involved, the merge is simply done in the other direction:
+
+ $ git checkout feature/python Checkout feature branch
+ $ git pull Bring it up to date
+ $ git checkout master Checkout master
+ $ git pull Bring it up to date
+ $ git merge feature/python Merge from feature/python into
master
+
+ If you've been keeping 'feature/python' in sync with 'master', then
+ there should be no merge conflicts to resolve, and you can push the
+ result to Savannah:
+
+ $ git push Push up to Savannah
+
+ Since 'feature/python' is no longer needed, it can be gotten rid
+ of:
+
+ $ git branch -d feature/python Still on master, delete
feature branch
+ $ git push -u origin -d feature/python Delete the branch on
Savannah
+
+ The 'git push' command deletes the 'feature/python' branch from the
+ Savannah repo.
+
+ Finally, you should send an email to developer's list describing
+ what you've done so that everyone else can delete their copies of
+ the branch and do a 'git fetch --prune' (*note Repo Maintenance::).
+
+ To update the other remaining development branches with the latest
+ changes on 'master', use the 'helpers/update-branches.sh' script in
+ the repo.
+
+
+File: gawkworkflow.info, Node: Repo Maintenance, Next: Development Stuff,
Prev: General practices, Up: Top
+
+7 Keeping Your Repo Organized
+*****************************
+
+There are a few commands you should know about to help keep your local
+repo clean.
+
+_Removing old branches_
+ Developers add branches to the Savannah repo and when development
+ on them is done, they get merged into 'master'. Then the branches
+ on Savannah are deleted (as shown in *note General practices::).
+
+ However, your local copies of those branches (labelled with the
+ 'origin/' prefix) remain in your local repo. If you don't need
+ them, then you can clean up your repo as follows.
+
+ First, remove any related tracking branch you may have:
+
+ $ git pull Get up to date
+ $ git branch -d feature/merged-feature Remove tracking branch
+
+ Then, ask Git to clean things up for you:
+
+ $ git fetch --prune Remove unneeded branches
+
+_Removing cruft_
+ As Git works, occasional "cruft" collects in the repository. Git
+ does occasionally clean this out on its own, but if you're
+ concerned about disk usage, you can do so yourself using 'git gc'
+ (short for "garbage collect"). For example:
+
+ $ du -s . Check disk usage
+ -| 99188 . Almost 10 megabytes
+ $ git gc Collect garbage
+ -| Counting objects: 32114, done.
+ -| Delta compression using up to 4 threads.
+ -| Compressing objects: 100% (6370/6370), done.
+ -| Writing objects: 100% (32114/32114), done.
+ -| Total 32114 (delta 25655), reused 31525 (delta 25231)
+ $ du -s . Check disk usage again
+ -| 75168 . Down to 7 megabytes
+
+_Renaming branches_
+ Occasionally you may want to rename a branch.(1) If your branch is
+ local and you are on it, us:
+
+ $ git branch -m feature/NEW-NAME
+
+ Otherwise, use:
+
+ $ git branch -m feature/OLD-NAME feature/NEW-NAME
+
+ You then need to fix the upstream repo. This command does so,
+ using an older syntax to simultaneously delete the old name and
+ push the new name. You should be on the new branch:
+
+ $ git push origin :feature/OLD-NAME feature/NEW-NAME
+
+ NOTE: It is the leading ':' in the first branch name that
+ causes Git to delete the old name in the upstream repo. Don't
+ omit it!
+
+ Finally, reset the upstream branch for the local branch with the
+ new name:
+
+ $ git push -u origin feature/NEW-NAME
+
+ ---------- Footnotes ----------
+
+ (1) This discussion adopted from here
+(https://multiplestates.wordpress.com/2015/02/05/rename-a-local-and-remote-branch-in-git).
+
+
+File: gawkworkflow.info, Node: Development Stuff, Next: Cheat Sheet, Prev:
Repo Maintenance, Up: Top
+
+8 Development Stuff
+*******************
+
+This major node discusses other things you need to know and/or do if
+you're going to participate seriously in 'gawk' development.
+
+* Menu:
+
+* Coding style:: Where to read up on the coding style.
+* Doing paperwork:: Legal stuff in order to contribute.
+* Tools:: Tools to have on your system for development.
+* Debugging:: Compiling for debugging.
+
+
+File: gawkworkflow.info, Node: Coding style, Next: Doing paperwork, Up:
Development Stuff
+
+8.1 Coding Style
+================
+
+You should read the discussion about adding code in the 'gawk'
+documentation. *Note Additions: (gawk)Additions, for a discussion of
+the general procedure. In particular, pay attention to the coding style
+guidelines in *note Adding Code: (gawk)Adding Code.(1) These two
+sections may also be found online, at
+<https://www.gnu.org/software/gawk/manual/html_node/Additions.html#Additions>,
+and
+<https://www.gnu.org/software/gawk/manual/html_node/Adding-Code.html#Adding-Code>,
+respectively.
+
+ ---------- Footnotes ----------
+
+ (1) Changes that don't follow the coding style guidelines won't be
+accepted. Period.
+
+
+File: gawkworkflow.info, Node: Doing paperwork, Next: Tools, Prev: Coding
style, Up: Development Stuff
+
+8.2 Assigning Copyrights to the FSF
+===================================
+
+For any change of more than just a few lines, you will need to assign
+copyright in (that is, ownership of) those changes to the Free Software
+Foundation.
+
+ This is generally an easy thing to do. In particular, you can choose
+to use a version of the copyright assignment which assigns all your
+current _and future_ changes to 'gawk' to the FSF. This means that you
+only need to do the paperwork once, and from then on all your changes
+will automatically belong to the FSF. The maintainer recommends doing
+this.
+
+ The maintainer will help you with this process once you have a
+contribution that warrants it.
+
+
+File: gawkworkflow.info, Node: Tools, Next: Debugging, Prev: Doing
paperwork, Up: Development Stuff
+
+8.3 Software Tools You Will Need
+================================
+
+This minor node discusses additional tools that you may need to install
+on your system in order to be in sync with what the 'gawk' maintainer
+uses. It also discusses different C compiler options for use during
+code development, and how to compile 'gawk' for debugging.
+
+* Menu:
+
+* GNU Tools:: The GNU Autotools.
+* Compilers:: A discussion of compilers that can be used.
+
+
+File: gawkworkflow.info, Node: GNU Tools, Next: Compilers, Up: Tools
+
+8.3.1 GNU Tools
+---------------
+
+If you expect to work with the configuration files and/or the 'Makefile'
+files, you will need to install a number of other GNU tools. In
+general, you should be using the latest versions of the tools, or least
+the same ones that the maintainer himself uses. This helps minimize the
+differences that the maintainer has to resolve when merging changes, and
+in general avoids confusion and hassle. Similarly, you should install
+the latest GNU documentation tools as well. The tools are described in
+the following list:
+
+'autoconf'
+ GNU Autoconf processes the 'configure.ac' files in order to
+ generate the 'configure' shell script and 'config.h.in' input file.
+ See the Autoconf home page
+ (https://www.gnu.org/software/autoconf/autoconf.html) for more
+ information.
+
+'automake'
+ GNU Automake processes the 'configure.ac' and 'Makefile.am' files
+ to produce 'Makefile.in' files. See the Automake home page
+ (https://www.gnu.org/software/automake) for more information.
+
+'gettext'
+ GNU Gettext processes the 'gawk' source code to produce the
+ original 'po/gawk.pot' message template file. Normally you should
+ not need need to do this; the maintainer usually manages this task.
+ See the Gettext home page (https://www.gnu.org/software/gettext)
+ for more information.
+
+'libtool'
+ GNU Libtool works with Autoconf and Automake to produce portable
+ shared libraries. It is used for the extensions that ship with
+ 'gawk', whose code is in the 'extensions' directory. See the
+ Libtool home page (https://www.gnu.org/software/libtool) for more
+ information.
+
+'makeinfo'
+ The 'makeinfo' command is used to build the Info versions of the
+ documentation. You need to have the same version as the maintainer
+ uses, so that when you make a change to the documentation, the
+ corresponding change to the generated Info file will be minimal.
+ 'makeinfo' is part of GNU Texinfo. See the Texinfo home page
+ (https://www.gnu.org/software/texinfo) for more information.
+
+
+File: gawkworkflow.info, Node: Compilers, Prev: GNU Tools, Up: Tools
+
+8.3.2 Compilers
+---------------
+
+The default compiler for 'gawk' development is GCC, the GNU Compiler
+Collection (https://gcc.gnu.org). The default version of GCC is
+whatever is on the maintainer's personal GNU/Linux system, although he
+does try to build the latest released version if that is newer than
+what's on his system, and then occasionally test 'gawk' with it.
+
+ He also attempts to test occasionally with 'clang'
+(https://clang.llvm.org/). However, he uses whatever is the default for
+his GNU/Linux system, and does _not_ make an effort to build the current
+version for testing.
+
+ Both GCC and 'clang' are highly optimizing compilers that produce
+good code, but are very slow. There are two other compilers that are
+faster, but that may not produce quite as good code. However, they are
+both reasonable for doing development.
+
+_The Tiny C Compiler, 'tcc'_
+ This compiler is _very_ fast, but it produces only mediocre code.
+ It is capable of compiling 'gawk', and it does so well enough that
+ 'make check' runs without errors.
+
+ However, in the past the quality has varied, and the maintainer has
+ had problems with it. He recommends using it for regular
+ development, where fast compiles are important, but rebuilding with
+ GCC before doing any commits, in case 'tcc' has missed
+ something.(1)
+
+ See the project's home page (http://www.tinycc.org) for some
+ information. More information can be found in the project's Git
+ repository (http://repo.or.cz/tinycc.git). The maintainer builds
+ from the 'mob' branch for his work, but after updating it you
+ should check that this branch still works to compile 'gawk' before
+ installing it.
+
+_The (Revived) Portable C Compiler_
+ This is an updated version of the venerable Unix Portable C
+ Compiler, PCC. It accepts ANSI C syntax and supports both older and
+ modern architectures. It produces better code than 'tcc' but is
+ slower, although still much faster than GCC and 'clang'.
+
+ See the project's home page (http://pcc.ludd.ltu.se) for more
+ information. See <http://pcc.ludd.ltu.se/supported-platforms> for
+ instructions about obtaining the code using CVS and building it.
+
+ An alternative location for the source is the 'gawk' maintainer's
+ Git mirror (https://github.com/arnoldrobbins/pcc-revived) of the
+ code.
+
+ ---------- Footnotes ----------
+
+ (1) This bit the maintainer once.
+
+
+File: gawkworkflow.info, Node: Debugging, Prev: Tools, Up: Development Stuff
+
+8.4 Compiling For Debugging
+===========================
+
+If you wish to compile for debugging, you should use GCC. After running
+'configure' but before running 'make', edit the 'Makefile' and remove
+the '-O2' flag from the definition of 'CFLAGS'. Optionally, do the same
+for 'extensions/Makefile'. Then run 'make'.
+
+ You can enable additional debugging code by creating a file named
+'.developing' in the 'gawk' source code directory _before_ running
+'configure'. Doing so enables additional conditionally-compiled
+debugging code within 'gawk', and adds additional warning and debugging
+options if compiling with GCC.
+
+
+File: gawkworkflow.info, Node: Cheat Sheet, Next: Resources, Prev:
Development Stuff, Up: Top
+
+Appendix A Git Command Cheat Sheet
+**********************************
+
+This major node provides an alphabetical list of the Git commands cited
+in this Info file, along with brief descriptions of what the commands
+do.
+
+ Note that you may always use either 'git help COMMAND' or 'git
+COMMAND --help' to get short, man-page style help on how to use any
+given Git command.
+
+'git add'
+ Add a file to the list of files to be committed.
+
+'git branch'
+ View existing branches, or delete a branch. Most useful options:
+ '-a' and '-d'.
+
+'git checkout'
+ Checkout an existing branch, create a new branch, or checkout a
+ file to reset it. Use the '-b' option to create and checkout a new
+ branch in one operation.
+
+'git clone'
+ Clone (make a new copy of) an existing repository. You generally
+ only need to do this once.
+
+'git commit'
+ Commit changes to files which have been staged for committing with
+ 'git add'. This makes your changes permanent, _in your local
+ repository only_. To publish your changes to an upstream repo, you
+ must use 'git push'.
+
+'git config'
+ Display and/or change global and/or local configuration settings.
+
+'git diff'
+ Show a unified-format diff of what's changed in the current
+ directory as of the last commit. It helps to have Git configured
+ to use its builtin pager for reviewing diffs (*note Configuring
+ git::).
+
+'git difftool'
+ Use a "tool" (usually a GUI-based program) to view differences,
+ instead of the standard textual diff as you'd get from 'git diff'.
+
+'git fetch'
+ Update your local copy of the upstream's branches. That is, update
+ the various 'origin/' branches. This leaves your local tracking
+ branches unchanged. With the '--prune' option, this removes any
+ copies of stale 'origin/' branches.
+
+'git format-patch'
+ Create a series of patch files, one per commit not on the original
+ branch from which you started.
+
+'git gc'
+ Run a "garbage collection" pass in the current repository. This
+ can often reduce the space used in a large repo. For 'gawk' it
+ does not make that much difference.
+
+'git help'
+ Print a man-page-style usage summary for a command.
+
+'git log'
+ Show the current branch's commit log. This includes who made the
+ commit, the date, and the commit message. Commits are shown from
+ newest to oldest.
+
+'git merge'
+ Merge changes from the named branch into the current one.
+
+'git pull'
+ When in your local tracking branch 'XXX', run 'git fetch', and then
+ merge from 'origin/XXX' into 'XXX'.
+
+'git push'
+ Push commits from your local tracking branch 'XXX' through
+ 'origin/XXX' and on to branch 'XXX' in the upstream repo. Use 'git
+ push -u origin -d XXX' to delete an upstream branch. (Do so
+ carefully!)
+
+'git rebase'
+ Rebase the changes in the current purely local branch to look as if
+ they had been made relative to the latest commit in the current
+ upstream branch (typically 'master'). This is how you keep your
+ local, in-progress changes up-to-date with respect to the original
+ branch from which they were started.
+
+'git reset'
+ Restore the original state of the repo, especially with the
+ '--hard' option. Read up on this command, and use it carefully.
+
+'git status'
+ Show the status of files that are scheduled to be committed, and
+ those that have been modified but not yet scheduled for committing.
+ Use 'git add' to schedule a file for committing. This command also
+ lists untracked files.
+
+
+File: gawkworkflow.info, Node: Resources, Next: TODO, Prev: Cheat Sheet,
Up: Top
+
+Appendix B Git Resources
+************************
+
+There are many Git resources available on the Internet. Start at the
+Git Project home page (http://git-scm.org). In particular, the 'Pro
+Git' book (https://git-scm.com/book/en/v2) is available online.
+
+ See also the Savannah quick introduction to Git
+(http://savannah.gnu.org/maintenance/UsingGit).
+
+
+File: gawkworkflow.info, Node: TODO, Next: Index, Prev: Resources, Up: Top
+
+Appendix C Stuff Still To Do In This Document
+*********************************************
+
+ * Fill out all examples with full output
+
+
+File: gawkworkflow.info, Node: Index, Prev: TODO, Up: Top
+
+Index
+*****
+
+ [index ]
+* Menu:
+
+* --help option for git: Cheat Sheet. (line 10)
+* .developing file: Debugging. (line 11)
+* .gitconfig file: Configuring git. (line 27)
+* account, Savannah, creation of: Initial setup. (line 10)
+* assigning copyright: Doing paperwork. (line 6)
+* autoconf: GNU Tools. (line 15)
+* automake: GNU Tools. (line 22)
+* autotools: GNU Tools. (line 6)
+* Bernat, Yehezkel: Acknowledgments. (line 10)
+* bootstrap.sh script: Cloning. (line 41)
+* branch, main: Repo State. (line 27)
+* branch, master: Repo State. (line 27)
+* branches, dead: Repo State. (line 8)
+* branches, feature: Repo State. (line 35)
+* branches, local: Local Branches. (line 6)
+* branches, origin/: Repo Copies. (line 68)
+* branches, purely local: Local State. (line 6)
+* branches, removing: Removing Branches. (line 6)
+* branches, removing <1>: Repo Maintenance. (line 9)
+* branches, renaming: Repo Maintenance. (line 44)
+* branches, stable: Repo State. (line 15)
+* branches, tracking: Local Branches. (line 11)
+* ChangeLog file: Starting A New Branch.
+ (line 19)
+* ChangeLog file <1>: Developing patches. (line 11)
+* changes, submitting for review: Submitting Changes. (line 12)
+* clang compiler: Compilers. (line 12)
+* coding style: Coding style. (line 6)
+* committing changes: Starting A New Branch.
+ (line 19)
+* compilers: Compilers. (line 6)
+* compiling for debugging: Debugging. (line 6)
+* configuration setting, pager.status: Configuring git. (line 24)
+* configuration setting, push.default: Configuring git. (line 24)
+* configuration setting, user.email: Configuring git. (line 16)
+* configuration setting, user.name: Configuring git. (line 16)
+* configuration settings: Configuring git. (line 6)
+* configuration settings, global: Configuring git. (line 6)
+* configure.ac file: GNU Tools. (line 15)
+* conflicts, from merging: Merge Conflicts. (line 6)
+* copyright, assignment: Doing paperwork. (line 6)
+* cruft, removing: Repo Maintenance. (line 27)
+* dead branches: Repo State. (line 8)
+* debugging, compiling for: Debugging. (line 6)
+* directory ownership: General practices. (line 17)
+* documentation files: Developing patches. (line 13)
+* email address: Configuring git. (line 14)
+* extensions, gawk: GNU Tools. (line 34)
+* feature branches: Repo State. (line 35)
+* fixes, propagating to other branches: General practices. (line 10)
+* gawk.1 manual page: Developing patches. (line 13)
+* gawk.pot file: GNU Tools. (line 27)
+* gawktexi.in documentation: Developing patches. (line 13)
+* GCC, the GNU Compiler Collection: Compilers. (line 6)
+* generating a single patch: Submitting Changes. (line 14)
+* generating multiple patches: Submitting Changes. (line 24)
+* gettext: GNU Tools. (line 27)
+* git add: Starting A New Branch.
+ (line 36)
+* git add <1>: Developing patches. (line 26)
+* git add <2>: Developing new features.
+ (line 24)
+* git add <3>: Developing new features.
+ (line 36)
+* git add <4>: Developing fixes. (line 10)
+* git branch: Repo Copies. (line 38)
+* git branch <1>: Removing Branches. (line 9)
+* git branch <2>: General practices. (line 88)
+* git branch <3>: Repo Maintenance. (line 20)
+* git branch command, -a option: Remotes. (line 6)
+* git checkout: Local Branches. (line 11)
+* git checkout <1>: Switching Branches. (line 9)
+* git checkout <2>: Starting A New Branch.
+ (line 10)
+* git checkout <3>: Undoing a change. (line 10)
+* git checkout <4>: Rebasing. (line 10)
+* git checkout <5>: Submitting Changes. (line 18)
+* git checkout <6>: Submitting Changes. (line 27)
+* git checkout <7>: Removing Branches. (line 9)
+* git checkout <8>: Points to remember. (line 19)
+* git checkout <9>: Points to remember. (line 32)
+* git checkout <10>: Points to remember. (line 37)
+* git checkout <11>: Developing new features.
+ (line 9)
+* git checkout <12>: Developing fixes. (line 10)
+* git checkout <13>: General practices. (line 43)
+* git checkout <14>: General practices. (line 60)
+* git checkout <15>: General practices. (line 73)
+* git clone: Repo Copies. (line 42)
+* git clone <1>: Cloning. (line 6)
+* git clone <2>: ssh clone. (line 10)
+* git command, --help option: Cheat Sheet. (line 10)
+* git commit: Starting A New Branch.
+ (line 49)
+* git commit <1>: Developing patches. (line 26)
+* git commit <2>: Developing new features.
+ (line 24)
+* git commit <3>: Developing new features.
+ (line 36)
+* git commit <4>: Developing fixes. (line 10)
+* git config: Configuring git. (line 11)
+* git diff: Starting A New Branch.
+ (line 29)
+* git diff <1>: Submitting Changes. (line 18)
+* git diff <2>: Points to remember. (line 32)
+* git diff <3>: Developing patches. (line 16)
+* git diff <4>: Developing patches. (line 26)
+* git diff <5>: Developing new features.
+ (line 24)
+* git diff <6>: Developing new features.
+ (line 36)
+* git diff <7>: Developing fixes. (line 10)
+* git difftool: Starting A New Branch.
+ (line 29)
+* git fetch: General practices. (line 94)
+* git fetch <1>: Repo Maintenance. (line 25)
+* git format-patch: Submitting Changes. (line 24)
+* git gc: Repo Maintenance. (line 33)
+* git help: Cheat Sheet. (line 10)
+* git log: Starting A New Branch.
+ (line 51)
+* git merge: Points to remember. (line 37)
+* git merge <1>: General practices. (line 60)
+* git merge <2>: General practices. (line 73)
+* Git Project: Preface. (line 10)
+* git pull: Cloning. (line 32)
+* git pull <1>: Switching Branches. (line 9)
+* git pull <2>: Rebasing. (line 10)
+* git pull <3>: Removing Branches. (line 9)
+* git pull <4>: Points to remember. (line 19)
+* git pull <5>: Points to remember. (line 37)
+* git pull <6>: Developing new features.
+ (line 9)
+* git pull <7>: Developing fixes. (line 10)
+* git pull <8>: Developing fixes. (line 19)
+* git pull <9>: General practices. (line 43)
+* git pull <10>: General practices. (line 60)
+* git pull <11>: General practices. (line 73)
+* git pull <12>: Repo Maintenance. (line 20)
+* git push: Local Branches. (line 16)
+* git push <1>: Developing patches. (line 26)
+* git push <2>: Developing new features.
+ (line 24)
+* git push <3>: Developing new features.
+ (line 36)
+* git push <4>: Developing fixes. (line 19)
+* git push <5>: General practices. (line 83)
+* git push <6>: General practices. (line 88)
+* git rebase: Rebasing. (line 10)
+* git rebase <1>: Points to remember. (line 25)
+* git rebase <2>: General practices. (line 43)
+* git reset: Undoing a change. (line 12)
+* git reset, --hard option: Cheat Sheet. (line 93)
+* git status: Starting A New Branch.
+ (line 23)
+* git status <1>: Starting A New Branch.
+ (line 41)
+* GitHub: Contributing. (line 57)
+* global configuration settings: Configuring git. (line 6)
+* GNU autoconf: GNU Tools. (line 15)
+* GNU automake: GNU Tools. (line 22)
+* GNU gettext: GNU Tools. (line 27)
+* GNU libtool: GNU Tools. (line 34)
+* GNU makeinfo: GNU Tools. (line 41)
+* GNU software tools: GNU Tools. (line 6)
+* GNU Texinfo: GNU Tools. (line 41)
+* Kahrs, Ju"rgen: Acknowledgments. (line 6)
+* libtool: GNU Tools. (line 34)
+* local branches: Local Branches. (line 6)
+* main branch: Repo State. (line 27)
+* Makefile.am file: GNU Tools. (line 22)
+* makeinfo: GNU Tools. (line 41)
+* master branch: Repo State. (line 27)
+* meld utility: Starting A New Branch.
+ (line 29)
+* merge conflicts: Merge Conflicts. (line 6)
+* old branches, removing: Repo Maintenance. (line 9)
+* origin/ branches: Repo Copies. (line 68)
+* ownership of directories: General practices. (line 17)
+* pager.status configuration setting: Configuring git. (line 24)
+* patch, single, generation of: Submitting Changes. (line 14)
+* patches, multiple, generation of: Submitting Changes. (line 24)
+* pcc compiler: Compilers. (line 40)
+* pcc compiler, Git mirror: Compilers. (line 50)
+* Portable C compiler: Compilers. (line 40)
+* Pro Git book: Resources. (line 6)
+* propagating fixes to other branches: General practices. (line 10)
+* purely local branches: Local State. (line 6)
+* push.default configuration setting: Configuring git. (line 24)
+* rebasing: Rebasing. (line 6)
+* removing branches: Removing Branches. (line 6)
+* removing cruft: Repo Maintenance. (line 27)
+* removing old branches: Repo Maintenance. (line 9)
+* renaming branches: Repo Maintenance. (line 44)
+* Repository, gawk, URL for: Cloning. (line 13)
+* Repository, gawk, URL for <1>: ssh clone. (line 10)
+* review, changes you made: Submitting Changes. (line 12)
+* Savannah, creating an account: Initial setup. (line 10)
+* Savannah, using Git guide: Resources. (line 10)
+* settings, configuration: Configuring git. (line 6)
+* software tools: Tools. (line 6)
+* ssh key: Initial setup. (line 10)
+* stable branches: Repo State. (line 15)
+* tcc compiler: Compilers. (line 22)
+* Texinfo: Conventions. (line 6)
+* Texinfo <1>: GNU Tools. (line 41)
+* Tiny C compiler: Compilers. (line 22)
+* tracking branches: Local Branches. (line 11)
+* URL, for cloning repositories: Cloning. (line 10)
+* URL, for gawk repository: Cloning. (line 13)
+* URL, for gawk repository <1>: ssh clone. (line 10)
+* user.email configuration setting: Configuring git. (line 16)
+* user.name configuration setting: Configuring git. (line 16)
+
+
+
+Tag Table:
+Node: Top1102
+Node: Preface5174
+Node: This Manual6070
+Node: Conventions7559
+Node: Acknowledgments9028
+Node: Reviewers9465
+Node: Contributing9786
+Ref: Contributing-Footnote-113141
+Node: Using Git13173
+Node: Push Pull13929
+Node: Repo Copies15344
+Ref: savannah-repo16327
+Ref: your-repo17360
+Ref: Repo Copies-Footnote-119054
+Node: Local Branches19111
+Ref: your-repo-220889
+Ref: Local Branches-Footnote-121970
+Node: Branches are state22028
+Node: Repo State22751
+Node: Local State24871
+Node: Remotes25535
+Node: Configuring git26850
+Ref: Configuring git-Footnote-129203
+Node: Development without commit access29372
+Node: Cloning30374
+Node: Switching Branches32233
+Node: Starting A New Branch32886
+Ref: Starting A New Branch-Footnote-134774
+Ref: Starting A New Branch-Footnote-234832
+Node: Undoing a change34908
+Node: Updating35509
+Node: Rebasing36011
+Node: Merge Conflicts36623
+Node: Submitting Changes38123
+Ref: Submitting Changes-Footnote-140267
+Ref: Submitting Changes-Footnote-240304
+Ref: Submitting Changes-Footnote-340340
+Node: Removing Branches40386
+Node: Points to remember40922
+Node: Development with commit access42599
+Node: Initial setup43244
+Node: ssh clone44032
+Node: Developing patches44629
+Node: Developing new features45965
+Node: Developing fixes47869
+Node: General practices48956
+Node: Repo Maintenance53686
+Ref: Repo Maintenance-Footnote-156455
+Node: Development Stuff56588
+Node: Coding style57151
+Ref: Coding style-Footnote-157809
+Node: Doing paperwork57899
+Node: Tools58694
+Node: GNU Tools59276
+Node: Compilers61437
+Ref: Compilers-Footnote-163931
+Node: Debugging63969
+Node: Cheat Sheet64675
+Node: Resources68356
+Node: TODO68799
+Node: Index69019
+
+End Tag Table
diff --git a/doc/gawkworkflow.texi b/doc/gawkworkflow.texi
new file mode 100755
index 0000000..4d9ddd0
--- /dev/null
+++ b/doc/gawkworkflow.texi
@@ -0,0 +1,2158 @@
+\input texinfo @c -*-texinfo-*-
address@hidden vim: filetype=texinfo expandtab tabstop=4 shiftwidth=4
address@hidden %**start of header (This is for running Texinfo on a region.)
address@hidden gawkworkflow.info
address@hidden GNU Awk Development Workflow
address@hidden %**end of header (This is for running Texinfo on a region.)
+
address@hidden Text creation and manipulation
address@hidden
+* Gawk Work Flow: (gawkworkflow). Participating in
@command{gawk} development.
address@hidden direntry
address@hidden Individual utilities
address@hidden
+* Gawk Work Flow: (gawkworkflow)Overview. Participating in
@command{gawk} development.
address@hidden direntry
+
address@hidden With early 2014 texinfo.tex, restore PDF links and colors
address@hidden
+\gdef\linkcolor{0.5 0.09 0.12} % Dark Red
+\gdef\urlcolor{0.5 0.09 0.12} % Also
+\global\urefurlonlylinktrue
address@hidden tex
+
address@hidden xref-automatic-section-title
+
address@hidden The following information should be updated here only!
address@hidden This sets the edition of the document, the version of gawk it
address@hidden applies to and all the info about who's publishing this edition
+
address@hidden These apply across the board.
address@hidden UPDATE-MONTH April, 2017
+
address@hidden TITLE Participating in @command{gawk} Development
address@hidden EDITION 0.7
+
address@hidden
address@hidden DOCUMENT booklet
address@hidden CHAPTER chapter
address@hidden APPENDIX appendix
address@hidden SECTION section
address@hidden SUBSECTION subsection
address@hidden iftex
address@hidden
address@hidden DOCUMENT Info file
address@hidden CHAPTER major node
address@hidden APPENDIX major node
address@hidden SECTION minor node
address@hidden SUBSECTION node
address@hidden ifinfo
address@hidden
address@hidden DOCUMENT Web page
address@hidden CHAPTER chapter
address@hidden APPENDIX appendix
address@hidden SECTION section
address@hidden SUBSECTION subsection
address@hidden ifhtml
address@hidden
address@hidden DOCUMENT booklet
address@hidden CHAPTER chapter
address@hidden APPENDIX appendix
address@hidden SECTION section
address@hidden SUBSECTION subsection
address@hidden ifdocbook
address@hidden
address@hidden DOCUMENT booklet
address@hidden CHAPTER chapter
address@hidden APPENDIX appendix
address@hidden SECTION section
address@hidden SUBSECTION subsection
address@hidden ifxml
address@hidden
address@hidden DOCUMENT booklet
address@hidden CHAPTER chapter
address@hidden APPENDIX appendix
address@hidden SECTION section
address@hidden SUBSECTION subsection
address@hidden ifplaintext
+
+
address@hidden
address@hidden
address@hidden ii{text}
address@hidden
address@hidden macro
address@hidden ifnotdocbook
address@hidden ifnottex
+
address@hidden
address@hidden ii{text}
address@hidden,<lineannotation>\text\</lineannotation>}
address@hidden macro
address@hidden ifdocbook
+
address@hidden For HTML, spell out email addresses, to avoid problems with
address@hidden address harvesters for spammers.
address@hidden
address@hidden EMAIL{real,spelled}
+``\spelled\''
address@hidden macro
address@hidden ifhtml
address@hidden
address@hidden EMAIL{real,spelled}
address@hidden
address@hidden macro
address@hidden ifnothtml
+
+
address@hidden merge the function and variable indexes into the concept index
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden ifinfo
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden iftex
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden ifxml
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden ifdocbook
+
address@hidden If "finalout" is commented out, the printed output will show
address@hidden black boxes that mark lines that are too long. Thus, it is
address@hidden unwise to comment it out when running a master in case there are
address@hidden overfulls which are deemed okay.
+
address@hidden
address@hidden
address@hidden iftex
+
address@hidden
address@hidden
+<para>Published by:</para>
+
+<literallayout class="normal">Free Software Foundation
+51 Franklin Street, Fifth Floor
+Boston, MA 02110-1301 USA
+Phone: +1-617-542-5942
+Fax: +1-617-542-2652
+Email: <email>gnu@@gnu.org</email>
+URL: <ulink
url="http://www.gnu.org";>http://www.gnu.org/</ulink></literallayout>
+
+<literallayout class="normal">Copyright © 2017
+Free Software Foundation, Inc.
+All Rights Reserved.</literallayout>
address@hidden docbook
+
address@hidden
+Copyright @copyright{} 2017
+Free Software Foundation, Inc.
address@hidden ifnotdocbook
address@hidden 2
+
+This is Edition @value{EDITION} of @address@hidden
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', with the
+Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
+as in (a) below.
+A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+
address@hidden a
address@hidden
+The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.''
address@hidden enumerate
address@hidden copying
+
address@hidden Comment out the "smallbook" for technical review. Saves
address@hidden considerable paper. Remember to turn it back on *before*
address@hidden starting the page-breaking work.
+
address@hidden 4/2002: Karl Berry recommends commenting out this and the
address@hidden address@hidden odd', and letting users use `texi2dvi -t'
address@hidden if they want to waste paper.
address@hidden @smallbook
+
+
address@hidden Uncomment this for the release. Leaving it off saves paper
address@hidden during editing and review.
address@hidden @setchapternewpage odd
+
address@hidden @shorttitlepage @value{TITLE}
address@hidden
address@hidden @value{TITLE}
address@hidden Edition @value{EDITION}
address@hidden @value{UPDATE-MONTH}
address@hidden Arnold D. Robbins
+
address@hidden
address@hidden Include the Distribution inside the titlepage environment so
address@hidden that headings are turned off. Headings on and off do not work.
+
address@hidden
address@hidden 0pt plus 1filll
+Published by:
address@hidden 1
+
+Free Software Foundation @*
+51 Franklin Street, Fifth Floor @*
+Boston, MA 02110-1301 USA @*
+Phone: +1-617-542-5942 @*
+Fax: +1-617-542-2652 @*
+Email: @email{gnu@@gnu.org} @*
+URL: @uref{http://www.gnu.org/} @*
+
address@hidden ISBN x-xxxxxx-xx-x @*
address@hidden 2
address@hidden
address@hidden ifnotdocbook
address@hidden titlepage
+
address@hidden
address@hidden off
address@hidden @thispage@ @ @ @address@hidden @| @|
address@hidden @| @| @address@hidden@ @ @ @thispage
address@hidden iftex
+
address@hidden
address@hidden
address@hidden
address@hidden Top
address@hidden General Introduction
address@hidden Preface node should come right after the Top
address@hidden node, in `unnumbered' sections, then the first chapter.
+
+This file describes how to participate in software development for
address@hidden://www.gnu.org/software/gawk, GNU Awk (@command{gawk})}.
+
address@hidden
+
address@hidden ifnotdocbook
address@hidden ifnotxml
address@hidden ifnottex
+
address@hidden
+* Preface:: Some introductory remarks.
+* Contributing:: How to contribute to @command{gawk}
+ development.
+* Using Git:: Getting started with Git.
+* Configuring git:: Configuring Git.
+* Development without commit access:: How to wwork without commit access.
+* Development with commit access:: How to work with commit access.
+* General practices:: How things should usually be done.
+* Repo Maintenance:: Tips for keeping your repo clean.
+* Development Stuff:: Things you need to know to be a
+ @command{gawk} developer.
+* Cheat Sheet:: Git command summary.
+* Resources:: Some further resources.
+* TODO:: Stuff still to do.
+* Index:: The index.
+
address@hidden
+* This Manual:: How to use this manual.
+* Conventions:: Typographical Conventions.
+* Acknowledgments:: Acknowledgments.
+* Reviewers:: A note to reviewers.
+* Push Pull:: The push/pull software development model.
+* Repo Copies:: What it means to have a copy of a repo.
+* Local Branches:: How to best use local branches.
+* Branches are state:: Branches represent development state.
+* Repo State:: The different branch types in the repo.
+* Local State:: Managing local branches.
+* Remotes:: What a ``remote'' is.
+* Cloning:: Cloning the repo the first time.
+* Switching Branches:: Moving from one branch to another.
+* Starting A New Branch:: Starting a new branch for development.
+* Undoing a change:: Throwing away changes.
+* Updating:: Keeping in sync with the upstream repo.
+* Rebasing:: Rebasing A Local Branch.
+* Merge Conflicts:: Dealing With Merge Conflicts.
+* Submitting Changes:: How to submit your changes.
+* Removing Branches:: Getting rid of unneeded branches.
+* Points to remember:: Things you need to keep in mind.
+* Initial setup:: Getting started with commit access.
+* ssh clone:: Cloning using an @samp{ssh://} URL.
+* Developing patches:: Developing patches.
+* Developing new features:: Developing new features.
+* Developing fixes:: Developing fixes.
+* Coding style:: Where to read up on the coding style.
+* Doing paperwork:: Legal stuff in order to contribute.
+* Tools:: Tools to have on your system for
+ development.
+* GNU Tools:: The GNU Autotools.
+* Compilers:: A discussion of compilers that can be
+ used.
+* Debugging:: Compiling for debugging.
address@hidden detailmenu
address@hidden menu
+
address@hidden @summarycontents
address@hidden
+
address@hidden Preface
address@hidden Preface
address@hidden I saw a comment somewhere that the preface should describe the
book itself,
address@hidden and the introduction should describe what the book covers.
+
+This @value{DOCUMENT} describes how to participate in development
+of GNU Awk (@command{gawk}). GNU Awk is a Free Software project
+belonging to the Free Software Foundation's GNU project.
+
address@hidden Git Project
+The @value{DOCUMENT} focuses on participation in the project (that is,
+how to work most effectively if you wish to contribute to it) and
+also describes how to make use of the @uref{http://git-scm.org, Git}
+distributed source code management system for @command{gawk} development.
+
+You should be comfortable working with traditional UNIX-style
+tools and with the C language and standard library facilities.
+
address@hidden
+* This Manual:: How to use this manual.
+* Conventions:: Typographical Conventions.
+* Acknowledgments:: Acknowledgments.
+* Reviewers:: A note to reviewers.
address@hidden menu
+
+
address@hidden This Manual
address@hidden Using This Book
+
+This @value{DOCUMENT} has the following chapters and appendices:
+
address@hidden @bullet
+
address@hidden
address@hidden describes how to start contributing to
+the @command{gawk} project.
+
address@hidden
address@hidden Git} introduces the Git distributed source code
+management system.
+
address@hidden
address@hidden git} describes some initial set-up you need to do
+before using Git seriously.
+
address@hidden
address@hidden without commit access} gets into the meat of the
+development workflow, describing how to work if you don't have
+commit access to the Savannah repository.
+
address@hidden
address@hidden with commit access} continues the discussion,
+covering what's different when you can commit directly to the
+Savannah repository.
+
address@hidden
address@hidden practices} describes general development
+practices used by the @command{gawk} development team.
+
address@hidden
address@hidden Maintenance} presents several different things
+you need to know about to keep your repo in good shape.
+
address@hidden
address@hidden Stuff} describes some important points you
+should be familiar with in order to participate in @command{gawk}
+development and presents some tools that may make your work easier.
+
address@hidden
address@hidden Sheet} provides a short ``cheat sheet'' summarizing
+all the Git commands referenced in this @value{DOCUMENT}.
+
address@hidden
address@hidden provides a few pointers to Internet
+resources for learning more about Git.
+
address@hidden itemize
+
address@hidden Conventions
address@hidden Typographical Conventions
+
address@hidden Texinfo
+This @value{DOCUMENT} is written in
@uref{http://www.gnu.org/software/texinfo/, Texinfo},
+the GNU documentation formatting language.
+A single Texinfo source file is used to produce both the printed and online
+versions of the documentation.
address@hidden
+Because of this, the typographical conventions
+are slightly different than in other books you may have read.
address@hidden ifnotinfo
address@hidden
+This @value{SECTION} briefly documents the typographical conventions used in
Texinfo.
address@hidden ifinfo
+
+Examples you would type at the command line are preceded by the common
+shell primary and secondary prompts, @samp{$} and @samp{>}.
+Input that you type is shown @kbd{like this}.
+Output from the command is preceded by the glyph address@hidden''.
+This typically represents the command's standard output.
+Error messages and other output on the command's standard error are preceded
+by the glyph address@hidden''. For example:
+
address@hidden
+$ @kbd{echo hi on stdout}
address@hidden hi on stdout
+$ @kbd{echo hello on stderr 1>&2}
address@hidden hello on stderr
address@hidden example
+
address@hidden
+In the text, almost anything related to programming, such as command
+names, variable and function names, and string, numeric and regexp
+constants appear in @code{this font}. Code fragments appear in the same
+font and quoted, @samp{like this}. Things that are replaced by the
+user or programmer appear in @var{this font}. Options look like this:
address@hidden File names are indicated like this: @file{/path/to/ourfile}.
+Some things are emphasized @emph{like this}, and if a point needs to be
+made strongly, it is done @strong{like this}. The first occurrence of
+a new term is usually its @dfn{definition} and appears in the same font
+as the previous occurrence of ``definition'' in this sentence.
address@hidden ifnotinfo
+
+Characters that you type at the keyboard look @kbd{like this}. In particular,
+there are special characters called ``control characters.'' These are
+characters that you type by holding down both the @kbd{CONTROL} key and
+another key, at the same time. For example, a @kbd{Ctrl-d} is typed
+by first pressing and holding the @kbd{CONTROL} key, next
+pressing the @kbd{d} key, and finally releasing both keys.
+
address@hidden NOTE
+Notes of interest look like this.
address@hidden quotation
+
address@hidden CAUTION
+Cautionary or warning notes look like this.
address@hidden quotation
+
address@hidden Acknowledgments
address@hidden Acknowledgments
+
address@hidden Kahrs, J@"urgen
+Thanks to J@"urgen Kahrs for his initial efforts to write a document like this.
+Although his prose has not survived, his material was helpful in preparing
+this @value{DOCUMENT}.
+
address@hidden Bernat, Yehezkel
+Thanks to Yehezkel Bernat for reviewing this document and
+in general for his good intentions.
+
address@hidden:} YOUR NAME HERE...
+
address@hidden Reviewers
address@hidden Notes to Reviewers
+
+Please let me know if anything is missing, or unclear.
+Real errors with respect Git commands and usage are
+very important as well.
+
+Spelling errors and typo fixes welcome, but not as important.
+
address@hidden Contributing
address@hidden How to Start Contributing
+
address@hidden development is distributed. It's done using electronic
+mail (email) and via branches in the Git address@hidden for
+``repository''.} on @uref{http://savannah.gnu.org, Savannah}, the GNU
+project's source code management site.
+
+In this @value{CHAPTER} we use some Git terminology. If you're not at
+all familiar with Git, then skim this @value{CHAPTER} and come back
+after reading the rest of the @value{DOCUMENT}.
+
address@hidden is similar to many other Free Software projects. To begin
+contributing, simply start! Take a look at the @file{TODO} file in the
+distribution, see if there is something of interest to you, and ask on
+the @email{bug-gawk@@gnu.org} mailing list if anyone else is working
+on it. If not, then go for it! (@xref{Development Stuff} for a discussion of
some
+of the technical things you'll need to do. Here we describe the process
+in general.)
+
+Your contribution can be almost anything that is relevant for
address@hidden, such as code fixes, documentation fixes, and/or new
+features.
+
address@hidden NOTE
+If possible, new features should be done using @command{gawk}'s extension
+mechanism. If you want to add a user-visible language change to the
address@hidden core, you're going to have to convince the maintainer
+and other developers that it's really worthwile to do so.
+
+Changes that improve performance or portability, or that fix bugs,
+or that enable more things in extensions,
+will require less convincing, of course.
address@hidden quotation
+
+As you complete a task, submit patches for review to the
address@hidden@@gnu.org} mailing list, where you'll be given feedback
+about your work. Once your changes are acceptable, the maintainer will
+commit them to the Git repository.
+
+Over time, as the maintainer and development team gain confidence in your
+ability to contribute, you may be asked to join the private @command{gawk}
+developers' mailing list, and/or be granted commit access to the Git
+repository on Savannah. This has happened to more than one person who
+just ``came out of the woodwork.''
+
+Until that happens, or if you don't want to join the list, you should
+continue to work with private branches and submission of patches to the
+mailing list.
+
+Once you have commit access, if you want to make a major change or add a
+major feature, where the patch(es) would be very large, it has become the
+practice to create a separate branch, based off of @code{master}, to host
+the feature. This way the maintainer can review it, and you can continue
+to improve it, until it's ready for integration into @code{master}.
+
address@hidden GitHub
address@hidden NOTE
+Because of the GNU project's requirements for signed paperwork for
+contributions, the @command{gawk} project will @strong{not} work
+with pull requests from @uref{http://github.com, GitHub} or any other
+Git-based software hosting service. You must submit patches to the
+mailing list, and be willing to sign paperwork for large patches.
address@hidden quotation
+
+The @email{bug-gawk@@gnu.org} mailing list is not private. Anyone may
+send mail to it, and anyone may subscribe to it. To subscribe,
+go to the list's @uref{https://lists.gnu.org/mailman/listinfo/bug-gawk,
+web page} and follow the instructions there. If you plan to be involved
+long-term with @command{gawk} development, then you probably should
+subscribe to the list.
+
address@hidden Using Git
address@hidden Using Git
+
+This chapter provides an introduction to using Git. Our point is
address@hidden to rave about how wonderful Git is, nor to go into painful
+detail about how it works. Rather we want to give you enough background
+to understand how to use Git effectively for bug fix and feature
+development and to interact (``play nicely'') with the development team.
+
address@hidden
+* Push Pull:: The push/pull software development model.
+* Repo Copies:: What it means to have a copy of a repo.
+* Local Branches:: How to best use local branches.
+* Branches are state:: Branches represent development state.
address@hidden menu
+
address@hidden Push Pull
address@hidden The ``Push/Pull'' Model of Software Development
+
+Git is a powerful, distributed source code management system. However,
+the way it's used for @command{gawk} development purposely does not take
+advantage of all its features.
+
+Instead, the model is rather simple, and in many ways much like more
+traditional distributed systems such as the @uref{http://www.nongnu.org/cvs,
+Concurrent Versions System} (CVS) or
address@hidden://subversion.apache.org, Subversion} (SVN).
+
+The central idea can be termed ``push/pull.'' You @emph{pull} updates down from
+the central repository to your local copy, and if you have commit rights,
+you @emph{push} your changes or updates up to the central repository.
+
+Where Git does stand out is in its management of multiple branches of
+development. Git makes it very easy to set up a separate branch for
+use in fixing a bug or developing a feature. You can then easily keep
+that branch up to date with respect to the main development branch(es),
+and eventually merge the changes from your branch into the main branch.
+
+Almost always Git does these merges for you without problem. When there
+is a problem (a @dfn{merge conflict}), usually it is very easy for you
+to @dfn{resolve} them and then complete the merge. We talk about this
+in more detail later (@pxref{Merge Conflicts}).
+
address@hidden Repo Copies
address@hidden How Git Stores Branches and Their Copies
+
+So how does Git address@hidden following description is greatly
+simplified.}
+
+A repository consists of a collection of @dfn{branches}. Each branch
+represents the history of a collection of files and directories (a file
address@hidden). Each combined set of changes to this collection (files and
+directories added or deleted, and/or file contents changed) is termed
+a @dfn{commit}.
+
+When you first create a local copy of a remote repository (``clone
+the repo''), Git copies all of the original repository's branches to
+your local system. The original remote repository is referred to as
+being @dfn{upstream}, and your local repo is @dfn{downstream} from it.
+Git distinguishes branches from the upstream repo by prefixing their
+names with @samp{origin/}. Let's draw some pictures. @ref{savannah-repo}
+represents the state of the repo on Savannah:
+
address@hidden
address@hidden Figure,savannah-repo
address@hidden Savannah @command{gawk} Repository}
address@hidden
++======================+
+| Branches |
++======================+
+| master |
++----------------------+
+| gawk-4.1-stable |
++----------------------+
+| gawk-4.0-stable |
++----------------------+
+| feature/fix-comments |
++----------------------+
+| ... |
++----------------------+
address@hidden smallexample
address@hidden float
+
address@hidden @code{git branch}
+After you clone the repo, on your local system you will have a single
+branch named @code{master} that's visible when you use @samp{git branch}
+to see your branches.
+
address@hidden @code{git clone}
address@hidden
+$ @kbd{git clone http://git.savannah.gnu.org/r/gawk.git} @ii{Clone the repo}
+$ @kbd{cd gawk} @ii{Change to local
copy}
+$ @kbd{git branch} @ii{See branch
information}
address@hidden * master
address@hidden example
+
address@hidden
+The current branch is always indicated with a leading asterisk (@samp{*}).
+
+Pictorially, the local repo looks like @ref{your-repo} (you can ignore
+the @samp{T} column for the moment):
+
address@hidden Figure,your-repo
address@hidden Local @command{gawk} Repository}
address@hidden
++===+======================++=============================+
+| T | Local Branches || Remote Branches |
++===+======================++=============================+
+| X | master || origin/master |
++---+----------------------++-----------------------------+
+| | || origin/gawk-4.1-stable |
++---+----------------------++-----------------------------+
+| | || origin/gawk-4.0-stable |
++---+----------------------++-----------------------------+
+| | || origin/feature/fix-comments |
++---+----------------------++-----------------------------+
+| | || ... |
++---+----------------------++-----------------------------+
address@hidden smallexample
address@hidden float
+
address@hidden
address@hidden @code{origin/} branches
address@hidden branches, @code{origin/}
+Note that what is simply @code{gawk-4.1-stable} in the upstream repo
+is now referred to as @code{origin/gawk-4.1-stable}. The @samp{origin/}
+branches are a snapshot of the state of the upstream repo. This is
+how Git allows you to see what changes you've made with respect to the
+upstream repo, without having to actually communicate with the upstream
+repo over the Internet. (When files are identical, Git is smart enough
+to not have two separate physical copies on your local disk.)
+
+If you're working on a simple bug fix or change, you can do so directly
+in your local @code{master} branch. You can then commit your changes,
+and if you have access rights, push them upstream to the Savannah repo.
+(However, there is a process to follow. Please read the rest of
+this @value{DOCUMENT}.)
+
address@hidden Local Branches
address@hidden Local Branches
+
address@hidden local branches
address@hidden branches, local
+Let's talk about local branches in more detail. (The terminology used
+here is my own, not official Git jargon.) There are two kinds of local
+branches:
+
address@hidden @dfn
address@hidden Tracking Branches
address@hidden tracking branches
address@hidden branches, tracking
address@hidden @code{git checkout}
+Tracking branches track branches from the upstream repository. You first
+create a tracking branch simply by checking out a branch from the
+upstream. You use the branch name without the leading @samp{origin/}
+prefix. For example, @samp{git checkout gawk-4.1-stable}.
+
address@hidden @code{git push}
+You can then work on this branch, making commitments to it as you wish.
+Once things are ready to move upstream, you simply use @samp{git push},
+and your changes will be pushed up to the main address@hidden
+you have permission to do so, of course.}
+
+You should @strong{never} checkout a branch using the @samp{origin/}
+prefix. Things will get very confused. Always work on local tracking
+branches.
+
address@hidden Purely Local Branches
+A @dfn{purely local branch} exists only on your system. You may be developing
+some large new feature, or fixing a very difficult bug, or have a change
+for which paperwork has not yet been completed.
+
+In such a case, you would keep your changes on a local branch, and
+periodically synchronize it with @code{master} (or whichever upstream
+branch you started from).
address@hidden table
+
+This may seem somewhat abstract so far. We demonstrate with commands
+and branches in @ref{Development without commit access},
+later in this @value{DOCUMENT}.
+
+Let's say you have checked out a copy of @code{gawk-4.1-stable} and
+have created a purely local branch named @code{better-random}. Then
+our picture now looks like @ref{your-repo-2}, where the @samp{T} column
+indicates a tracking branch.
+
address@hidden Figure,your-repo-2
address@hidden Local @command{gawk} Repository With a Purely Local Branch}
address@hidden
++===+======================++=============================+
+| T | Local Branches || Remote Branches |
++===+======================++=============================+
+| X | master || origin/master |
++---+----------------------++-----------------------------+
+| X | gawk-4.1-stable || origin/gawk-4.1-stable |
++---+----------------------++-----------------------------+
+| | || origin/gawk-4.0-stable |
++---+----------------------++-----------------------------+
+| | || origin/feature/fix-comments |
++---+----------------------++-----------------------------+
+| | || ... |
++---+----------------------++-----------------------------+
+| | better-random || |
++---+----------------------++-----------------------------+
address@hidden smallexample
address@hidden float
+
address@hidden Branches are state
address@hidden Branches Represent Development State
+
+Branches represent development state. At any given time, when you
+checkout a particular branch (or create a new one), you have a copy
+of the @command{gawk} source tree that you should be able to build
+and test.
+
+The following @value{SECTION}s describe the different branches
+in the @command{gawk} repository and what they are for, as well
+as how to use your own branches.
+
address@hidden
+* Repo State:: The different branch types in the repo.
+* Local State:: Managing local branches.
+* Remotes:: What a ``remote'' is.
address@hidden menu
+
address@hidden Repo State
address@hidden Branches in the Savannah Repository
+
+There are several kinds of branches in the Savannah repository.
+
address@hidden @dfn
address@hidden branches, dead
address@hidden dead branches
address@hidden Dead Branches
+Branches with the prefix @samp{dead-branches/} (such as
address@hidden/const}) hold code that was never merged into the
+main code base. For example, a feature which was started, but later
+deemed to be unwise to add. These branches keep the code available,
+but they are not updated.
+
address@hidden branches, stable
address@hidden stable branches
address@hidden Stable Branches
+These branches are used for bug fixes to released versions
+of @command{gawk}. Sometimes new development (i.e., user-visible
+changes) also occurs on these branches, although in a perfect world
+they would be used only for bug fixes.
+
+These branches have names like @code{gawk-4.1-stable},
address@hidden, and so on. Once a release has been made from
address@hidden, the previous stable branch is not updated. For example,
+once @command{gawk} 4.1.0 was released, no more work was done on
address@hidden
+
address@hidden branch, main
address@hidden main branch
address@hidden branch, @code{master}
address@hidden @code{master} branch
address@hidden The Main Branch
+This is the @code{master} branch. Here is where most new feature
+development takes place, and releases of new major versions are based
+off of this branch.
+
+Feature branches are typically based off this branch as well, and when
+the feature is deemed complete, merged back into it.
+
address@hidden branches, feature
address@hidden feature branches
address@hidden Feature Branches
+Often, a proposed new feature or code improvement is quite involved.
+It may take some time to perfect, or the @command{gawk} development team
+may not be convinced that the feature should be kept.
+
+For this purpose, the team uses branches prefixed with @samp{feature/}.
+This prefix is used even for code that simply improves the internals
+and does not make a user-visible change.
+
+Having large changes on separate branches makes it easier for members
+of the team to review the code, and also makes it easier to keep the
+changes up-to-date with respect to @code{master}, since Git excels at
+merging commits from one branch to another.
address@hidden table
+
address@hidden Local State
address@hidden Branches in Your Local Repository
+
address@hidden branches, purely local
address@hidden purely local branches
+Purely local branches are where you do your own development.
+You may use purely local branches because you don't have commit rights
+to the Savannah repo. You may also use them if you are doing some work
+that isn't ready for sharing with the rest of the team, or cannot be
+committed for some other reason.
+
+For example, for around a nine-month period, the maintainer kept a
+purely local branch for some contributed changes for which paperwork had
+not yet been completed.
+
address@hidden Remotes
address@hidden A Closer Look at Branch Naming
+
address@hidden @command{git branch} command, @option{-a} option
+Earlier, we said that Git maintains copies of the branches
+in the upstream repo, as well as manages your local branches.
+You can see all these branches with @samp{git branch -a}:
+
address@hidden
+$ @kbd{git branch -a}
address@hidden gawk-4.1-stable
address@hidden * master
address@hidden remotes/origin/HEAD -> origin/master
address@hidden remotes/origin/dead-branches/async-events
address@hidden @dots{}
address@hidden remotes/origin/feature/api-mpfr
address@hidden remotes/origin/feature/array-iface
address@hidden remotes/origin/feature/fix-comments
address@hidden @dots{}
address@hidden example
+
+You'll note that what we've referred to as @samp{origin/} branches
+appear in the output with an additional prefix: @samp{remotes/}.
+Up to this point, we've treated Git as if it allowed only a singled
+upstream repository. But in fact, you can configure it to use more
+than one. All the known upstream repositories are grouped under
+the @samp{remotes/} prefix, with @code{remotes/origin} being the one
+from which you initially cloned your local repository.
+
+The ability to work with multiple upstream repositories is an
+advanced one; @command{gawk} development does not make use of it.
+The intent of this @value{SUBSECTION} is to explain the output
+from @samp{git branch -a}, nothing more.
+
address@hidden Configuring git
address@hidden Configuring Global Settings For Git
+
address@hidden configuration settings
address@hidden settings, configuration
address@hidden global configuration settings
address@hidden configuration settings, global
+Before starting to use Git, you should configure it with some important
+settings that won't change as you use Git. You may configure options
+both globally, and on a per-repository basis. Here, we discuss only
+global configuration settings.
+
address@hidden @code{git config}
+You can configure Git using either @samp{git config}, or by editing
+the relevant files with your favorite text address@hidden are
+required to use either Vim or Emacs, other text editors are not
+allowed. Of course, reasonable developers wouldn't want to use
+any other editor anyway.}
+
address@hidden email address
+The first things to set are your email address and your real name:
+
address@hidden @code{user.name} configuration setting
address@hidden @code{user.email} configuration setting
address@hidden configuration setting, @code{user.name}
address@hidden configuration setting, @code{user.email}
address@hidden
+$ @kbd{git config --global user.name "J.P. Developer"} @ii{Set full name}
+$ @kbd{git config --global user.email jpdev@@example.com} @ii{Set email
address}
address@hidden example
+
+Setting these two items are an absolute requirement.
address@hidden: No aliases are allowed. If you can't supply your
+real name, you cannot contribute to the project. Other options that
+the @command{gawk} maintainer recommends that you use are:
+
address@hidden @code{push.default} configuration setting
address@hidden @code{pager.status} configuration setting
address@hidden configuration setting, @code{push.default}
address@hidden configuration setting, @code{pager.status}
address@hidden
+$ @kbd{git config --global push.default=simple} @ii{Only push current
branch}
+$ @kbd{git config --global pager.status=true} @ii{Use pager for output
of} git status
address@hidden example
+
address@hidden @file{.gitconfig} file
+The global settings are stored in the @file{.gitconfig} file in your
+home directory. The file looks like this:
+
address@hidden
+[user]
+ name = J.P. Developer
+ email = jpdev@@example.com
+[push]
+ default = simple
+[pager]
+ status = true
address@hidden example
+
+The @code{push.default=simple} setting ensures that older
+versions of Git only push the current branch up to the Savannah
+repo. This is the safest way to operate, and is the default
+in current Git versions.
+
+There may be other settings in your configuration file as well.
+Use @samp{git config} to see your settings:
+
address@hidden
+$ @kbd{git config --list}
address@hidden user.name=J.P. Developer
address@hidden user.email=jpdev@@example.com
address@hidden push.default=simple
address@hidden example
+
+Here are the @command{gawk} maintainer's settings:
+
address@hidden
+$ @kbd{git config --global --list}
address@hidden user.name=Arnold D. Robbins
address@hidden user.email=arnold@@@dots{}
address@hidden credential.helper=cache --timeout=3600
address@hidden push.default=simple
address@hidden color.ui=false
address@hidden core.autocrlf=input
address@hidden pager.status=true
address@hidden log.decorate=auto
address@hidden example
+
+Additional, per-project (``local'') settings are stored in
+each repo's @file{.git/config} file.
+
address@hidden Development without commit access
address@hidden Development Without Commit Access
+
+In this chapter we present step-by-step recipes for checking out
+and working with a local
+copy of the Savannah Git repo for @command{gawk}.
+The presentation is for when you do not have commit access
+to the Git repo, and so you cannot push your changes directly.
+
address@hidden
+* Cloning:: Cloning the repo the first time.
+* Switching Branches:: Moving from one branch to another.
+* Starting A New Branch:: Starting a new branch for development.
+* Undoing a change:: Throwing away changes.
+* Updating:: Keeping in sync with the upstream repo.
+* Submitting Changes:: How to submit your changes.
+* Removing Branches:: Getting rid of unneeded branches.
+* Points to remember:: Things you need to keep in mind.
address@hidden menu
+
address@hidden Cloning
address@hidden Cloning The Repo
+
address@hidden @code{git clone}
+Clone the Savannah repo using @samp{git clone}. You may do so using
+either the native Git protocol, or using HTTP if you must go through a
+gateway or firewall that won't pass the Git protocol.
+
address@hidden URL, for cloning repositories
+To choose which method, you supply a @dfn{URL} for the repo when you
+clone it, as follows.
+
address@hidden URL, for @command{gawk} repository
address@hidden Repository, @command{gawk}, URL for
address@hidden @bullet
address@hidden
+Clone via the Git native protocol:
+
address@hidden
+$ @kbd{git clone git://git.savannah.gnu.org/gawk.git} @ii{Clone the repo}
address@hidden ...
+$ @kbd{cd gawk} @ii{Start working}
address@hidden example
+
+This will be faster, but not all firewalls pass the Git protocol
+on through.
+
address@hidden
+Clone via the HTTP protocol:
+
address@hidden
+$ @kbd{git clone http://git.savannah.gnu.org/r/gawk.git} @ii{Clone the repo}
address@hidden ...
+$ @kbd{cd gawk} @ii{Start working}
address@hidden example
address@hidden itemize
+
address@hidden only need to clone the repo once.} From then on, you update its
+contents using other Git commands. For example, after coming back from
+your vacation in the Bahamas:
+
address@hidden @code{git pull}
address@hidden
+$ @kbd{cd gawk} @ii{Move to the repo}
+$ @kbd{make distclean} @ii{A good idea before updating}
address@hidden ...
+$ @kbd{git pull} @ii{Update it}
address@hidden example
+
+To build, you should generally follow this recipe:
+
address@hidden
+$ @kbd{./bootstrap.sh && ./configure && make -j && make check}
address@hidden example
+
address@hidden @file{bootstrap.sh} script
address@hidden NOTE
+Unless you have installed all the tools described in @ref{GNU Tools},
+you @emph{must} run @command{./bootstrap.sh} every time you clone a repo,
+do a @samp{git pull} or checkout a different branch. (In the latter case,
+do @samp{make distclean} first.) Otherwise things will get messy very
+quickly. The @command{bootstrap.sh} script ensures that all of the file
+time stamps are up to date so that it's not necessary to run the various
+configuration tools.
address@hidden quotation
+
address@hidden Switching Branches
address@hidden Switching Branches
+
+So far, we've been working in the default @code{master} branch.
+Let's check what's happening in the @code{gawk-4.1-stable} branch:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden
+$ @kbd{make distclean} @ii{Clean up}
+$ @kbd{git checkout gawk-4.1-stable} @ii{Checkout a
different branch}
address@hidden ...
+$ @kbd{git pull} @ii{Get up to
date}
address@hidden ...
+$ @kbd{./bootstrap.sh && ./configure && make -j && make check} @ii{Start
working}
address@hidden example
+
address@hidden Starting A New Branch
address@hidden Starting A New Branch
+
+Let's say you want to work on a new feature. For example,
+you might decide to add Python syntax address@hidden joking.
+Please don't attempt this for real.} You should create a
+new branch on which to work. First, switch back to @code{master}:
+
address@hidden @code{git checkout}
address@hidden
+$ @kbd{make distclean}
+$ @kbd{git checkout master}
address@hidden example
+
+Now, create a new branch. The easiest way to do that is
+with the @option{-b} option to @samp{git checkout}:
+
address@hidden
+$ @kbd{git checkout -b feature/python}
address@hidden ...
address@hidden example
+
address@hidden @file{ChangeLog} file
address@hidden committing changes
+You now do massive amounts of work in order to add Python syntax support.
+As you do each defined chunk of work, you update the @file{ChangeLog}
+file with your changes before @dfn{committing} them to the repo.
+
address@hidden @code{git status}
+Let's say you've added a new file @file{python.c} and updated several
+others. Use @samp{git status} to see what's changed:
+
address@hidden
+$ @kbd{git status}
address@hidden ...
address@hidden example
+
address@hidden @code{git diff}
address@hidden @code{git difftool}
address@hidden @command{meld} utility
+Before committing the current set of changes, you can use @samp{git diff}
+to view the changes. You may also use @samp{git address@hidden't
+run @samp{git difftool} in the background; it works interactively.} to run an
+external @command{diff} command, such as @command{meld} on GNU/Linux:
+
address@hidden
+$ @kbd{git diff} @ii{Regular built-in tool}
+$ @kbd{git difftool --tool=meld} @ii{GUI diff tool}
address@hidden example
+
address@hidden @code{git add}
+When you're happy with the changes, use @samp{git add} to tell
+Git which of the changed and/or new files you wish to have ready to
+be committed:
+
address@hidden
+$ @kbd{git add ...}
address@hidden example
+
address@hidden @code{git status}
+Use @samp{git status} to see that your changes are scheduled for committing:
+
address@hidden
+$ @kbd{git status}
address@hidden
address@hidden example
+
+Now you can commit your changes to your branch:
+
address@hidden @code{git commit}
address@hidden
+$ @kbd{git commit}
address@hidden example
+
address@hidden
address@hidden @code{git log}
+Running @samp{git commit} causes Git to invoke an editor
+(typically from the @env{$EDITOR} environment variable)
+in which you can compose a commit message. Please supply a
+short message summarizing the commit. This message will be
+visible via @samp{git log}.
+
address@hidden Undoing a change
address@hidden Undoing A Change
+
+Should you need to undo a change that you have not yet
+committed (so that you can start over), you can do so on
+per-file basis by simply checking out the file again:
+
address@hidden @code{git checkout}
address@hidden
+git checkout awkgram.y @ii{Undo changes to} address@hidden There is no
output}
address@hidden example
+
address@hidden @code{git reset}
+To start over completely, use @samp{git reset --hard}.
+Note that this will @emph{throw away} all your changes, with no
+chance for recovery, so be sure you really want to do it.
+
address@hidden Updating
address@hidden Updating and Merging
+
+As you work on your branch, you will occasionally want to bring it
+up to date with respect to @code{master}.
+This @value{SECTION} dicusses updating locale branches
+and handling merge conflicts.
+
address@hidden
+* Rebasing:: Rebasing A Local Branch.
+* Merge Conflicts:: Dealing With Merge Conflicts.
address@hidden menu
+
address@hidden Rebasing
address@hidden Rebasing A Local Branch
+
address@hidden rebasing
+For purely local branches, bringing your branch up to date is called
address@hidden, which causes the branch to look @emph{as if} you had
+started from the latest version of @code{master}. The steps are as
+follows:
+
address@hidden @code{git rebase}
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden
+$ @kbd{git checkout master} @ii{Checkout} master
+$ @kbd{git pull} @ii{Update it}
+$ @kbd{git checkout feature/python} @ii{Move back to new, purely local
branch}
+$ @kbd{git rebase master} @ii{``Start over'' from current}
master
address@hidden example
+
address@hidden Merge Conflicts
address@hidden Dealing With Merge Conflicts
+
address@hidden conflicts, from merging
address@hidden merge conflicts
+
+Sometimes, when merging from @code{master} into your branch, or from
+a branch into @code{master}, there will be @dfn{merge conflicts}.
+These are one or more areas within a file where there are conflicting
+sets of changes, and Git could not do the merge for you.
+In this case, the conflicted area will be delimited by the traditional
+conflict markers, @samp{<<<}, @samp{===} and @samp{>>>}.
+
+Your mission is then to edit the file and @dfn{resolve} the conflict
+by fixing the order of additions (such as in a @file{ChangeLog} file),
+or fixing the code to take new changes into account.
+
+Once you have done so, you tell Git that everything is OK using
address@hidden add} and @samp{git commit}:
+
address@hidden
+$ @kbd{git checkout feature/python} @ii{Move back to new, purely local
branch}
+$ @kbd{git rebase master} @ii{``Start over'' from current}
master
address@hidden ... Kaboom! Conflict. FIXME: Show real output here
+$ @kbd{gvim main.c} @ii{Edit the file and fix the
problem}
+$ @kbd{git add main.c} @ii{Tell Git everything is OK now
@dots{}}
+$ @kbd{git commit} @address@hidden and it's settled}
+$ @kbd{git rebase --continue} @ii{Continue the rebase}
address@hidden example
+
+The @command{git rebase --continue} then continues the process of
+rebasing the current branch that we started in @ref{Rebasing}.
+It's not necessary if you are using @samp{git merge}
+(@pxref{Points to remember}).
+
address@hidden Submitting Changes
address@hidden Submitting Your Changes
+
+So now your feature is complete. You've added test cases for it to
+the test address@hidden did do this, didn't you?}, you have
address@hidden entries that describe all the address@hidden remembered this,
right?},
+you have documented the new address@hidden wouldn't neglect this, would you?},
+and everything works great. You're ready
+to submit the changes for review, and with any luck, inclusion into
address@hidden
+
address@hidden review, changes you made
address@hidden changes, submitting for review
+There are two ways to submit your changes for review.
+
address@hidden @emph
address@hidden generating a single patch
address@hidden patch, single, generation of
address@hidden Generate a single large patch
+To do this, simply compare your branch
+to the branch off which it is based:
+
address@hidden @code{git checkout}
address@hidden @code{git diff}
address@hidden
+$ @kbd{git checkout feature/python}
+$ @kbd{git diff master > /tmp/python.diff}
address@hidden example
+
+Mail the @file{python.diff} file to the appropriate mailing list
+along with a description of what you've changed and why.
+
address@hidden @code{git format-patch}
address@hidden generating multiple patches
address@hidden patches, multiple, generation of
address@hidden Generate a set of patches that in toto comprise your changes
+To do this, use @samp{git format-patch}:
+
address@hidden @code{git checkout}
address@hidden
+$ @kbd{git checkout feature/python}
+$ @kbd{git format-patch}
address@hidden example
+
+This creates a set of patch files, one per commit that isn't on the
+original branch. Mail these patches, either separately, or as a set of
+attachments, to the appropriate mailing list along with a description
+of what you've changed and why.
+
address@hidden table
+
+Either way you choose to submit your changes, the @command{gawk}
+maintainer and development team will review your changes and provide feedback.
+If you have signed paperwork with the FSF for @command{gawk} and the maintainer
+approves your changes, he will apply the patch(es) and commit the changes.
+
+Which list should you send mail to? If you are just starting to
+contribute, use @email{bug-gawk@@gnu.org}. After making enough
+contributions, you may be invited to join the private @command{gawk}
+developers' mailing list. If you do so, then submit your changes to
+that list.
+
+If you make any substantial changes, you will need to assign copyright
+in those changes to the Free Software Foundation before the maintainer
+can commit those changes. @xref{Doing paperwork}, for more information.
+
address@hidden Removing Branches
address@hidden Removing Branches
+
address@hidden removing branches
address@hidden branches, removing
+Once the maintainer has integrated your changes, you can get
+rid of your local branch:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git branch}
address@hidden
+$ @kbd{git checkout master} @ii{Move to upstream branch}
+$ @kbd{git pull} @ii{Update}
+$ @kbd{gvim ChangeLog ...} @ii{Verify your changes are in}
+$ @kbd{git branch -d feature/python} @ii{Remove your local branch}
address@hidden example
+
address@hidden Points to remember
address@hidden Points to Remember
+
+There are some important points to remember:
+
address@hidden @bullet
address@hidden
+Always do a @samp{make distclean} before switching between branches.
+Things will get really confused if you don't.
+
address@hidden
+For upstream branches, @emph{always} work with tracking branches. @emph{Never}
+use @samp{git checkout origin/@var{whatever}}. Git will happily let
+you do something like that, but it's just plain asking for trouble.
+
address@hidden
+Make sure your tracking branches are up-to-date before doing anything
+with them, particularly using them as the basis for a rebase
+or merge. This typically means a three-step process:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden
+$ @kbd{git checkout master} @ii{Get to local copy}
+$ @kbd{git pull} @ii{Bring it up to date}
+$ @kbd{git checkout feature/python} @ii{Go back to your branch}
address@hidden example
+
address@hidden
+You can then do the actual rebase:
+
address@hidden @code{git rebase}
address@hidden
+$ @kbd{git rebase master} @ii{Now rebase your feature off of
master}
address@hidden example
+
address@hidden
+Git always treats the currently checked-out branch as the object of
+operations. For example, when comparing files with the regular
address@hidden command, the usage is @samp{diff @var{oldfile} @var{newfile}}.
+For @samp{git diff}, the current branch takes the place of @var{newfile}, thus:
+
address@hidden @code{git checkout}
address@hidden @code{git diff}
address@hidden
+$ @kbd{git checkout feature/python}
+$ @kbd{git diff master} @ii{Compare} master @ii{to current
branch}
address@hidden example
+
address@hidden
+or if merging:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git merge}
address@hidden
+$ @kbd{git checkout master} @ii{Checkout} master
+$ @kbd{git pull} @ii{Update tracking branch}
+$ @kbd{git merge feature/python} @ii{Merge changes into} master
address@hidden example
+
address@hidden itemize
+
address@hidden Development with commit access
address@hidden Development With Commit Access
+
+This @value{CHAPTER} describes how to do development when you @emph{do}
+have commit access to the @command{gawk} repo on Savannah.
+
address@hidden
+* Initial setup:: Getting started with commit access.
+* ssh clone:: Cloning using an @samp{ssh://} URL.
+* Developing patches:: Developing patches.
+* Developing new features:: Developing new features.
+* Developing fixes:: Developing fixes.
address@hidden menu
+
address@hidden Initial setup
address@hidden Initial Setup
+
+Congratulations! After becoming a quality contributor to @command{gawk}
+development, you've been invited to join the private development list
+and to accept having commit access to the repo.
+
address@hidden Savannah, creating an account
address@hidden account, Savannah, creation of
address@hidden @code{ssh} key
+The first thing to do is to create an account on Savannah, choosing a
+unique user name. To do so, go to the @uref{http://savannah.gnu.org,
+Savannah home page} and click on the ``New User'' link. The setup
+will include uploading of your @command{ssh} key, as per the instructions
+on the Savannah web page.
+
+After you've done all this, send email to the maintainer with your
+Savannah user name, and he will add you to the list of users who have
+commit access to the repo.
+
address@hidden ssh clone
address@hidden Cloning The Repo With An @command{ssh} URL
+
+In order to be able to commit changes to the repo, you must
+clone it using an @samp{ssh://} URL.
+Cloning the repo with @command{ssh} is similar to cloning
+with the Git protocol or with HTTP, but the URL is different:
+
address@hidden @code{git clone}
address@hidden URL, for @command{gawk} repository
address@hidden Repository, @command{gawk}, URL for
address@hidden
+$ @kbd{git clone ssh://yourname@@git.sv.gnu.org/srv/git/gawk.git}
address@hidden ...
address@hidden example
+
+Here, you should replace @samp{yourname} in the command with the user
+name you chose for use on Savannah.
+
address@hidden Developing patches
address@hidden Developing Patches
+
+The first part of developing a patch is the same as for developers
+without commit access:
+
address@hidden 1
address@hidden
+Develop the code and test it.
+
address@hidden
address@hidden @file{ChangeLog} file
+Update the @file{ChangeLog}.
+
address@hidden
address@hidden documentation files
address@hidden @file{gawktexi.in} documentation
address@hidden @file{gawk.1} manual page
+If necessary, update the documentation: @file{doc/gawktexi.in}
+and/or @file{doc/gawk.1}.
+
address@hidden @code{git diff}
address@hidden
+Use @samp{git diff > mychange.diff} to create a patch file.
+
address@hidden
+Send it to the mailing list for discussion.
+
address@hidden
+Iterate until the patch is ready to be committed.
address@hidden enumerate
+
+However, now that you have commit access, you can commit the fix and push
+it up to the repo yourself!
+Let's assume you've made a bug fix directly on @code{master}.
+Here's how to commit your changes:
+
address@hidden @code{git diff}
address@hidden @code{git add}
address@hidden @code{git commit}
address@hidden @code{git push}
address@hidden
+$ @kbd{git diff} @ii{Review the patch one more time}
+$ @kbd{git add @dots{}} @ii{Add any files for committing}
+$ @kbd{git commit} @ii{Commit the files. Include a commit message.}
+$ @kbd{git push} @ii{Push the files up to the repo. Ta da!}
address@hidden example
+
+The first three steps are the same described earlier
+(@pxref{Starting A New Branch}).
+The @samp{git push} is what's new, and it updates the repo on
+Savannah. Congratulations!
+
+As a courtesy, you should send a note to the mailing list indicating
+that you have pushed your change.
+
address@hidden Developing new features
address@hidden Developing New Features
+
+Developing a new feature can be easier once you have commit access
+to the repo. First, create a new branch to hold your feature:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden
+$ @kbd{git checkout master} @ii{Start from} master
+$ @kbd{git pull} @ii{Be sure to be up to date}
+$ @kbd{git checkout -b feature/python} @ii{Create and switch to a new
branch}
address@hidden example
+
+Now, you can develop as normal, adding new files if necessary (such as new
tests),
+modifying code, updating the @file{ChangeLog} and documentation, and so on.
+
+You can share changes with the mailing list as diffs, as usual. However,
especially
+for a large feature, it would be better to push your branch up to Savannah.
Then,
+everyone else can simply pull it down to their local systems and review your
+changes at their leisure.
+
+To push your branch up initially:
+
address@hidden @code{git diff}
address@hidden @code{git add}
address@hidden @code{git commit}
address@hidden @code{git push}
address@hidden
+$ @kbd{git diff} @ii{Review your changes}
+$ @kbd{git add @dots{}} @ii{Add any files for
committing}
+$ @kbd{git commit} @ii{Commit the files. Include
a commit message}
+$ @kbd{git push -u origin feature/python} @ii{Push the branch up to the
repo}
address@hidden example
+
+When you use @samp{push -u origin}, Git helpfully converts
+your purely local branch into a tracking branch. It becomes
+as if the branch had originated from the upstream repo
+and you checked it out locally.
+
address@hidden only need to do @samp{git push -u origin} once.}
+As you continue to work on your branch, the workflow simplifies
+into this:
+
address@hidden @code{git diff}
address@hidden @code{git add}
address@hidden @code{git commit}
address@hidden @code{git push}
address@hidden
+$ @kbd{git diff} @ii{Review your changes}
+$ @kbd{git add @dots{}} @ii{Add any files for committing}
+$ @kbd{git commit} @ii{Commit the files}
+$ @kbd{git push} @ii{Push your changes to the branch upstream}
address@hidden example
+
address@hidden Developing fixes
address@hidden Developing Fixes
+
+If you want to make a fix on @code{master} or on the current
+stable branch, you work the same way, by producing and discussing
+a diff on the mailing list. Once it's approved, you can commit it
+yourself:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git add}
address@hidden @code{git commit}
address@hidden @code{git diff}
address@hidden
+$ @kbd{git checkout master} @ii{Move to} master
+$ @kbd{git pull} @ii{Make sure we're up to date with the
maintainer}
+$ @kbd{gvim @dots{}} @ii{Make any fixes, compile, test}
+$ @kbd{git diff} @ii{Review your changes}
+$ @kbd{git add @dots{}} @ii{Add any files for committing}
+$ @kbd{git commit} @ii{Commit the files. Include a commit
message.}
address@hidden example
+
+When you're ready to push your changes:
+
address@hidden @code{git pull}
address@hidden @code{git push}
address@hidden
+$ @kbd{git pull} @ii{Download latest version; Git will merge}
+$ @kbd{gvim ...} @ii{Resolve any merge conflicts with} git add
@ii{and} git commit
+$ @kbd{git push} @ii{Now you can push your changes upstream}
address@hidden example
+
address@hidden Conflicts} for instructions on dealing with merge conflicts.
+
address@hidden General practices
address@hidden General Development Practices
+
+This @value{CHAPTER} discusses general practices for @command{gawk}
development.
+The discussion here is mainly for developers with commit access to the
+Savannah repo.
+
address@hidden @dfn
address@hidden propagating fixes to other branches
address@hidden fixes, propagating to other branches
address@hidden Propagating Fixes
+Usually, bug fixes should be made on the current ``stable'' branch.
+Once a fix has been reviewed and approved, you can commit it and
+push it yourself.
+Typically, the maintainer then takes care to merge the fix to @code{master}
+and from there to any other branches. However, you are welcome to
+save him the time and do this yourself.
+
address@hidden directory ownership
address@hidden ownership of directories
address@hidden Directory ownership
+Some developers ``own'' certain parts of the tree, such as the @file{pc} and
@file{vms} directories.
+They are allowed to commit changes to those directories without review by the
mailing
+list, but changes that also touch the mainline code should be submitted for
review.
+
address@hidden New feature development
+Unless you can convince the maintainer (and the other developers!) otherwise,
+you should @emph{always} start branches for new features from @code{master},
+and not from the current ``stable'' branch.
+
+Use @samp{checkout -b feature/@var{feature_name}} to create the initial branch.
+You may then elect to keep it purely local, or to push it up to Savannah for
+review, even if the feature is not yet totally ``ready for prime time.''
address@hidden table
+
+During development of a new feature, you will most likely wish to keep your
+feature branch up to date with respect to ongoing improvements in
@code{master}.
+This is generally easy to do. There are two different mechanisms, and which
+one you use depends upon the nature of your new feature branch.
+
address@hidden @dfn
address@hidden As long as your branch is purely local
+You should use @samp{git rebase}
+to the keep the branch synchronized with the original branch from which it was
forked:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git rebase}
address@hidden
+$ @kbd{git checkout master} @ii{Move to} master
+$ @kbd{git pull} @ii{Bring it up to date}
+$ @kbd{git checkout feature/python} @ii{Move to your new feature branch}
+$ @kbd{git rebase master} @ii{Rebase from} master
address@hidden example
+
address@hidden
+The rebasing operation may require that you resolve conflicts
+(@pxref{Merge Conflicts}).
+Edit any conflicted files and resolve the problem(s). Compile and
+test your changes, then use @samp{git add}
+and @samp{git commit} to indicate resolution, and then use
address@hidden rebase --continue} to continue the rebasing.
+Git is very good about providing short instructions on how to
+continue when such conflicts occur.
+
address@hidden Once the branch has been pushed up to Savannah
+You @emph{must} use @samp{git merge} to bring your feature branch up
+to date. That flow looks like this:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git merge}
address@hidden
+$ @kbd{git checkout master} @ii{Move to} master
+$ @kbd{git pull} @ii{Bring it up to date}
+$ @kbd{git checkout feature/python} @ii{Move to your new feature branch}
+$ @kbd{git merge master} @ii{Merge from} master
address@hidden example
+
address@hidden
+Here too, you may have to resolve any merge conflicts
+(@pxref{Merge Conflicts}).
+Once that's done, you can push the changes up to Savannah.
+
+When the changes on your branch are complete, usually the
+maintainer merges the branch to @code{master}. But
+there's really no magic involved, the merge is simply
+done in the other direction:
+
address@hidden @code{git checkout}
address@hidden @code{git pull}
address@hidden @code{git merge}
address@hidden
+$ @kbd{git checkout feature/python} @ii{Checkout feature branch}
+$ @kbd{git pull} @ii{Bring it up to date}
+$ @kbd{git checkout master} @ii{Checkout} master
+$ @kbd{git pull} @ii{Bring it up to date}
+$ @kbd{git merge feature/python} @ii{Merge from} feature/python
@ii{into} master
address@hidden example
+
+If you've been keeping @samp{feature/python} in sync with
address@hidden, then there should be no merge conflicts to
+resolve, and you can push the result to Savannah:
+
address@hidden @code{git push}
address@hidden
+$ @kbd{git push} @ii{Push up to Savannah}
address@hidden example
+
+Since @samp{feature/python} is no longer needed, it can be
+gotten rid of:
+
address@hidden @code{git branch}
address@hidden @code{git push}
address@hidden
+$ @kbd{git branch -d feature/python} @ii{Still on} address@hidden,
delete feature branch}
+$ @kbd{git push -u origin -d feature/python} @ii{Delete the branch on
Savannah}
address@hidden example
+
+The @samp{git push} command deletes the @code{feature/python}
+branch from the Savannah repo.
+
address@hidden @code{git fetch}
address@hidden
+Finally, you should send an email to developer's list describing
+what you've done so that everyone else can delete their
+copies of the branch and do a @samp{git fetch --prune}
+(@pxref{Repo Maintenance}).
+
+To update the other remaining development branches
+with the latest changes on @code{master}, use the
address@hidden/update-branches.sh} script in the repo.
+
address@hidden table
+
address@hidden Repo Maintenance
address@hidden Keeping Your Repo Organized
+
+There are a few commands you should know about to help keep
+your local repo clean.
+
address@hidden @emph
address@hidden removing old branches
address@hidden old branches, removing
address@hidden branches, removing
address@hidden Removing old branches
+Developers add branches to the Savannah repo and when development
+on them is done, they
+get merged into @code{master}. Then the branches on Savannah are
+deleted (as shown in @ref{General practices}).
+
+However, your local copies of those branches (labelled with the
address@hidden/} prefix) remain in your local repo. If you don't
+need them, then you can clean up your repo as follows.
+
+First, remove any related tracking branch you may have:
+
address@hidden @code{git pull}
address@hidden @code{git branch}
address@hidden
+$ @kbd{git pull} @ii{Get up to date}
+$ @kbd{git branch -d feature/merged-feature} @ii{Remove tracking branch}
address@hidden example
+
+Then, ask Git to clean things up for you:
+
address@hidden @code{git fetch}
address@hidden
+$ @kbd{git fetch --prune} @ii{Remove unneeded branches}
address@hidden example
+
address@hidden removing cruft
address@hidden cruft, removing
address@hidden Removing cruft
+As Git works, occasional ``cruft'' collects in the repository.
+Git does occasionally clean this out on its own, but if you're
+concerned about disk usage, you can do so yourself
+using @samp{git gc} (short for ``garbage collect''). For
+example:
+
address@hidden @code{git gc}
address@hidden
+$ @kbd{du -s .} @ii{Check disk usage}
address@hidden 99188 . @ii{Almost 10 megabytes}
+$ @kbd{git gc} @ii{Collect garbage}
address@hidden Counting objects: 32114, done.
address@hidden Delta compression using up to 4 threads.
address@hidden Compressing objects: 100% (6370/6370), done.
address@hidden Writing objects: 100% (32114/32114), done.
address@hidden Total 32114 (delta 25655), reused 31525 (delta 25231)
+$ @kbd{du -s .} @ii{Check disk usage again}
address@hidden 75168 . @ii{Down to 7 megabytes}
address@hidden example
+
address@hidden renaming branches
address@hidden branches, renaming
address@hidden Renaming branches
+Occasionally you may want to rename a address@hidden discussion
+adopted from
address@hidden://multiplestates.wordpress.com/2015/02/05/rename-a-local-and-remote-branch-in-git,
here}.}
+If your branch is local and you are on it, us:
+
address@hidden
+$ @kbd{git branch -m feature/@var{new-name}}
address@hidden example
+
address@hidden
+Otherwise, use:
+
address@hidden
+$ @kbd{git branch -m feature/@var{old-name} feature/@var{new-name}}
address@hidden example
+
+You then need to fix the upstream repo. This command does so,
+using an older syntax to simultaneously delete the old name and
+push the new name. You should be on the new branch:
+
address@hidden
+$ @kbd{git push origin :feature/@var{old-name} feature/@var{new-name}}
address@hidden example
+
address@hidden NOTE
+It is the leading @samp{:} in the first branch name that causes
+Git to delete the old name in the upstream repo. Don't omit it!
address@hidden quotation
+
+Finally, reset the upstream branch for the local branch
+with the new name:
+
address@hidden
+$ @kbd{git push -u origin feature/@var{new-name}}
address@hidden example
+
address@hidden table
+
address@hidden Development Stuff
address@hidden Development Stuff
+
+This @value{CHAPTER} discusses other things you need to know and/or do
+if you're going to participate seriously in @command{gawk} development.
+
address@hidden
+* Coding style:: Where to read up on the coding style.
+* Doing paperwork:: Legal stuff in order to contribute.
+* Tools:: Tools to have on your system for development.
+* Debugging:: Compiling for debugging.
address@hidden menu
+
address@hidden Coding style
address@hidden Coding Style
+
address@hidden coding style
+You should read the discussion about adding code in the @command{gawk}
+documentation.
address@hidden
address@hidden, Additions, Making Additions to @command{gawk}, gawk, GAWK:
Effective awk Programming},
+for a discussion of the general procedure. In particular, pay attention to the
+coding style guidelines in
address@hidden Code, Adding Code, Adding New Features, gawk, GAWK: Effective
awk address@hidden that don't follow the coding
+style guidelines won't be accepted. Period.}
+These two sections may also be found online, at
address@hidden://www.gnu.org/software/gawk/manual/html_node/Additions.html#Additions},
and
address@hidden://www.gnu.org/software/gawk/manual/html_node/Adding-Code.html#Adding-Code},
+respectively.
address@hidden ifnothtml
address@hidden
+See
@uref{https://www.gnu.org/software/gawk/manual/html_node/Additions.html#Additions,
+the section @cite{Making Additions to @command{gawk}}}, in the online
documentation
+for a discussion of the general procedure. In particular, pay attention to the
+coding style guidelines in
address@hidden://www.gnu.org/software/gawk/manual/html_node/Adding-Code.html#Adding-Code,
+the section @cite{Adding New Features}}, also in the online documentation.
address@hidden ifhtml
+
address@hidden Doing paperwork
address@hidden Assigning Copyrights to the FSF
+
address@hidden assigning copyright
address@hidden copyright, assignment
+For any change of more than just a few lines, you will need to assign
+copyright in (that is, ownership of) those changes to the Free Software
+Foundation.
+
+This is generally an easy thing to do. In particular, you can choose to
+use a version of the copyright assignment which assigns all your current
address@hidden future} changes to @command{gawk} to the FSF. This means
+that you only need to do the paperwork once, and from then on all your
+changes will automatically belong to the FSF. The maintainer recommends
+doing this.
+
+The maintainer will help you with this process once you have a
+contribution that warrants it.
+
address@hidden Tools
address@hidden Software Tools You Will Need
+
address@hidden software tools
+This @value{SECTION} discusses additional tools that you may need to
+install on your system in order to be in sync with what the @command{gawk}
+maintainer uses. It also discusses different C compiler options for use
+during code development, and how to compile @command{gawk} for debugging.
+
address@hidden
+* GNU Tools:: The GNU Autotools.
+* Compilers:: A discussion of compilers that can be used.
address@hidden menu
+
address@hidden GNU Tools
address@hidden GNU Tools
+
address@hidden GNU software tools
address@hidden autotools
+If you expect to work with the configuration files and/or the
address@hidden files, you will need to install a number of other GNU
+tools. In general, you should be using the latest versions of the tools,
+or least the same ones that the maintainer himself uses. This helps
+minimize the differences that the maintainer has to resolve when merging
+changes, and in general avoids confusion and hassle.
+Similarly, you should install the latest GNU documentation tools as well.
+The tools are described in the following list:
+
address@hidden @command
address@hidden @command{autoconf}
address@hidden GNU @command{autoconf}
address@hidden @file{configure.ac} file
address@hidden autoconf
+GNU Autoconf processes the @file{configure.ac} files in order to
+generate the @file{configure} shell script and @file{config.h.in}
+input file. See @uref{https://www.gnu.org/software/autoconf/autoconf.html,
+the Autoconf home page} for more information.
+
address@hidden @command{automake}
address@hidden GNU @command{automake}
address@hidden @file{Makefile.am} file
address@hidden automake
+GNU Automake processes the @file{configure.ac} and @file{Makefile.am}
+files to produce @file{Makefile.in} files. See
@uref{https://www.gnu.org/software/automake,
+the Automake home page} for more information.
+
address@hidden @command{gettext}
address@hidden GNU @command{gettext}
address@hidden @file{gawk.pot} file
address@hidden gettext
+GNU Gettext processes the @command{gawk} source code to produce the
+original @file{po/gawk.pot} message template file. Normally you
+should not need need to do this; the maintainer usually
+manages this task. See @uref{https://www.gnu.org/software/gettext,
+the Gettext home page} for more information.
+
address@hidden @command{libtool}
address@hidden GNU @command{libtool}
address@hidden extensions, @command{gawk}
address@hidden libtool
+GNU Libtool works with Autoconf and Automake to produce portable
+shared libraries. It is used for the extensions that ship with @command{gawk},
+whose code is in the @file{extensions} directory.
+See @uref{https://www.gnu.org/software/libtool, the Libtool home page}
+for more information.
+
address@hidden @command{makeinfo}
address@hidden GNU @command{makeinfo}
address@hidden @command{Texinfo}
address@hidden GNU Texinfo
address@hidden makeinfo
+The @command{makeinfo} command is used to build the Info versions of
+the documentation. You need to have the same version as the maintainer
+uses, so that when you make a change to the documentation, the corresponding
+change to the generated Info file will be minimal. @command{makeinfo} is
+part of GNU Texinfo. See @uref{https://www.gnu.org/software/texinfo,
+the Texinfo home page} for more information.
+
address@hidden table
+
address@hidden Compilers
address@hidden Compilers
+
address@hidden compilers
address@hidden GCC, the GNU Compiler Collection
+The default compiler for @command{gawk} development is GCC, the
address@hidden://gcc.gnu.org, GNU Compiler Collection}.
+The default version of GCC is whatever is on the
+maintainer's personal GNU/Linux system, although he does try to build
+the latest released version if that is newer than what's
+on his system, and then occasionally test @command{gawk} with it.
+
address@hidden @command{clang} compiler
+He also attempts to test occasionally with @uref{https://clang.llvm.org/,
address@hidden However, he uses whatever is the default for his
+GNU/Linux system, and does @emph{not} make an effort to build the current
+version for testing.
+
+Both GCC and @command{clang} are highly optimizing compilers that produce
+good code, but are very slow. There are two other compilers that
+are faster, but that may not produce quite as good code. However, they
+are both reasonable for doing development.
+
address@hidden @emph
address@hidden @command{tcc} compiler
address@hidden Tiny C compiler
address@hidden The Tiny C Compiler, @command{tcc}
+This compiler is @emph{very} fast, but it produces only mediocre code.
+It is capable of compiling @command{gawk}, and it does so well enough
+that @samp{make check} runs without errors.
+
+However, in the past the quality has varied, and the maintainer has
+had problems with it. He recommends using it for regular development,
+where fast compiles are important, but rebuilding with GCC before doing
+any commits, in case @command{tcc} has missed address@hidden
+bit the maintainer once.}
+
+See @uref{http://www.tinycc.org, the project's home page} for
+some information. More information can be found in the project's
address@hidden://repo.or.cz/tinycc.git, Git repository}. The maintainer builds
+from the @code{mob} branch for his work, but after updating it you should
+check that this branch still works to compile @command{gawk} before
+installing it.
+
address@hidden @command{pcc} compiler
address@hidden Portable C compiler
address@hidden The (Revived) Portable C Compiler
+This is an updated version of the venerable Unix Portable C Compiler,
+PCC. It accepts ANSI C syntax and supports both older and modern
+architectures. It produces better code than @command{tcc} but is slower,
+although still much faster than GCC and @command{clang}.
+
+See @uref{http://pcc.ludd.ltu.se, the project's home page} for more
+information. See @uref{http://pcc.ludd.ltu.se/supported-platforms}
+for instructions about obtaining the code using CVS and building it.
+
address@hidden @command{pcc} compiler, Git mirror
+An alternative location for the source is the @command{gawk}
+maintainer's @uref{https://github.com/arnoldrobbins/pcc-revived,
+Git mirror} of the code.
address@hidden table
+
address@hidden Debugging
address@hidden Compiling For Debugging
+
address@hidden debugging, compiling for
address@hidden compiling for debugging
+If you wish to compile for debugging, you should use GCC. After
+running @command{configure} but before running @command{make}, edit the
address@hidden and remove the @option{-O2} flag from the definition of
address@hidden Optionally, do the same for @file{extensions/Makefile}.
+Then run @command{make}.
+
address@hidden @file{.developing} file
+You can enable additional debugging code by creating a file
+named @file{.developing} in the @command{gawk} source code directory
address@hidden running @command{configure}. Doing so enables additional
+conditionally-compiled debugging code within @command{gawk}, and adds
+additional warning and debugging options if compiling with GCC.
+
address@hidden Cheat Sheet
address@hidden Git Command Cheat Sheet
+
+This @value{APPENDIX} provides an alphabetical list of the Git commands
+cited in this @value{DOCUMENT}, along with brief descriptions of
+what the commands do.
+
address@hidden @code{git help}
address@hidden @option{--help} option for @command{git}
address@hidden @command{git} command, @option{--help} option
+Note that you may always use either @samp{git help @var{command}}
+or @samp{git @var{command} --help} to get short, man-page style
+help on how to use any given Git command.
+
address@hidden @code
address@hidden git add
+Add a file to the list of files to be committed.
+
address@hidden git branch
+View existing branches, or delete a branch.
+Most useful options: @option{-a} and @option{-d}.
+
address@hidden git checkout
+Checkout an existing branch, create a new branch, or checkout a file to
+reset it. Use the @option{-b} option to create and checkout a
+new branch in one operation.
+
address@hidden git clone
+Clone (make a new copy of) an existing repository. You generally
+only need to do this once.
+
address@hidden git commit
+Commit changes to files which have been staged for committing
+with @samp{git add}.
+This makes your changes permanent, @emph{in your local repository only}.
+To publish your changes to an upstream repo, you must use @samp{git push}.
+
address@hidden git config
+Display and/or change global and/or local configuration settings.
+
address@hidden git diff
+Show a unified-format diff of what's changed in the current directory
+as of the last commit. It helps to have Git configured to use
+its builtin pager for reviewing diffs (@pxref{Configuring git}).
+
address@hidden git difftool
+Use a ``tool'' (usually a GUI-based program) to view differences,
+instead of the standard textual diff as you'd get from @samp{git diff}.
+
address@hidden git fetch
+Update your local copy of the upstream's branches. That is,
+update the various @samp{origin/} branches. This leaves your
+local tracking branches unchanged.
+With the @option{--prune} option, this removes any copies
+of stale @samp{origin/} branches.
+
address@hidden git format-patch
+Create a series of patch files, one per commit not on the
+original branch from which you started.
+
address@hidden git gc
+Run a ``garbage collection'' pass in the current repository.
+This can often reduce the space used in a large repo. For
address@hidden it does not make that much difference.
+
address@hidden git help
+Print a man-page--style usage summary for a command.
+
address@hidden git log
+Show the current branch's commit log. This includes who
+made the commit, the date, and the commit message.
+Commits are shown from newest to oldest.
+
address@hidden git merge
+Merge changes from the named branch into the current one.
+
address@hidden git pull
+When in your local tracking branch @address@hidden,
+run @samp{git fetch}, and then merge from @code{origin/@var{xxx}}
+into @address@hidden
+
address@hidden git push
+Push commits from your local tracking branch @address@hidden
+through @code{origin/@var{xxx}} and on to branch @address@hidden
+in the upstream repo. Use @samp{git push -u origin -d @var{xxx}} to delete
+an upstream branch. (Do so carefully!)
+
address@hidden git rebase
+Rebase the changes in the current purely local branch to
+look as if they had been made relative to the latest
+commit in the current upstream branch (typically @code{master}).
+This is how you keep your local, in-progress changes up-to-date
+with respect to the original branch from which they were started.
+
address@hidden git reset
address@hidden @code{git reset}, @option{--hard} option
+Restore the original state of the repo, especially with the
address@hidden option. Read up on this command, and use it carefully.
+
address@hidden git status
+Show the status of files that are scheduled to be committed,
+and those that have been modified but not yet scheduled for committing.
+Use @samp{git add} to schedule a file for committing.
+This command also lists untracked files.
+
address@hidden table
+
address@hidden Resources
address@hidden Git Resources
+
address@hidden @cite{Pro Git} book
+There are many Git resources available on the Internet.
+Start at the @uref{http://git-scm.org, Git Project home page}.
+In particular, the @uref{https://git-scm.com/book/en/v2,
address@hidden Git} book} is available online.
+
address@hidden Savannah, using Git guide
+See also @uref{http://savannah.gnu.org/maintenance/UsingGit,
+the Savannah quick introduction to Git}.
+
address@hidden TODO
address@hidden Stuff Still To Do In This Document
+
address@hidden @bullet
address@hidden
+Fill out all examples with full output
+
address@hidden itemize
+
address@hidden
address@hidden Index
address@hidden Index
address@hidden ifnotdocbook
address@hidden cp
+
address@hidden
diff --git a/doc/using-git.texi b/doc/using-git.texi
deleted file mode 100644
index 1812c15..0000000
--- a/doc/using-git.texi
+++ /dev/null
@@ -1,1179 +0,0 @@
-\input texinfo @c -*-texinfo-*-
address@hidden %**start of header (This is for running Texinfo on a region.)
address@hidden using-git.info
address@hidden Workflow in the @command{gawk} project
address@hidden %**end of header (This is for running Texinfo on a region.)
-
address@hidden Network applications
address@hidden
-* Gawkworkflow: (using-git). Workflow in the `gawk' project.
address@hidden direntry
-
address@hidden
address@hidden DOCUMENT book
address@hidden CHAPTER chapter
address@hidden SECTION section
address@hidden DARKCORNER @address@hidden,1cm}, @image{rflashlight,1cm}}
address@hidden iftex
address@hidden
address@hidden DOCUMENT Info file
address@hidden CHAPTER major node
address@hidden SECTION node
address@hidden DARKCORNER (d.c.)
address@hidden ifinfo
address@hidden
address@hidden DOCUMENT web page
address@hidden CHAPTER chapter
address@hidden SECTION section
address@hidden DARKCORNER (d.c.)
address@hidden ifhtml
-
address@hidden FN file name
address@hidden FFN File Name
-
address@hidden merge the function and variable indexes into the concept index
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden ifinfo
address@hidden
address@hidden fn cp
address@hidden vr cp
address@hidden iftex
-
address@hidden If "finalout" is commented out, the printed output will show
address@hidden black boxes that mark lines that are too long. Thus, it is
address@hidden unwise to comment it out when running a master in case there are
address@hidden overfulls which are deemed okay.
-
address@hidden
address@hidden
address@hidden iftex
-
address@hidden
-
address@hidden TITLE Workflow in the @command{gawk} project
address@hidden EDITION 0.0
address@hidden UPDATE-MONTH August, 2014
address@hidden gawk versions:
address@hidden VERSION 4.1
address@hidden PATCHLEVEL 0
-
address@hidden
-This is Edition @value{EDITION} of @address@hidden,
-for the @address@hidden (or later) version of the GNU
-implementation of AWK.
address@hidden 2
-Copyright (C) 2014, 2015 Free Software Foundation, Inc.
address@hidden 2
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
address@hidden a
address@hidden
-The FSF's Back-Cover Text is: ``You have the freedom to
-copy and modify this GNU manual.''
address@hidden enumerate
address@hidden copying
-
address@hidden
-This file documents the workflow of the developers in the GNU
address@hidden project.
-
address@hidden
address@hidden ifinfo
-
address@hidden odd
-
address@hidden
address@hidden @value{TITLE}
address@hidden Edition @value{EDITION}
address@hidden @value{UPDATE-MONTH}
address@hidden J@"urgen Kahrs
address@hidden with Arnold D. Robbins
-
address@hidden Include the Distribution inside the titlepage environment so
address@hidden that headings are turned off. Headings on and off do not work.
-
address@hidden
address@hidden 0pt plus 1filll
address@hidden 2
-Published by:
address@hidden 1
-
-Free Software Foundation @*
-51 Franklin Street, Fifth Floor @*
-Boston, MA 02110-1301 USA @*
-Phone: +1-617-542-5942 @*
-Fax: +1-617-542-2652 @*
-Email: @email{gnu@@gnu.org} @*
-URL: @uref{http://www.gnu.org/} @*
-
-ISBN 1-882114-93-0 @*
-
address@hidden
-
address@hidden @sp 2
address@hidden Cover art by ?????.
address@hidden titlepage
-
address@hidden
address@hidden off
address@hidden @thispage@ @ @ @address@hidden @| @|
address@hidden @| @| @address@hidden@ @ @ @thispage
address@hidden iftex
-
address@hidden
address@hidden Top
address@hidden Introduction
address@hidden node-name, next, previous, up
-
-This file documents the workflow of the developers in the GNU Awk
(@command{gawk})
-version 4.1 and later.
-
address@hidden
address@hidden ifnottex
-
address@hidden
-* Introduction:: About networking.
-* Basics of GIT repositories:: The fundamental environment of
- the developer.
-* Conventions used in the repository:: How to behave.
-* Tutorial for a first-time-gawk-contributor:: How to get started with least
- pain.
-* FAQs and HOWTOs:: General recipes for daily work.
-* Links:: Where to find the stuff
- mentioned in this document.
-* GNU Free Documentation License:: The license for this document.
-* Index:: The index.
-
address@hidden
-* Quick Start::
-* Setting up a proper @command{git} repository::
-* Pulling the latest changes from the remote repository::
-* Checking out a feature branch from the remote repository::
-* Semantics of Cloning:: What to
- consider
- before you
- clone.
-* Local versus Remote:: Where my
- source code
- really is.
-* Tracking and Merging:: What the
- others are
- doing.
-* master::
-* stable::
-* feature::
-* who does what::
-* step-by-step instructions for a first-time-gawk-contributor::
-* step-by-step instructions for a first-time-gawk-administrator::
-* general recipes for daily work::
-* references and URLs to books and other texts::
address@hidden detailmenu
address@hidden menu
-
address@hidden
-
address@hidden Introduction
address@hidden Introduction
-
-This @value{DOCUMENT} is meant to be a description of the working habits
-that were established for collaboration in the GNU Awk project.
-Such stuff tends to become rather dry, and to prevent you from getting
-bored at this early stage, we will begin this @value{CHAPTER} with a
-brief introduction that shows you how to get the
-source code of the GNU Awk project compiled on your machine.
-
-We do this in order to get you motivated to follow us through the later
-steps that consist mainly of conceptual considerations.
-We hope that (in later, more abstract steps) you will always remember
-this down-to-earth introduction, should you ever wonder what all the
-later bizarre trickery is good for.
-
address@hidden
-* Quick Start::
-* Setting up a proper @command{git} repository::
-* Pulling the latest changes from the remote repository::
-* Checking out a feature branch from the remote repository::
address@hidden menu
-
address@hidden Quick Start
address@hidden Quick Start: Compiling @command{gawk} in 5 Minutes
-
-The following steps will look familiar to you; they are not that much
-different from the steps you used in the old days when you downloaded
-a tar ball, extracted it and compiled the source code. It is mainly
-the very first step that looks different; instead of downloading the
-tar ball you need the tool @address@hidden the command
address@hidden does not exist on your machine,
-you need adminstrator privileges to install it. By convention, the
-command is usually part of an installation package by the same name.}
-
address@hidden
-git clone git://git.savannah.gnu.org/gawk.git
-cd gawk
-git checkout gawk-4.1-stable
-./bootstrap.sh
-./configure
-make
-./gawk --version
address@hidden example
-
-There are two differences to your working habits. In the third step,,
-you have to extract (or @dfn{check out}) the @code{gawk-4.1-stable} branch of
the current source
-code (there are other branches available, that's the point where
-things get interesting).
-
-In the fourth step, you must run the @command{bootstrap.sh} script in
-order to set correctly timestamps on various files. Doing this is essential;
-it allows you to avoid having to install the correct versions of the
-various autotools as used by the @command{gawk} maintainer.
-
-Isn't this simple? No, it's not that simple.
-If you plan to go any further (for example compile the source
-code again next week, including next week's latest update), you will
-need to know what's going on when you use this seemingly simple
address@hidden command (and that's the point where things get bizarre).
-
-In the next @value{CHAPTER} you will find a more thorough conceptual
-explanation, here we are satisfied with getting to know the practical
-steps necessary to get a working environment going that you can use
-in your daily work in a reliable way.
-
address@hidden Setting up a proper @command{git} repository
address@hidden Setting up a proper @command{git} repository
-
-After the initial @emph{checkout} you have access to all the source code
-files that the maintainers have pushed through the official release procedure.
-
-You may not have noticed, but each change is well documented and traceable.
-This process of tracing the change history is so precise, reproducable and
-fine-grained that any dubious change may be kicked out later and the author
-of dubious stuff identified by name and change date.
-
-Some bookkeeping is
-necessary for this and that's why you need @command{git}. @command{git}
-does all this for you. Developers who have used @command{svn} or
address@hidden in the past will not be surprised to hear that each change
-is traceable precisely (they know that @command{svn} and @command{cvs}
-can do this, too).
-
-But the first-time user of @command{git} (as well as the @command{svn} user)
-may still have failed to notice what he actually did earlier in this
@value{CHAPTER}.
-It is not just a mere copy of the source code that you created,
-it is a full copy of the entire @dfn{upstream} repository server that you
created
-(or @dfn{cloned}). This means that others could make their own copy of
address@hidden repository and treat it as @emph{their upstream} repository.
-
-This is the essential difference between working with @command{svn} and
-working with @command{git}: by @emph{cloning} you become a repository
-administrator, whether you like it or not. As such you have some duties that
-go beyond the duties of an @command{svn} user. For example, you have to
-identify yourself properly as the owner of the repository by setting
-some global variables identifying you. The global settings will be used
-every time you connect again to the upstream repository.
-
address@hidden
-git config --global user.name "@var{First-Name Last-Name}"
-git config --global user.email @var{email@@address.site}
-git config --global color.ui auto
address@hidden smallexample
-
-You may leave these variables unset, but then you are reduced to an
-anonymous consumer-only behaviour whenever you connect to the upstream
-repository. Later you will learn that there are many other variables
-to be set, most of them serving as defaults that can be overridden if
-you like. Choosing to work with defaults makes work quick and easy for the
most frequent
-use cases, but that comes at a cost: With so many helpful defaults
-you may be overwhelmed by the detail and complexity of the real inner working.
-Here is an example of one of the author's configuration variables:
-
address@hidden
-$ @kbd{git config --list}
address@hidden user.name=First-Name Last-Name
address@hidden user.email=email@@address.site
address@hidden color.diff=auto
address@hidden color.status=auto
address@hidden color.branch=auto
address@hidden gui.spellingdictionary=en_US
address@hidden core.repositoryformatversion=0
address@hidden core.filemode=true
address@hidden core.logallrefupdaIsn't this simple? No, it's not that simple.
tes=true
address@hidden remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
address@hidden remote.origin.url=ssh://jkahrs@@git.sv.gnu.org/srv/git/gawk.git
address@hidden branch.master.remote=origin
address@hidden branch.master.merge=refs/heads/master
address@hidden branch.xgawk_load.remote=origin
address@hidden branch.xgawk_load.merge=refs/heads/xgawk_load
address@hidden smallexample
-
-Changing these variables with specialized variants of the @command{git} command
-may seem awkward to you and perhaps you prefer to use your favourite text
editor
-to overview and change the variables. That's easy: edit the file
@file{.git/config}.
-
address@hidden
-$ @kbd{cat .git/config}
address@hidden [core]
address@hidden repositoryformatversion = 0
address@hidden filemode = true
address@hidden bare = false
address@hidden logallrefupdates = true
address@hidden [remote "origin"]
address@hidden fetch = +refs/heads/*:refs/remotes/origin/*
address@hidden url = ssh://jkahrs@@git.sv.gnu.org/srv/git/gawk.git
address@hidden [branch "master"]
address@hidden remote = origin
address@hidden merge = refs/heads/master
address@hidden [branch "cmake"]
address@hidden remote = origin
address@hidden merge = refs/heads/cmake
address@hidden smallexample
-
-Now you can see how variables are structured group-wise.
-But wait, where is the e-mail address in this list of variables?
-It is missing in the file @file{.git/config} because that file
-contains only the local settings of this one repository
-(while there may be others on your machine).
-The e-mail address is a variable of a more general kind that
-should be stored above all the repositories.
-These are referred to as the @dfn{global} variables:
-
address@hidden
-$ @kbd{git config --list --global}
address@hidden user.name=First-Name Last-Name
address@hidden user.email=email@@address.site
address@hidden color.diff=auto
address@hidden color.status=auto
address@hidden color.branch=auto
address@hidden gui.spellingdictionary=en_US
address@hidden smallexample
-
-If you wonder whether there is a parameter @command{--local} to list
-the local variables, then you should look into the well-structured
-man pages of @command{git}. The level of detail may overwhelm you,
-but one day you might appreciate it.
-
address@hidden
-git help config
address@hidden smallexample
-
address@hidden Pulling the latest changes from the remote repository
address@hidden Pulling the latest changes from the remote repository
-
-Whether you set any of these variables or not, sooner or later you will want
-to catch up with the changes that happened in the upstream repository.
-So, how can you update your copy of the repository and re-build the source
code?
-The easiest way is to rely on defaults and use the @emph{pull} command to
request
-updates from the upstream repository:
-
address@hidden
-git pull
-./bootstrap.sh
-./configure
-make
address@hidden smallexample
-
-When using the @emph{pull} command, all the changes available in all branches
of
-the upstream repository will be copied (and merged) into your local repository.
-We assume here that we still have the @emph{gawk-4.1-stable} branch checked
out (as described earlier)
-and we are not interested in changes to other existing branches.
-The merging of changes will be done inside the branches only, so that changes
in one
-branch are kept inside this branch and don't mix up other branches.
-
address@hidden ========================================
-
-But @emph{what is a branch?} you may wonder. It is the name given to a
sequence of changes
-that were made to the master branch outside the master branch.
-It is easy to look up all the available branches
-(the names of the change sequences) in the remote upstream repository.
-
address@hidden
-$ @kbd{git branch -a}
address@hidden * master
address@hidden remotes/origin/cmake
address@hidden smallexample
-
-The asterisk in front of the branch name assures you of the fact that you see
-the source files as they are in the @emph{master} branch.
-
address@hidden Checking out a feature branch from the remote repository
address@hidden Checking out a feature branch from the remote repository
-
-It is also easy to
-have a look at other branches, for example when you are interested in what is
-going on in a certain @emph{feature branch} that the maintainer set up recently
-for a new feature to be developed separately (so that others can go on
undisturbed).
-
address@hidden
-$ @kbd{git checkout origin/cmake}
-$ @kbd{git branch -a}
address@hidden master
address@hidden * remotes/origin/cmake
-$ @kbd{./bootstrap.sh}
-$ @kbd{./configure}
-$ @kbd{make}
address@hidden smallexample
-
-When you try this, take care that you have not changed anything in any source
file.
address@hidden would notice changes and refuse to checkout the other branch.
-This is meant to protect you from losing any local changes that you forgot to
save.
-Any source file that is part of the repository and gets generated during the
build
-in a slightly different way than the original would cause such a problem.
-
address@hidden
-$ @kbd{git status}
address@hidden # On branch master
address@hidden # Changes not staged for commit:
address@hidden # awkgram.c
address@hidden smallexample
-
-Here we have @file{awkgram.c} that was generated from @file{awkgram.y}.
-But what was generated differently in the file?
-
address@hidden
-git diff awkgram.c
address@hidden smallexample
-
-Ok, you are not interested in textual changes to the copyright notice
-that are only due to a new calendar year. You are also not interested
-in the internals of the generated parser and only wonder
address@hidden do we get back the original file from the repository?}
-
address@hidden
-$ @kbd{git checkout awkgram.c}
-$ @kbd{git diff awkgram.c | wc -l}
address@hidden 0
address@hidden smallexample
-
-After checking the file out once more, there is obviously no difference
-to the copy saved in the repository. But let's not get distracted, we
-wanted to find out what was going on in this feature branch. We can
-find out by asking @command{git} what has changed in the file @file{ChangeLog}
-of this feature branch relative to the master branch.
-
address@hidden
-git diff origin/master ChangeLog
address@hidden smallexample
-
address@hidden
-This produces:
-
address@hidden
-diff --git a/ChangeLog b/ChangeLog
-index eab657c..a499ec5 100644
---- a/ChangeLog
-+++ b/ChangeLog
-@@ -1,81 +1,3 @@
--2014-09-07 Arnold D. Robbins <arnold@@skeeve.com>
--
-- * awk.h: Move libsigsegv stuff to ...
-- * main.c: here. Thanks to Yehezkel Bernat for motivating
-- the cleanup.
-- * symbol.c (make_symbol, install, install_symbol): Add const to
-- first parameter. Adjust decls and fix up uses.
address@hidden smallexample
-
-Looks like a minor cleanup operation in the master branch that has not
-yet been merged into the feature branch. We still don't know what is new
-in this feature branch, how can we know? By looking at all changes that exist.
-
address@hidden
-$ @kbd{git diff origin/master --numstat}
address@hidden 0 78 ChangeLog
address@hidden 8 3 README_d/README.cmake
address@hidden smallexample
-
-On your screen you see a list of all differences between the currently
-checked-out branch and the master branch. It tells you the names of the
-files that have changed, along with the number of added and deleted lines.
-Now we can have a closer look at who changed what.
-Let's single out one particular file that looks interesting.
-As usual there is a @command{diff} sub-command to list all the changed
-lines, but there is also a @command{blame} sub-command that tells you
-who made the last change to any of the lines.
-
address@hidden
-git blame README_d/README.cmake
address@hidden smallexample
-
address@hidden
-This produces (in part):
-
address@hidden
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 1) CMake is a build
automation system
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 2)
http://en.wikipedia.org/wiki/Cmake
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 3)
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 4) We try to use it as
a replacement for the established GNU build system.
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 5) This attempt is
currently only experimental. If you wonder why anyone
-2092a35f (Juergen Kahrs 2014-08-12 17:11:20 +0200 6) should do this, read
address@hidden smallexample
-
-The strange number on the left margin is the short form of a numerical
-identifier of the change set. At the moment you can safely ignore it,
-but this number is the key you need in case you should ever want to
-cherry-pick some change sets. But cherry-picking is still far away,
-before you can do this, you have to learn how to make changes to your
-local repository and @command{push} them to the upstream repository.
-Some conceptual basics are needed for understanding this essential part
-of the workflow.
-
address@hidden Basics of GIT repositories
address@hidden Basics of GIT repositories
-
address@hidden
-* Semantics of Cloning:: What to consider before you clone.
-* Local versus Remote:: Where my source code really is.
-* Tracking and Merging:: What the others are doing.
address@hidden menu
-
address@hidden http://iverilog.wikia.com/wiki/Installation_Guide
address@hidden http://www.linuxjournal.com/article/2840
address@hidden http://git-scm.com/book/en/Git-Branching-Branching-Workflows
address@hidden https://www.atlassian.com/en/git/workflows
address@hidden https://help.github.com/articles/what-is-a-good-git-workflow
address@hidden https://guides.github.com/introduction/flow/index.html
address@hidden
http://supercollider.sourceforge.net/wiki/index.php/Developer_cheatsheet_for_git
address@hidden http://savannah.gnu.org/maintenance/UsingGit/
address@hidden http://www.emacswiki.org/emacs/GitForEmacsDevs
-
-What is tracking ?
-
address@hidden
-- How can I use git to contribute source code ?
-You need an account at Savannah. Read this to understand the first steps:
- http://savannah.gnu.org/maintenance/UsingGit
- README.git
-Use your account there to register your public ssh key at Savannah.
-Then you are ready to checkout. Remember that (when cloning) you are
-setting up your own local repository and make sure you configure it
-properly.
- git clone ssh://my_account_name@@git.sv.gnu.org/srv/git/gawk.git
address@hidden display
-
address@hidden Semantics of Cloning
address@hidden Semantics of Cloning
-
address@hidden Local versus Remote
address@hidden Local versus Remote
-
address@hidden Tracking and Merging
address@hidden Tracking and Merging
-
address@hidden Conventions used in the repository
address@hidden Conventions used in the repository
-
address@hidden
-* master::
-* stable::
-* feature::
-* who does what::
address@hidden menu
-
address@hidden master
address@hidden master
-
address@hidden stable
address@hidden stable
-
address@hidden feature
address@hidden feature
-
address@hidden who does what
address@hidden who does what
-
address@hidden Tutorial for a first-time-gawk-contributor
address@hidden Tutorial for a first-time-gawk-contributor
-
address@hidden
-* step-by-step instructions for a first-time-gawk-contributor::
-* step-by-step instructions for a first-time-gawk-administrator::
address@hidden menu
-
address@hidden step-by-step instructions for a first-time-gawk-contributor
address@hidden step-by-step instructions for a first-time-gawk-contributor
-
address@hidden step-by-step instructions for a first-time-gawk-administrator
address@hidden step-by-step instructions for a first-time-gawk-administrator
-
address@hidden e-mail from Arnold 2014-08.24
address@hidden Thanks to Michal for pointing us in the right direction!
address@hidden I see this:
address@hidden
address@hidden bash-4.2$ git config --get push.default
address@hidden simple
address@hidden
address@hidden What does yours say?
address@hidden
address@hidden It appears that "simple" will be the default in version 2.0:
address@hidden
address@hidden From:
address@hidden
http://blog.nicoschuele.com/posts/git-2-0-changes-push-default-to-simple
address@hidden
address@hidden Matching
address@hidden
address@hidden The 'matching' option is the default behavior in Git 1.x. It
means that if you do a git push without specifying a branch, it will push all
your local branches to their matching ones on your remote repository.
address@hidden
address@hidden Simple
address@hidden
address@hidden The new default in Git 2.x is 'simple'. It means that when doing
a git push without specifying a branch, only your current branch will be pushed
to the one git pull would normally get your code from."
address@hidden
address@hidden So this must explain it. I'll bet yours is set to "matching".
I have no
address@hidden idea how mine got set to "simple", since I don't recall doing
that.
address@hidden
address@hidden In the future, I will simply make sure to push before switching
branches.
address@hidden I think I actually prefer that behavior, since it's more
intuitive to me.
-
-
address@hidden FAQs and HOWTOs
address@hidden FAQs and HOWTOs
-
address@hidden
-* general recipes for daily work::
address@hidden menu
-
address@hidden general recipes for daily work
address@hidden general recipes for daily work
-
address@hidden Links
address@hidden Links
-
address@hidden
-* references and URLs to books and other texts::
address@hidden menu
-
address@hidden references and URLs to books and other texts
address@hidden references and URLs to books and other texts
-
address@hidden The GNU Free Documentation License.
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden FDL (Free Documentation License)
address@hidden Free Documentation License (FDL)
address@hidden GNU Free Documentation License
address@hidden Version 1.3, 3 November 2008
-
address@hidden This file is intended to be included within another document,
address@hidden hence no sectioning command or @node.
-
address@hidden
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
address@hidden://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
address@hidden display
-
address@hidden 0
address@hidden
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document @dfn{free} in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
address@hidden
-APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The ``Document'', below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as ``you''. You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section
-of the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall
-subject (or to related matters) and contains nothing that could fall
-directly within that overall subject. (Thus, if the Document is in
-part a textbook of mathematics, a Secondary Section may not explain
-any mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not ``Transparent'' is called ``Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
-format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
-PostScript or @acronym{PDF} designed for human modification. Examples
-of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
-not generally available, and the machine-generated @acronym{HTML},
-PostScript or @acronym{PDF} produced by some word processors for
-output purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-The ``publisher'' means any person or entity that distributes copies
-of the Document to the public.
-
-A section ``Entitled XYZ'' means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as ``Acknowledgements'',
-``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
-of such a section when you modify the Document means that it remains a
-section ``Entitled XYZ'' according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
address@hidden
-VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
address@hidden
-COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
address@hidden
-MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
address@hidden A
address@hidden
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document). You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
address@hidden
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has fewer than five),
-unless they release you from this requirement.
-
address@hidden
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
address@hidden
-Preserve all the copyright notices of the Document.
-
address@hidden
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
address@hidden
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
address@hidden
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
address@hidden
-Include an unaltered copy of this License.
-
address@hidden
-Preserve the section Entitled ``History'', Preserve its Title, and add
-to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page. If
-there is no section Entitled ``History'' in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
address@hidden
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
address@hidden
-For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
-the Title of the section, and preserve in the section all the
-substance and tone of each of the contributor acknowledgements and/or
-dedications given therein.
-
address@hidden
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles. Section numbers
-or the equivalent are not considered part of the section titles.
-
address@hidden
-Delete any section Entitled ``Endorsements''. Such a section
-may not be included in the Modified Version.
-
address@hidden
-Do not retitle any existing section to be Entitled ``Endorsements'' or
-to conflict in title with any Invariant Section.
-
address@hidden
-Preserve any Warranty Disclaimers.
address@hidden enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled ``Endorsements'', provided it contains
-nothing but endorsements of your Modified Version by various
-parties---for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
address@hidden
-COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled ``History''
-in the various original documents, forming one section Entitled
-``History''; likewise combine any sections Entitled ``Acknowledgements'',
-and any sections Entitled ``Dedications''. You must delete all
-sections Entitled ``Endorsements.''
-
address@hidden
-COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
address@hidden
-AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an ``aggregate'' if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
address@hidden
-TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled ``Acknowledgements'',
-``Dedications'', or ``History'', the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
address@hidden
-TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License. If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
address@hidden
-FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation. If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy's public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
address@hidden
-RELICENSING
-
-``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works. A
-public wiki that anybody can edit is an example of such a server. A
-``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-``Incorporate'' means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is ``eligible for relicensing'' if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
address@hidden enumerate
-
address@hidden fakenode --- for prepinfo
address@hidden ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
address@hidden
address@hidden
- Copyright (C) @var{year} @var{your name}.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
address@hidden group
address@hidden smallexample
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the address@hidden'' line with this:
-
address@hidden
address@hidden
- with the Invariant Sections being @var{list their titles}, with
- the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
- being @var{list}.
address@hidden group
address@hidden smallexample
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
-
-
address@hidden Index
address@hidden node-name, next, previous, up
-
address@hidden Index
address@hidden cp
address@hidden
-
-Conventions:
-1. Functions, built-in or otherwise, do NOT have () after them.
-2. Gawk built-in vars and functions are in @code. Also program vars and
- functions.
-3. HTTP method names are in @code.
-4. Protocols such as echo, ftp, etc are in @samp.
-5. URLs are in @url.
-6. All RFCs in the index. Put a space between `RFC' and the number.
diff --git a/doc/wordlist2 b/doc/wordlist2
new file mode 100644
index 0000000..5d91c81
--- /dev/null
+++ b/doc/wordlist2
@@ -0,0 +1,176 @@
+Autoconf
+Automake
+Awk
+Bernat
+CFLAGS
+ChangeLog
+Ctrl
+FIXME
+FSF
+FSF's
+Gettext
+GitHub
+ISBN
+Kahrs
+Libtool
+PCC
+PDF
+Rebase
+Repo
+SVN
+TODO
+Texinfo
+UsingGit
+Workflow
+Yehezkel
+ac
+api
+arnold
+arnoldrobbins
+async
+autoconf
+autocrlf
+automake
+autotools
+awk
+awkgram
+builtin
+cd
+cindex
+com
+config
+const
+cp
+cvs
+cz
+da
+detailmenu
+dfn
+diff
+diffs
+difftool
+dircategory
+direntry
+distclean
+docbook
+du
+dvi
+emph
+en
+env
+evenheading
+expandtab
+filetype
+filll
+finalout
+fn
+gawktexi
+gawkworkflow
+gc
+gcc
+gdef
+gettext
+gitconfig
+github
+gvim
+html
+http
+https
+iface
+ifdocbook
+ifhtml
+ifinfo
+ifnotdocbook
+ifnothtml
+ifnotinfo
+ifnottex
+ifnotxml
+ifplaintext
+iftex
+ifxml
+inlineraw
+insertcopying
+jpdev
+kbd
+libtool
+lineannotation
+linkcolor
+listinfo
+literallayout
+llvm
+ltu
+ludd
+makeinfo
+mpfr
+multiplestates
+mychange
+newfile
+noindent
+nongnu
+oddheading
+oldfile
+org
+ourfile
+overfulls
+para
+pc
+pcc
+po
+printindex
+pt
+pxref
+rebase
+rebasing
+regexp
+repo
+repo's
+samp
+scm
+se
+setchapternewpage
+setfilename
+settitle
+shiftwidth
+shorttitlepage
+smallbook
+smallexample
+sp
+srv
+ssh
+stderr
+stdout
+summarycontents
+sv
+syncodeindex
+synindex
+tabstop
+tcc
+tex
+texi
+texinfo
+thischapter
+thispage
+titlepage
+tmp
+toto
+ui
+ulink
+unnumberedsec
+upstream's
+uref
+urefurlonlylinktrue
+urgen
+url
+urlcolor
+var
+vms
+vr
+vskip
+wordpress
+workflow
+worthwile
+www
+xref
+xxx
+xxxxxx
+yourname
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 7 +
doc/Makefile.am | 22 +-
doc/Makefile.in | 54 +-
doc/gawkworkflow.info | 1980 +++++++++++++++++++++++++++++++++++++++++++++
doc/gawkworkflow.texi | 2158 +++++++++++++++++++++++++++++++++++++++++++++++++
doc/using-git.texi | 1179 ---------------------------
doc/wordlist2 | 176 ++++
7 files changed, 4367 insertions(+), 1209 deletions(-)
create mode 100644 doc/gawkworkflow.info
create mode 100755 doc/gawkworkflow.texi
delete mode 100644 doc/using-git.texi
create mode 100644 doc/wordlist2
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, master, updated. gawk-4.1.0-2461-g6de370d,
Arnold Robbins <=