README
1 Copyright (C) 2005, 2006, 2007, 2009, 2010, 2011, 2012, 2013, 2014, 2015,
2 2016, 2017, 2018, 2019, 2020, 2021, 2022 Free Software Foundation, Inc.
3
4 Copying and distribution of this file, with or without modification,
5 are permitted in any medium without royalty provided the copyright
6 notice and this notice are preserved.
7
8README:
9
10This is GNU Awk 5.2.0. It is upwardly compatible with Brian Kernighan's
11version of Unix awk. It is almost completely compliant with the
122018 POSIX 1003.1 standard for awk. (See the note below about POSIX.)
13
14This is a major release. See NEWS and ChangeLog for details.
15
16Work to be done is described briefly in the TODO file, which is available
17only in the 'master' branch in the Git repo.
18
19Changes in this version are summarized in the NEWS file.
20
21Read the file POSIX.STD for a discussion of issues where the standard
22says one thing but gawk does something different.
23
24To format the documentation with TeX, use at least version 2019-09-20.22
25of texinfo.tex. There is a usable copy of texinfo.tex in the doc directory.
26You must also use at least version 6.7 of texindex and of makeinfo
27from the texinfo-6.7 distribution.
28
29INSTALLATION:
30
31Check whether there is a system-specific README file for your system under
32the `README_d' directory. If there's something there that you should
33have read and didn't, and you bug me about it, I'm going to yell at you.
34
35See the file INSTALL for installation instructions.
36
37If you don't have Bison, use the awkgram.c file here. It was
38generated with Bison, and has no proprietary code in it. (Note that
39modifying awkgram.y without Bison is next to impossible. You might
40want to get a copy of Bison from the FSF too.)
41
42The build mechanics depend upon Bison. Also, gawk doesn't work correctly
43with some versions of yacc, so just use Bison.
44
45If you have an MS-DOS, MS-Windows, or OS/2 system, use the stuff in the `pc'
46directory. Similarly, there is a separate directory for VMS.
47
48Appendix B of ``GAWK: Effective Awk Programming'' discusses configuration
49in detail. The configuration process is based on GNU Autoconf and
50Automake.
51
52After successful compilation, do `make check' to run the test suite.
53There should be no output from the `cmp' invocations except in the
54cases where there are small differences in floating point values, and
55possibly in the case of strftime. There may be differences based on
56installed (or not installed) locales and the quality of multibyte
57character support on your system.
58
59Several of the tests ignore errors on purpose; those are not a problem.
60If there are other differences, please investigate and report the problem.
61
62PRINTING THE MANUAL
63
64The `doc' directory contains a recent version of texinfo.tex, which will
65be necessary for printing the manual. Use `make dvi' to get a DVI file
66from the manual. In the `doc' directory, use `make postscript' to get
67PostScript versions of the manual, the man page, and the reference card.
68Use `make pdf' to get PDF versions of the manuals, the man page and
69the reference card.
70
71BUG REPORTS AND FIXES (Un*x systems):
72
73Please coordinate changes through Arnold Robbins. In particular, see
74the section in the manual on reporting bugs. Note that comp.lang.awk
75is about the worst place to post a gawk bug report. So too is use of
76a web forum such as Stack Overflow. Please, use the mechanisms outlined
77in the manual.
78
79Bug reports should be submitted using the `gawkbug' script. This formats
80a report and sends it to bug-gawk@gnu.org. This is a separate mailing
81list at GNU Central. The advantage to using this address is that bug
82reports are archived at GNU Central.
83
84General non-bug questions should be sent to help-gawk@gnu.org.
85
86Arnold Robbins
87
88BUG REPORTS AND FIXES, non-Unix systems:
89
90MS-DOS with DJGPP:
91 Juan Manuel Guerrero
92 juan.guerrero@gmx.de
93
94MS-Windows with MinGW:
95 Eli Zaretskii
96 eliz@gnu.org
97
98OS/2:
99 Andreas Buening
100 andreas.buening@nexgo.de
101
102VMS:
103 John Malmberg
104 wb8tyw@qsl.net
105
106z/OS (OS/390) Contact:
107 Daniel Richard G.
108 skunk@iSKUNK.ORG
109
README.git
1Thu Jun 20 11:01:04 IDT 2019
2Wed Aug 23 08:07:18 IDT 2017
3============================
4
5If you are reading this, you have retrieved the gawk code base via
6Git from savannah.gnu.org. This is good; gawk no longer uses CVS.
7
8On GNU and Unix systems, please use the following to build
9gawk after doing `git clone' or `git pull':
10
11 make distclean # if not a new clone
12 ./bootstrap.sh && ./configure && make && make check
13
14On systems supported by configuration files in the pc/ subdirectory,
15chdir into pc/ and run the make-config.bat script there. This will produce
16an up-to-date version of config.h from the latest configh.in. Then
17proceed as described in README_d/README.pc.
18
19Bug reports should be sent to bug-gawk@gnu.org. Note that posting in
20comp.lang.awk is generally a bad idea, no matter what the purpose, but
21especially if you wish to report a gawk bug. Use the above email address.
22Really.
23
24You can find gawk's GIT repository at Savannah
25https://savannah.gnu.org/git/?group=gawk
26
27Detailed instructions on using and contributing to gawk can also be
28found at Savannah, see http://savannah.gnu.org/maintenance/UsingGit
29
30Thanks,
31
32Arnold Robbins
33Gawk Maintainer
34
35=====================================================================
36Here are some questions and answers related to using git compiled
37by several of the gawk maintainers.
38
39- I don't want to mess with git. Can I just get a tarball of a branch without
40 a lot of hassle?
41
42Yes. Use something like this:
43
44 wget http://git.savannah.gnu.org/cgit/gawk.git/snapshot/gawk-BRANCH-NAME.tar.gz
45
46Put the right thing in place of BRANCH-NAME.
47
48- How can I check out the GIT repository ?
49
50Depending upon your working habits, there are several options.
511. On the Linux command line use the git command (details see below)
522. With Microsoft Windows, use TortoiseGIT
533. On both platforms Eclipse with its EGIT plugin is an excellent choice
54
55On the Linux command line use git to check out the repository.
56With Microsoft Windows, use TortoiseGIT.
57
58
59- Where is TortoiseGIT and how do I install it ?
60
61Follow these instructions for installation:
62 https://github.com/multitheftauto/multitheftauto/wiki/how-to-use-tortoisegit
63
64Begin with installing Putty, then msysgit and finally TortoiseGIT.
65Find Putty at http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
66
67
68- What about the SSH keys needed when Windows is my primary environment ?
69
70On Windows you may use Puttygen for generating keys.
71Save both keys (public and private) in a local .ppk file.
72Notice that this file is highly confidential and even other
73team members are not supposed to see your keys.
74Finally you need to convert Putty's keys (.ppk file) so that they
75can also be used on Linux.
76 http://www.laszlomolnar.name/open-source/tips-and-tutorials/how-to-convert-puttys-private-key-ppk-into-opensshs-private-key-format-in-linux.html
77
78 puttygen my_keys.ppk -O private-openssh -o .ssh/id_rsa
79 puttygen my_keys.ppk -O public-openssh -o .ssh/id_rsa.pub
80
81
82- What about the SSH keys needed when Linux is my primary environment ?
83
84On Linux follow these instructions to generate keys:
85http://www.guyrutenberg.com/2007/10/05/ssh-keygen-tutorial-generating-rsa-and-dsa-keys/
86If you ever need these keys inside a Windows environment, use Puttygen
87to import the already existing keys.
88
89
90- I know Subversion, now what's different with git ?
91
92Read the "Git - SVN Crash Course". It lists the Subversion commands that
93are roughly equivalent to certain git commands:
94 http://www.pronego.com/helpdesk/knowledgebase.php?article=49
95This document is only one of many copies of the document on the Internet.
96You should read the original (which is currently offline and unreachable):
97 https://git.wiki.kernel.org/index.php/GitSvnCrashCourse
98
99
100- How can I check out this repository inside a clean subdirectory ?
101
102 mkdir -p workspace/git
103 cd workspace/git
104 git clone git://git.sv.gnu.org/project.git
105
106 git remote -v
107 origin ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git (fetch)
108 origin ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git (push)
109
110
111- How can I check out this repository with Eclipse ?
112
113Use the most recent version of Eclipse, it already comes with the
114EGIT plugin installed.
115 Select File -> Import -> Git -> Git Repository.
116 Press clone and maintain the git repository "ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git".
117 You only have to paste the URL to the first line of the dialog,
118 the rest will be filled out automatically.
119
120You can find details in the EGIT tutorial.
121 http://www.vogella.de/articles/EGit/article.html#respository_checkoutproject
122
123
124- Can I start adding new files to the repository right now ?
125Yes, you can, but you should not do so.
126Convention with branches.
127
128But first you should make sure some global settings identifying
129you are set. The global settings will be used every time you commit
130something to the repository.
131
132 git config --global user.name "First-Name Last-Name"
133 git config --global user.email email@address.site
134 git config --global color.ui auto
135
136
137- How can I inspect my settings ?
138
139
140 git config --list
141 giggle.main-window-maximized=false
142 giggle.main-window-geometry=1369x753+183+81
143 giggle.main-window-view=HistoryView
144 giggle.history-view-vpane-position=389
145 giggle.file-view-vpane-position=293
146 user.name=First-Name Last-Name
147 user.email=email@address.site
148 color.diff=auto
149 color.status=auto
150 color.branch=auto
151 gui.spellingdictionary=en_US
152 core.repositoryformatversion=0
153 core.filemode=true
154 core.bare=false
155 core.logallrefupdates=true
156 remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
157 remote.origin.url=ssh://jkahrs@git.sv.gnu.org/srv/git/gawk.git
158 branch.master.remote=origin
159 branch.master.merge=refs/heads/master
160 branch.xgawk_load.remote=origin
161 branch.xgawk_load.merge=refs/heads/xgawk_load
162
163
164- How can I get or set a specific variable of the settings ?
165
166 git config --get color.ui
167 git config --set color.ui auto
168
169
170- How can I create new files or directories to the repository ?
171
172 touch README
173 git add README
174 git commit -m "first commit"
175
176
177- What did I change since the last commit ?
178
179 git diff README
180 git diff
181
182
183- I have committed everything to my local repository, now how can I
184 "push" these changes up to gawk.git ?
185
186 git push -u origin master # push up to master branch
187 git push -u origin my_feature_branch # push up to my own branch
188
189
190- How can I inspect the list of branches of my repository ?
191
192 git branch # shows all local branches
193 git branch -r # shows all remote branches
194 git branch -a # shows all local and all remote branches
195
196
197- How can I change to a different branch ?
198
199 git checkout my_stuff # change to branch my_stuff
200 git checkout -b my_stuff # create new branch my_stuff and change to it
201
202- How can I pull patches from a branch ?
203
204 git pull origin feature_branch
205
206The name of the branch can be omitted if your current branch is
207created to track the feature_branch ("git branch -t", see below).
208
209- How can I create a branch ?
210
211For each new feature to be considered for inclusion into future
212releasses, a new branch shall be created. Upon creation, this new
213branch shall be based on the master branch.
214
215 # make master branch the base
216 git checkout master
217 # create new feature branch and connect local to upstream branch
218 git branch -t my_new_feature_branch
219 touch my_new_file.c
220 git add my_new_file.c
221 git status
222 git commit -m "Created new feature branch."
223 git push -u origin my_new_feature_branch
224 git checkout my_new_feature_branch
225
226
227- How can I merge recent patches from the master branch ?
228
229My feature branch has been created as describe above (based on master).
230While I committed and pushed up my changes, the master branch has also changed.
231Now I want to catch up with recent changes in the master branch.
232
233 git diff origin/master # What is in master that I don't have ?
234 git merge origin/master # Merge all master patches into local rep
235 git push -u origin my_new_feature_branch # Push these local changes up
236
237
238- How can I throw away an obsolete branch ?
239
240 git push origin :newfeature # remove remote branch
241 git checkout -f master # switch back from newfeature to master, ignoring changes
242 git branch -D newfeature # remove local branch
243
244
245- I have made stupid changes to a file and want the original back, how ?
246
247 git checkout file_name.ext
248
249 This will only work if the file was not yet committed.
250 If you have already committed the change and want back the
251 last pushed version, use "git reset" instead.
252
253- I have committed stupid changes, how can I undo the "git commit" ?
254
255 http://stackoverflow.com/questions/927358/git-undo-last-commit
256
257
258- Who changed a specific line in my file ?
259
260Sometimes you need to find out whom to blame for a certain line of a change.
261git can tell you for each line who did the most recent change of the line.
262
263 git blame README
264
265
266- Who else has ever changed my file, when and why ?
267
268You can inspect the log history file-wise but also directory-wise.
269
270 git log README
271 git log
272
273
274- How to fix a broken repository ?
275
276 git fsck
277
278- How to clean up my repository (garbage collection) ?
279
280 git gc
281
282- How can I change settings with an editor (without "git xxx" command) ?
283
284This is useful for inspecting the settings of local and remote branches that track each other.
285
286 vi .git/config
287
288- I'm a devoted user of Bazaar, and don't want to switch to git. Is
289 there any way for me to track Gawk development with bzr?
290
291Yes, there is. First, install the latest version of bzr (2.5.0 or
292later is required). If it doesn't come with the bzr-git plugin,
293download and install it from https://launchpad.net/bzr-git. You will
294also need dulwich, which is a Python implementation of the git
295protocol; get it from http://www.samba.org/~jelmer/dulwich/.
296
297(To know whether you have bzr-git, type "bzr plugins".)
298
299Next, clone the Gawk git repository with this command:
300
301 bzr git-import git://git.savannah.gnu.org/gawk.git gawk
302
303This will create a directory called 'gawk' with meta-data of the
304repository, but without any working trees. To checkout the files,
305chdir to that directory and type:
306
307 bzr checkout
308
309This will checkout the files for the default branch. To see the list
310of branches, type
311
312 bzr branches
313
314To switch to another branch, type
315
316 bzr switch --force BRANCH
317
318where BRANCH is the name of the branch, e.g. 'xgawk'. (The --force
319option is a workaround for an annoying misfeature in bzr 2.5.0, which
320will most probably be resolved in the near future.)
321
322To sync the current branch with upstream, type
323
324 bzr pull
325
326If you want to update several branches, "bzr switch" to each one in
327turn, followed by "bzr pull" to sync the branch.
328
329- How do I manage things if I want to undo a commit?
330
331It depends upon if you have pushed the commit or not. Lots of good
332info is at http://stackoverflow.com/questions/927358/git-undo-last-commit .
333
334- What is the difference between using `git rebase' and `git merge' ?
335
336Both of these can be used to bring one branch up to date with respect
337to another. For example, if you are working on a feature branch based
338off master, and master has since progressed, you can use
339
340 git checkout feature
341 git merge master
342
343or
344
345 git checkout feature
346 git rebase master
347
348In the end, you will have your changes on top of the current version of
349master in the feature branch.
350
351So which to use? The answer depends on whether your feature branch
352has been pushed up to the Savannah repo or not.
353
354If your branch is completely local to your machine, use `git rebase'.
355Otherwise, use `git merge'.
356
357- How do I remove branches in my local repo that are no longer in the
358 remote repo?
359
360 Either
361 git fetch --prune
362 or
363 git remote prune origin
364
365 These remove the remote branches (i.e., origin/something)
366 that no longer exist on the remote.
367
368 (Thanks to Stepan Kasal for this answer.)
369