@matheusbsbs / matheus-bagliano / commits / 26cfcfbff4
Fork 0

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