Copyright (C) 2005, 2006, 2007, 2009, 2010, 2011, 2012, 2013, 2014, 2015,
  2016, 2017, 2018, 2019 Free Software Foundation, Inc.
  
  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

README:

This is GNU Awk 5.1.0. It is upwardly compatible with Brian Kernighan's
version of Unix awk.  It is almost completely compliant with the
2018 POSIX 1003.1 standard for awk. (See the note below about POSIX.)

This is a bug-fix release. See NEWS and ChangeLog for details.

Work to be done is described briefly in the TODO file, which is available
only in the 'master' branch in the Git repo.

Changes in this version are summarized in the NEWS file.

Read the file POSIX.STD for a discussion of issues where the standard
says one thing but gawk does something different.

To format the documentation with TeX, use at least version 2017-09.16
of texinfo.tex. There is a usable copy of texinfo.tex in the doc directory.
You must also use at least version 6.7 of texindex and of makeinfo
from the texinfo-6.7 distribution.

INSTALLATION:

Check whether there is a system-specific README file for your system under
the `README_d' directory.  If there's something there that you should
have read and didn't, and you bug me about it, I'm going to yell at you.

See the file INSTALL for installation instructions.

If you don't have Bison, use the awkgram.c file here.  It was
generated with Bison, and has no proprietary code in it.  (Note that
modifying awkgram.y without Bison will be difficult, at best.  You might
want to get a copy of Bison from the FSF too.)

The build mechanics depend upon Bison. Also, gawk doesn't work correctly
with some versions of yacc, so just use Bison.

If you have an MS-DOS, MS-Windows, or OS/2 system, use the stuff in the `pc'
directory.  Similarly, there is a separate directory for VMS.

Appendix B of ``GAWK: Effective Awk Programming'' discusses configuration
in detail. The configuration process is based on GNU Autoconf and
Automake.

After successful compilation, do `make check' to run the test suite.
There should be no output from the `cmp' invocations except in the
cases where there are small differences in floating point values, and
possibly in the case of strftime.  There may be differences based on
installed (or not installed) locales and the quality of multibyte
character support on your system.

Several of the tests ignore errors on purpose; those are not a problem.
If there are other differences, please investigate and report the problem.

PRINTING THE MANUAL

The `doc' directory contains a recent version of texinfo.tex, which will
be necessary for printing the manual.  Use `make dvi' to get a DVI file
from the manual. In the `doc' directory, use `make postscript' to get
PostScript versions of the manual, the man page, and the reference card.
Use `make pdf' to get PDF versions of the manuals, the man page and
the reference card.

BUG REPORTS AND FIXES (Un*x systems):

Please coordinate changes through Arnold Robbins. In particular, see
the section in the manual on reporting bugs. Note that comp.lang.awk
is about the worst place to post a gawk bug report. So too is use of
a web forum such as Stack Overflow. Please, use the mechanisms outlined
in the manual.

Email should be sent to bug-gawk@gnu.org.  This is a separate mailing
list at GNU Central.  The advantage to using this address is that bug
reports are archived at GNU Central.

Arnold Robbins

BUG REPORTS AND FIXES, non-Unix systems:

MS-DOS with DJGPP:
	Juan Manuel Guerrero
	juan.guerrero@gmx.de

MS-Windows with MinGW:
	Eli Zaretskii
	eliz@gnu.org

OS/2:
	Andreas Buening
	andreas.buening@nexgo.de

VMS:
	John Malmberg
	wb8tyw@qsl.net

z/OS (OS/390) Contact:
	Daniel Richard G.
	skunk@iSKUNK.ORG

Thu Jun 20 11:01:04 IDT 2019
Wed Aug 23 08:07:18 IDT 2017
============================

If you are reading this, you have retrieved the gawk code base via
Git from savannah.gnu.org.  This is good; gawk no longer uses CVS.

On GNU and Unix systems, please use the following to build
gawk after doing `git clone' or `git pull':

	make distclean		# if not a new clone
	./bootstrap.sh && ./configure && make && make check

On systems supported by configuration files in the pc/ subdirectory,
chdir into pc/ and run the make-config.bat script there.  This will produce
an up-to-date version of config.h from the latest configh.in.  Then
proceed as described in README_d/README.pc.

Bug reports should be sent to bug-gawk@gnu.org. Note that posting in
comp.lang.awk is generally a bad idea, no matter what the purpose, but
especially if you wish to report a gawk bug. Use the above email address.
Really.

You can find gawk's GIT repository at Savannah
https://savannah.gnu.org/git/?group=gawk

Detailed instructions on using and contributing to gawk can also be
found at Savannah, see http://savannah.gnu.org/maintenance/UsingGit

Thanks,

Arnold Robbins
Gawk Maintainer

=====================================================================
Here are some questions and answers related to using git compiled
by several of the gawk maintainers.

- I don't want to mess with git. Can I just get a tarball of a branch without
  a lot of hassle?

Yes.  Use something like this:

	wget http://git.savannah.gnu.org/cgit/gawk.git/snapshot/gawk-BRANCH-NAME.tar.gz

Put the right thing in place of BRANCH-NAME.

- How can I check out the GIT repository ?

Depending upon your working habits, there are several options.
1. On the Linux command line use the git command (details see below)
2. With Microsoft Windows, use TortoiseGIT
3. On both platforms Eclipse with its EGIT plugin is an excellent choice

On the Linux command line use git to check out the repository.
With Microsoft Windows, use TortoiseGIT.


- Where is TortoiseGIT and how do I install it ?

Follow these instructions for installation:
  https://github.com/multitheftauto/multitheftauto/wiki/how-to-use-tortoisegit

Begin with installing Putty, then msysgit and finally TortoiseGIT.
Find Putty at http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html


- What about the SSH keys needed when Windows is my primary environment ?

On Windows you may use Puttygen for generating keys.
Save both keys (public and private) in a local .ppk file.
Notice that this file is highly confidential and even other
team members are not supposed to see your keys.
Finally you need to convert Putty's keys (.ppk file) so that they
can also be used on Linux.
  http://www.laszlomolnar.name/open-source/tips-and-tutorials/how-to-convert-puttys-private-key-ppk-into-opensshs-private-key-format-in-linux.html

  puttygen my_keys.ppk -O private-openssh -o .ssh/id_rsa
  puttygen my_keys.ppk -O public-openssh  -o .ssh/id_rsa.pub


- What about the SSH keys needed when Linux is my primary environment ?

On Linux follow these instructions to generate keys:
http://www.guyrutenberg.com/2007/10/05/ssh-keygen-tutorial-generating-rsa-and-dsa-keys/
If you ever need these keys inside a Windows environment, use Puttygen
to import the already existing keys.


- I know Subversion, now what's different with git ?

Read the "Git - SVN Crash Course". It lists the Subversion commands that
are roughly equivalent to certain git commands:
  http://www.pronego.com/helpdesk/knowledgebase.php?article=49
This document is only one of many copies of the document on the Internet.
You should read the original (which is currently offline and unreachable):
  https://git.wiki.kernel.org/index.php/GitSvnCrashCourse


- How can I check out this repository inside a clean subdirectory ?

  mkdir -p workspace/git
  cd workspace/git
  git clone git://git.sv.gnu.org/project.git

  git remote -v
  origin  ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git (fetch)
  origin  ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git (push)


- How can I check out this repository with Eclipse ?

Use the most recent version of Eclipse, it already comes with the
EGIT plugin installed.
   Select File -> Import -> Git -> Git Repository.
   Press clone and maintain the git repository "ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git".
   You only have to paste the URL to the first line of the dialog,
   the rest will be filled out automatically.

You can find details in the EGIT tutorial.
  http://www.vogella.de/articles/EGit/article.html#respository_checkoutproject


- Can I start adding new files to the repository right now ?
Yes, you can, but you should not do so.
Convention with branches.

But first you should make sure some global settings identifying
you are set. The global settings will be used every time you commit
something to the repository.

  git config --global user.name "First-Name Last-Name"
  git config --global user.email email@address.site
  git config --global color.ui auto


- How can I inspect my settings ?


  git config --list
  giggle.main-window-maximized=false
  giggle.main-window-geometry=1369x753+183+81
  giggle.main-window-view=HistoryView
  giggle.history-view-vpane-position=389
  giggle.file-view-vpane-position=293
  user.name=First-Name Last-Name
  user.email=email@address.site
  color.diff=auto
  color.status=auto
  color.branch=auto
  gui.spellingdictionary=en_US
  core.repositoryformatversion=0
  core.filemode=true
  core.bare=false
  core.logallrefupdates=true
  remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
  remote.origin.url=ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git
  branch.master.remote=origin
  branch.master.merge=refs/heads/master
  branch.xgawk_load.remote=origin
  branch.xgawk_load.merge=refs/heads/xgawk_load


- How can I get or set a specific variable of the settings ?

  git config --get color.ui
  git config --set color.ui auto


- How can I create new files or directories to the repository ?

  touch README
  git add README
  git commit -m "first commit"


- What did I change since the last commit ?

  git diff README
  git diff


- I have committed everything to my local repository, now how can I
  "push" these changes up to gawk.git ?

  git push -u origin master              # push up to master branch
  git push -u origin my_feature_branch   # push up to my own branch


- How can I inspect the list of branches of my repository ?

  git branch                # shows all local branches
  git branch -r             # shows all remote branches
  git branch -a             # shows all local and all remote branches


- How can I change to a different branch ?

  git checkout    my_stuff  # change to branch my_stuff
  git checkout -b my_stuff  # create new branch my_stuff and change to it

- How can I pull patches from a branch ?

  git pull origin feature_branch

The name of the branch can be omitted if your current branch is
created to track the feature_branch ("git branch -t", see below).

- How can I create a branch ?

For each new feature to be considered for inclusion into future
releasses, a new branch shall be created. Upon creation, this new
branch shall be based on the master branch.

  # make master branch the base
  git checkout master
  # create new feature branch and connect local to upstream branch
  git branch -t my_new_feature_branch
  touch my_new_file.c
  git add my_new_file.c
  git status
  git commit -m "Created new feature branch."
  git push -u origin my_new_feature_branch
  git checkout my_new_feature_branch


- How can I merge recent patches from the master branch ?

My feature branch has been created as describe above (based on master).
While I committed and pushed up my changes, the master branch has also changed.
Now I want to catch up with recent changes in the master branch.

  git diff  origin/master                   # What is in master that I don't have ?
  git merge origin/master                   # Merge all master patches into local rep
  git push -u origin my_new_feature_branch  # Push these local changes up


- How can I throw away an obsolete branch ?

  git push origin :newfeature      # remove remote branch
  git checkout -f master           # switch back from newfeature to master, ignoring changes
  git branch -D newfeature         # remove local branch


- I have made stupid changes to a file and want the original back, how ?

  git checkout file_name.ext

  This will only work if the file was not yet committed.
  If you have already committed the change and want back the
  last pushed version, use "git reset" instead. 

- I have committed stupid changes, how can I  undo the "git commit" ?

  http://stackoverflow.com/questions/927358/git-undo-last-commit


- Who changed a specific line in my file ?

Sometimes you need to find out whom to blame for a certain line of a change.
git can tell you for each line who did the most recent change of the line.

  git blame README


- Who else has ever changed my file, when and why ?

You can inspect the log history file-wise but also directory-wise.

  git log README
  git log


- How to fix a broken repository ?

  git fsck

- How to clean up my repository (garbage collection) ?

  git gc

- How can I change settings with an editor (without "git xxx" command) ?

This is useful for inspecting the settings of local and remote branches that track each other.

  vi .git/config

- I'm a devoted user of Bazaar, and don't want to switch to git.  Is
  there any way for me to track Gawk development with bzr?

Yes, there is.  First, install the latest version of bzr (2.5.0 or
later is required).  If it doesn't come with the bzr-git plugin,
download and install it from https://launchpad.net/bzr-git.  You will
also need dulwich, which is a Python implementation of the git
protocol; get it from http://www.samba.org/~jelmer/dulwich/.

(To know whether you have bzr-git, type "bzr plugins".)

Next, clone the Gawk git repository with this command:

  bzr git-import git://git.savannah.gnu.org/gawk.git gawk

This will create a directory called 'gawk' with meta-data of the
repository, but without any working trees.  To checkout the files,
chdir to that directory and type:

  bzr checkout

This will checkout the files for the default branch.  To see the list
of branches, type

  bzr branches

To switch to another branch, type

  bzr switch --force BRANCH

where BRANCH is the name of the branch, e.g. 'xgawk'.  (The --force
option is a workaround for an annoying misfeature in bzr 2.5.0, which
will most probably be resolved in the near future.)

To sync the current branch with upstream, type

  bzr pull

If you want to update several branches, "bzr switch" to each one in
turn, followed by "bzr pull" to sync the branch.

- How do I manage things if I want to undo a commit?

It depends upon if you have pushed the commit or not. Lots of good
info is at http://stackoverflow.com/questions/927358/git-undo-last-commit .

- What is the difference between using `git rebase' and `git merge' ?

Both of these can be used to bring one branch up to date with respect
to another.  For example, if you are working on a feature branch based
off master, and master has since progressed, you can use

	git checkout feature
	git merge master

or

	git checkout feature
	git rebase master

In the end, you will have your changes on top of the current version of
master in the feature branch.

So which to use?  The answer depends on whether your feature branch
has been pushed up to the Savannah repo or not.

If your branch is completely local to your machine, use `git rebase'.
Otherwise, use `git merge'.

- How do I remove branches in my local repo that are no longer in the
  remote repo?

  Either
  	git fetch --prune
  or
  	git remote prune origin

  These remove the remote branches (i.e., origin/something)
  that no longer exist on the remote.

  (Thanks to Stepan Kasal for this answer.)

Indexes created Tue Jan 21 17:23:38 MST 2020