Add release notes to the distribution.
This also adds a hook in the Makefile I can use to automatically include pointers to documentation for older releases when updating the pages at http://kernel.org/pub/software/scm/git/docs/. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Feb 13, 2007 at 15:15 UTC
26cfcfbff451a67412d2570759250a7418f648d2
5 files changed
+490
-2
Documentation/Makefile
+2
-1
@@ -32,6 +32,7 @@ man7dir=$(mandir)/man7
32
# DESTDIR=
33
34
ASCIIDOC=asciidoc
35
+ASCIIDOC_EXTRA =
36
INSTALL?=install
37
DOC_REF = origin/man
38
@@ -92,7 +93,7 @@ clean:
93
rm -f $(cmds_txt)
94
95
%.html : %.txt
95
- $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $<
96
+ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<
97
98
%.1 %.7 : %.xml
99
xmlto -m callouts.xsl man $<
Documentation/RelNotes-1.5.0.txt
new
+468
@@ -0,0 +1,468 @@
1
+GIT v1.5.0 Release Notes
2
+========================
3
+
4
+Old news
5
+--------
6
+
7
+This section is for people who are upgrading from ancient
8
+versions of git. Although all of the changes in this section
9
+happened before the current v1.4.4 release, they are summarized
10
+here in the v1.5.0 release notes for people who skipped earlier
11
+versions.
12
+
13
+As of git v1.5.0 there are some optional features that changes
14
+the repository to allow data to be stored and transferred more
15
+efficiently. These features are not enabled by default, as they
16
+will make the repository unusable with older versions of git.
17
+Specifically, the available options are:
18
+
19
+ - There is a configuration variable core.legacyheaders that
20
+ changes the format of loose objects so that they are more
21
+ efficient to pack and to send out of the repository over git
22
+ native protocol, since v1.4.2. However, loose objects
23
+ written in the new format cannot be read by git older than
24
+ that version; people fetching from your repository using
25
+ older clients over dumb transports (e.g. http) using older
26
+ versions of git will also be affected.
27
+
28
+ - Since v1.4.3, configuration repack.usedeltabaseoffset allows
29
+ packfile to be created in more space efficient format, which
30
+ cannot be read by git older than that version.
31
+
32
+The above two are not enabled by default and you explicitly have
33
+to ask for them, because these two features make repositories
34
+unreadable by older versions of git, and in v1.5.0 we still do
35
+not enable them by default for the same reason. We will change
36
+this default probably 1 year after 1.4.2's release, when it is
37
+reasonable to expect everybody to have new enough version of
38
+git.
39
+
40
+ - 'git pack-refs' appeared in v1.4.4; this command allows tags
41
+ to be accessed much more efficiently than the traditional
42
+ 'one-file-per-tag' format. Older git-native clients can
43
+ still fetch from a repository that packed and pruned refs
44
+ (the server side needs to run the up-to-date version of git),
45
+ but older dumb transports cannot. Packing of refs is done by
46
+ an explicit user action, either by use of "git pack-refs
47
+ --prune" command or by use of "git gc" command.
48
+
49
+ - 'git -p' to paginate anything -- many commands do pagination
50
+ by default on a tty. Introduced between v1.4.1 and v1.4.2;
51
+ this may surprise old timers.
52
+
53
+ - 'git archive' superseded 'git tar-tree' in v1.4.3;
54
+
55
+ - 'git cvsserver' was new invention in v1.3.0;
56
+
57
+ - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were
58
+ seriously enhanced during v1.4.0 timeperiod.
59
+
60
+ - 'gitweb' became part of git.git during v1.4.0 timeperiod and
61
+ seriously modified since then.
62
+
63
+ - reflog is an v1.4.0 invention. This allows you to name a
64
+ revision that a branch used to be at (e.g. "git diff
65
+ master@{yesterday} master" allows you to see changes since
66
+ yesterday's tip of the branch).
67
+
68
+
69
+Updates in v1.5.0 since v1.4.4 series
70
+-------------------------------------
71
+
72
+* Index manipulation
73
+
74
+ - git-add is to add contents to the index (aka "staging area"
75
+ for the next commit), whether the file the contents happen to
76
+ be is an existing one or a newly created one.
77
+
78
+ - git-add without any argument does not add everything
79
+ anymore. Use 'git-add .' instead. Also you can add
80
+ otherwise ignored files with an -f option.
81
+
82
+ - git-add tries to be more friendly to users by offering an
83
+ interactive mode ("git-add -i").
84
+
85
+ - git-commit <path> used to refuse to commit if <path> was
86
+ different between HEAD and the index (i.e. update-index was
87
+ used on it earlier). This check was removed.
88
+
89
+ - git-rm is much saner and safer. It is used to remove paths
90
+ from both the index file and the working tree, and makes sure
91
+ you are not losing any local modification before doing so.
92
+
93
+ - git-reset <tree> <paths>... can be used to revert index
94
+ entries for selected paths.
95
+
96
+ - git-update-index is much less visible. Many suggestions to
97
+ use the command in git output and documentation have now been
98
+ replaced by simpler commands such as "git add" or "git rm".
99
+
100
+
101
+* Repository layout and objects transfer
102
+
103
+ - The data for origin repository is stored in the configuration
104
+ file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly
105
+ created clones. The latter is still supported and there is
106
+ no need to convert your existing repository if you are
107
+ already comfortable with your workflow with the layout.
108
+
109
+ - git-clone always uses what is known as "separate remote"
110
+ layout for a newly created repository with a working tree.
111
+
112
+ A repository with the separate remote layout starts with only
113
+ one default branch, 'master', to be used for your own
114
+ development. Unlike the traditional layout that copied all
115
+ the upstream branches into your branch namespace (while
116
+ renaming their 'master' to your 'origin'), the new layout
117
+ puts upstream branches into local "remote-tracking branches"
118
+ with their own namespace. These can be referenced with names
119
+ such as "origin/$upstream_branch_name" and are stored in
120
+ .git/refs/remotes rather than .git/refs/heads where normal
121
+ branches are stored.
122
+
123
+ This layout keeps your own branch namespace less cluttered,
124
+ avoids name collision with your upstream, makes it possible
125
+ to automatically track new branches created at the remote
126
+ after you clone from it, and makes it easier to interact with
127
+ more than one remote repository (you can use "git remote" to
128
+ add other repositories to track). There might be some
129
+ surprises:
130
+
131
+ * 'git branch' does not show the remote tracking branches.
132
+ It only lists your own branches. Use '-r' option to view
133
+ the tracking branches.
134
+
135
+ * If you are forking off of a branch obtained from the
136
+ upstream, you would have done something like 'git branch
137
+ my-next next', because traditional layout dropped the
138
+ tracking branch 'next' into your own branch namespace.
139
+ With the separate remote layout, you say 'git branch next
140
+ origin/next', which allows you to use the matching name
141
+ 'next' for your own branch. It also allows you to track a
142
+ remote other than 'origin' (i.e. where you initially cloned
143
+ from) and fork off of a branch from there the same way
144
+ (e.g. "git branch mingw j6t/master").
145
+
146
+ Repositories initialized with the traditional layout continue
147
+ to work.
148
+
149
+ - New branches that appear on the origin side after a clone is
150
+ made are also tracked automatically. This is done with an
151
+ wildcard refspec "refs/heads/*:refs/remotes/origin/*", which
152
+ older git does not understand, so if you clone with 1.5.0,
153
+ you would need to downgrade remote.*.fetch in the
154
+ configuration file to specify each branch you are interested
155
+ in individually if you plan to fetch into the repository with
156
+ older versions of git (but why would you?).
157
+
158
+ - Similarly, wildcard refspec "refs/heads/*:refs/remotes/me/*"
159
+ can be given to "git-push" command to update the tracking
160
+ branches that is used to track the repository you are pushing
161
+ from on the remote side.
162
+
163
+ - git-branch and git-show-branch know remote tracking branches
164
+ (use the command line switch "-r" to list only tracked branches).
165
+
166
+ - git-push can now be used to delete a remote branch or a tag.
167
+ This requires the updated git on the remote side (use "git
168
+ push <remote> :refs/heads/<branch>" to delete "branch").
169
+
170
+ - git-push more aggressively keeps the transferred objects
171
+ packed. Earlier we recommended to monitor amount of loose
172
+ objects and repack regularly, but you should repack when you
173
+ accumulated too many small packs this way as well. Updated
174
+ git-count-objects helps you with this.
175
+
176
+ - git-fetch also more aggressively keeps the transferred objects
177
+ packed. This behavior of git-push and git-fetch can be
178
+ tweaked with a single configuration transfer.unpacklimit (but
179
+ usually there should not be any need for a user to tweak it).
180
+
181
+ - A new command, git-remote, can help you manage your remote
182
+ tracking branch definitions.
183
+
184
+ - You may need to specify explicit paths for upload-pack and/or
185
+ receive-pack due to your ssh daemon configuration on the
186
+ other end. This can now be done via remote.*.uploadpack and
187
+ remote.*.receivepack configuration.
188
+
189
+
190
+* Bare repositories
191
+
192
+ - Certain commands change their behavior in a bare repository
193
+ (i.e. a repository without associated working tree). We use
194
+ a fairly conservative heuristic (if $GIT_DIR is ".git", or
195
+ ends with "/.git", the repository is not bare) to decide if a
196
+ repository is bare, but "core.bare" configuration variable
197
+ can be used to override the heuristic when it misidentifies
198
+ your repository.
199
+
200
+ - git-fetch used to complain updating the current branch but
201
+ this is now allowed for a bare repository. So is the use of
202
+ 'git-branch -f' to update the current branch.
203
+
204
+ - Porcelain-ish commands that require a working tree refuses to
205
+ work in a bare repository.
206
+
207
+
208
+* Reflog
209
+
210
+ - Reflog records the history from the view point of the local
211
+ repository. In other words, regardless of the real history,
212
+ the reflog shows the history as seen by one particular
213
+ repository (this enables you to ask "what was the current
214
+ revision in _this_ repository, yesterday at 1pm?"). This
215
+ facility is enabled by default for repositories with working
216
+ trees, and can be accessed with the "branch@{time}" and
217
+ "branch@{Nth}" notation.
218
+
219
+ - "git show-branch" learned showing the reflog data with the
220
+ new -g option. "git log" has -s option to view reflog
221
+ entries in a more verbose manner.
222
+
223
+ - git-branch knows how to rename branches and moves existing
224
+ reflog data from the old branch to the new one.
225
+
226
+ - In addition to the reflog support in v1.4.4 series, HEAD
227
+ reference maintains its own log. "HEAD@{5.minutes.ago}"
228
+ means the commit you were at 5 minutes ago, which takes
229
+ branch switching into account. If you want to know where the
230
+ tip of your current branch was at 5 minutes ago, you need to
231
+ explicitly say its name (e.g. "master@{5.minutes.ago}") or
232
+ omit the refname altogether i.e. "@{5.minutes.ago}".
233
+
234
+ - The commits referred to by reflog entries are now protected
235
+ against pruning. The new command "git reflog expire" can be
236
+ used to truncate older reflog entries and entries that refer
237
+ to commits that have been pruned away previously with older
238
+ versions of git.
239
+
240
+ Existing repositories that have been using reflog may get
241
+ complaints from fsck-objects and may not be able to run
242
+ git-repack, if you had run git-prune from older git; please
243
+ run "git reflog expire --stale-fix --all" first to remove
244
+ reflog entries that refer to commits that are no longer in
245
+ the repository when that happens.
246
+
247
+
248
+* Crufts removal
249
+
250
+ - We used to say "old commits are retrievable using reflog and
251
+ 'master@{yesterday}' syntax as long as you haven't run
252
+ git-prune". We no longer have to say the latter half of the
253
+ above sentence, as git-prune does not remove things reachable
254
+ from reflog entries.
255
+
256
+ - 'git-prune' by default does not remove _everything_
257
+ unreachable, as there is a one-day grace period built-in.
258
+
259
+ - There is a toplevel garbage collector script, 'git-gc', that
260
+ runs periodic cleanup functions, including 'git-repack -a -d',
261
+ 'git-reflog expire', 'git-pack-refs --prune', and 'git-rerere
262
+ gc'.
263
+
264
+ - The output from fsck ("fsck-objects" is called just "fsck"
265
+ now, but the old name continues to work) was needlessly
266
+ alarming in that it warned missing objects that are reachable
267
+ only from dangling objects. This has been corrected and the
268
+ output is much more useful.
269
+
270
+
271
+* Detached HEAD
272
+
273
+ - You can use 'git-checkout' to check out an arbitrary revision
274
+ or a tag as well, instead of named branches. This will
275
+ dissociate your HEAD from the branch you are currently on.
276
+
277
+ A typical use of this feature is to "look around". E.g.
278
+
279
+ $ git checkout v2.6.16
280
+ ... compile, test, etc.
281
+ $ git checkout v2.6.17
282
+ ... compile, test, etc.
283
+
284
+ - After detaching your HEAD, you can go back to an existing
285
+ branch with usual "git checkout $branch". Also you can
286
+ start a new branch using "git checkout -b $newbranch" to
287
+ start a new branch at that commit.
288
+
289
+ - You can even pull from other repositories, make merges and
290
+ commits while your HEAD is detached. Also you can use "git
291
+ reset" to jump to arbitrary commit, while still keeping your
292
+ HEAD detached.
293
+
294
+ Going back to attached state (i.e. on a particular branch) by
295
+ "git checkout $branch" can lose the current stat you arrived
296
+ in these ways, and "git checkout" refuses when the detached
297
+ HEAD is not pointed by any existing ref (an existing branch,
298
+ a remote tracking branch or a tag). This safety can be
299
+ overridden with "git checkout -f $branch".
300
+
301
+
302
+* Packed refs
303
+
304
+ - Repositories with hundreds of tags have been paying large
305
+ overhead, both in storage and in runtime, due to the
306
+ traditional one-ref-per-file format. A new command,
307
+ git-pack-refs, can be used to "pack" them in more efficient
308
+ representation (you can let git-gc do this for you).
309
+
310
+ - Clones and fetches over dumb transports are now aware of
311
+ packed refs and can download from repositories that use
312
+ them.
313
+
314
+
315
+* Configuration
316
+
317
+ - configuration related to color setting are consolidated under
318
+ color.* namespace (older diff.color.*, status.color.* are
319
+ still supported).
320
+
321
+ - 'git-repo-config' command is accessible as 'git-config' now.
322
+
323
+
324
+* Updated features
325
+
326
+ - git-describe uses better criteria to pick a base ref. It
327
+ used to pick the one with the newest timestamp, but now it
328
+ picks the one that is topologically the closest (that is,
329
+ among ancestors of commit C, the ref T that has the shortest
330
+ output from "git-rev-list T..C" is chosen).
331
+
332
+ - git-describe gives the number of commits since the base ref
333
+ between the refname and the hash suffix. E.g. the commit one
334
+ before v2.6.20-rc6 in the kernel repository is:
335
+
336
+ v2.6.20-rc5-306-ga21b069
337
+
338
+ which tells you that its object name begins with a21b069,
339
+ v2.6.20-rc5 is an ancestor of it (meaning, the commit
340
+ contains everything -rc5 has), and there are 306 commits
341
+ since v2.6.20-rc5.
342
+
343
+ - git-describe with --abbrev=0 can be used to show only the
344
+ name of the base ref.
345
+
346
+ - git-blame learned a new option, --incremental, that tells it
347
+ to output the blames as they are assigned. A sample script
348
+ to use it is also included as contrib/blameview.
349
+
350
+ - git-blame starts annotating from the working tree by default.
351
+
352
+
353
+* Less external dependency
354
+
355
+ - We no longer require the "merge" program from the RCS suite.
356
+ All 3-way file-level merges are now done internally.
357
+
358
+ - The original implementation of git-merge-recursive which was
359
+ in Python has been removed; we have a C implementation of it
360
+ now.
361
+
362
+ - git-shortlog is no longer a Perl script. It no longer
363
+ requires output piped from git-log; it can accept revision
364
+ parameters directly on the command line.
365
+
366
+
367
+* I18n
368
+
369
+ - We have always encouraged the commit message to be encoded in
370
+ UTF-8, but the users are allowed to use legacy encoding as
371
+ appropriate for their projects. This will continue to be the
372
+ case. However, a non UTF-8 commit encoding _must_ be
373
+ explicitly set with i18n.commitencoding in the repository
374
+ where a commit is made; otherwise git-commit-tree will
375
+ complain if the log message does not look like a valid UTF-8
376
+ string.
377
+
378
+ - The value of i18n.commitencoding in the originating
379
+ repository is recorded in the commit object on the "encoding"
380
+ header, if it is not UTF-8. git-log and friends notice this,
381
+ and reencodes the message to the log output encoding when
382
+ displaying, if they are different. The log output encoding
383
+ is determined by "git log --encoding=<encoding>",
384
+ i18n.logoutputencoding configuration, or i18n.commitencoding
385
+ configuration, in the decreasing order of preference, and
386
+ defaults to UTF-8.
387
+
388
+ - Tools for e-mailed patch application now default to -u
389
+ behavior; i.e. it always re-codes from the e-mailed encoding
390
+ to the encoding specified with i18n.commitencoding. This
391
+ unfortunately forces projects that have happily been using a
392
+ legacy encoding without setting i18n.commitencoding to set
393
+ the configuration, but taken with other improvement, please
394
+ excuse us for this very minor one-time inconvenience.
395
+
396
+
397
+* e-mailed patches
398
+
399
+ - See the above I18n section.
400
+
401
+ - git-format-patch now enables --binary without being asked.
402
+ git-am does _not_ default to it, as sending binary patch via
403
+ e-mail is unusual and is harder to review than textual
404
+ patches and it is prudent to require the person who is
405
+ applying the patch to explicitly ask for it.
406
+
407
+ - The default suffix for git-format-patch output is now ".patch",
408
+ not ".txt". This can be changed with --suffix=.txt option,
409
+ or setting the config variable "format.suffix" to ".txt".
410
+
411
+
412
+* Foreign SCM interfaces
413
+
414
+ - git-svn now requires the Perl SVN:: libraries, the
415
+ command-line backend was too slow and limited.
416
+
417
+ - the 'commit' subcommand of git-svn has been renamed to
418
+ 'set-tree', and 'dcommit' is the recommended replacement for
419
+ day-to-day work.
420
+
421
+ - git fast-import backend.
422
+
423
+
424
+* User support
425
+
426
+ - Quite a lot of documentation updates.
427
+
428
+ - Bash completion scripts have been updated heavily.
429
+
430
+ - Better error messages for often used Porcelainish commands.
431
+
432
+ - Git GUI. This is a simple Tk based graphical interface for
433
+ common Git operations.
434
+
435
+
436
+* Sliding mmap
437
+
438
+ - We used to assume that we can mmap the whole packfile while
439
+ in use, but with a large project this consumes huge virtual
440
+ memory space and truly huge ones would not fit in the
441
+ userland address space on 32-bit platforms. We now mmap huge
442
+ packfile in pieces to avoid this problem.
443
+
444
+
445
+* Shallow clones
446
+
447
+ - There is a partial support for 'shallow' repositories that
448
+ keeps only recent history. A 'shallow clone' is created by
449
+ specifying how deep that truncated history should be
450
+ (e.g. "git clone --depth=5 git://some.where/repo.git").
451
+
452
+ Currently a shallow repository has number of limitations:
453
+
454
+ - Cloning and fetching _from_ a shallow clone are not
455
+ supported (nor tested -- so they might work by accident but
456
+ they are not expected to).
457
+
458
+ - Pushing from nor into a shallow clone are not expected to
459
+ work.
460
+
461
+ - Merging inside a shallow repository would work as long as a
462
+ merge base is found in the recent history, but otherwise it
463
+ will be like merging unrelated histories and may result in
464
+ huge conflicts.
465
+
466
+ but this would be more than adequate for people who want to
467
+ look at near the tip of a big project with a deep history and
468
+ send patches in e-mail format.
Documentation/git.txt
+18
@@ -29,6 +29,24 @@ in a coherent way to git enlightenment ;-).
29
The COMMAND is either a name of a Git command (see below) or an alias
30
as defined in the configuration file (see gitlink:git-config[1]).
31
32
+ifdef::stalenotes[]
33
+[NOTE]
34
+============
35
+You are reading the documentation for the latest version of git.
36
+Documentation for older releases are available here:
37
+
38
+* link:v1.4.4.4/git.html[documentation for release 1.4.4.4]
39
+
40
+* link:v1.3.3/git.html[documentation for release 1.3.3]
41
+
42
+* link:v1.2.6/git.html[documentation for release 1.2.6]
43
+
44
+* link:v1.0.13/git.html[documentation for release 1.0.13]
45
+
46
+============
47
+
48
+endif::stalenotes[]
49
+
50
OPTIONS
51
-------
52
--version::
Documentation/install-webdoc.sh
+1
-1
@@ -2,7 +2,7 @@
2
3
T="$1"
4
5
-for h in *.html *.txt howto/*.txt howto/*.html
5
+for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt
6
do
7
if test -f "$T/$h" &&
8
diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
RelNotes
new
+1
@@ -0,0 +1 @@
1
+Documentation/RelNotes-1.5.0.txt
\ No newline at end of file