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