0989ded497291714cc9a30c4e29f237c75470280
   1GIT v1.5.0 Release Notes
   2========================
   3
   4Old news
   5--------
   6
   7This section is for people who are upgrading from ancient
   8versions of git.  Although all of the changes in this section
   9happened before the current v1.4.4 release, they are summarized
  10here in the v1.5.0 release notes for people who skipped earlier
  11versions.
  12
  13As of git v1.5.0 there are some optional features that changes
  14the repository to allow data to be stored and transferred more
  15efficiently.  These features are not enabled by default, as they
  16will make the repository unusable with older versions of git.
  17Specifically, 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   To let git use the new loose object format, you have to
  29   set core.legacyheaders to false.
  30
  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.
  34
  35   To let git use the new format for packfiles, you have to
  36   set repack.usedeltabaseoffset to true.
  37
  38The above two new features are not enabled by default and you
  39have explicitly to ask for them, because they make repositories
  40unreadable by older versions of git, and in v1.5.0 we still do
  41not enable them by default for the same reason.  We will change
  42this default probably 1 year after 1.4.2's release, when it is
  43reasonable to expect everybody to have new enough version of
  44git.
  45
  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.
  54
  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.
  58
  59 - 'git archive' superseded 'git tar-tree' in v1.4.3;
  60
  61 - 'git cvsserver' was new invention in v1.3.0;
  62
  63 - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were
  64   seriously enhanced during v1.4.0 timeperiod.
  65
  66 - 'gitweb' became part of git.git during v1.4.0 timeperiod and
  67   seriously modified since then.
  68
  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).
  73
  74
  75Updates in v1.5.0 since v1.4.4 series
  76-------------------------------------
  77
  78* Index manipulation
  79
  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.
  83
  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.
  87
  88 - git-add tries to be more friendly to users by offering an
  89   interactive mode ("git-add -i").
  90
  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.
  94
  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.
  98
  99 - git-reset <tree> <paths>... can be used to revert index
 100   entries for selected paths.
 101
 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".
 105
 106
 107* Repository layout and objects transfer
 108
 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.
 114
 115 - git-clone always uses what is known as "separate remote"
 116   layout for a newly created repository with a working tree.
 117
 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.
 128
 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:
 136
 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.
 140
 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").
 151
 152   Repositories initialized with the traditional layout continue
 153   to work.
 154
 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?).
 163
 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.
 168
 169 - git-branch and git-show-branch know remote tracking branches
 170   (use the command line switch "-r" to list only tracked branches).
 171
 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").
 175
 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.
 181
 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).
 186
 187 - A new command, git-remote, can help you manage your remote
 188   tracking branch definitions.
 189
 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.
 194
 195
 196* Bare repositories
 197
 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.
 205
 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.
 209
 210 - Porcelain-ish commands that require a working tree refuses to
 211   work in a bare repository.
 212
 213
 214* Reflog
 215
 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.
 224
 225 - "git show-branch" learned showing the reflog data with the
 226   new -g option.  "git log" has -s option to view reflog
 227   entries in a more verbose manner.
 228
 229 - git-branch knows how to rename branches and moves existing
 230   reflog data from the old branch to the new one.
 231
 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}".
 239
 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.
 245
 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.
 252
 253
 254* Crufts removal
 255
 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.
 261
 262 - 'git-prune' by default does not remove _everything_
 263   unreachable, as there is a one-day grace period built-in.
 264
 265 - There is a toplevel garbage collector script, 'git-gc', that
 266   runs periodic cleanup functions, including 'git-repack -a -d',
 267   'git-reflog expire', 'git-pack-refs --prune', and 'git-rerere
 268   gc'.
 269
 270 - The output from fsck ("fsck-objects" is called just "fsck"
 271   now, but the old name continues to work) was needlessly
 272   alarming in that it warned missing objects that are reachable
 273   only from dangling objects.  This has been corrected and the
 274   output is much more useful.
 275
 276
 277* Detached HEAD
 278
 279 - You can use 'git-checkout' to check out an arbitrary revision
 280   or a tag as well, instead of named branches.  This will
 281   dissociate your HEAD from the branch you are currently on.
 282
 283   A typical use of this feature is to "look around".  E.g.
 284
 285        $ git checkout v2.6.16
 286        ... compile, test, etc.
 287        $ git checkout v2.6.17
 288        ... compile, test, etc.
 289
 290 - After detaching your HEAD, you can go back to an existing
 291   branch with usual "git checkout $branch".  Also you can
 292   start a new branch using "git checkout -b $newbranch" to
 293   start a new branch at that commit.
 294
 295 - You can even pull from other repositories, make merges and
 296   commits while your HEAD is detached.  Also you can use "git
 297   reset" to jump to arbitrary commit, while still keeping your
 298   HEAD detached.
 299
 300   Remember that a detached state is volatile, i.e. it will be forgotten
 301   as soon as you move away from it with the checkout or reset command,
 302   unless a branch is created from it as mentioned above.  It is also
 303   possible to rescue a lost detached state from the HEAD reflog.
 304
 305
 306* Packed refs
 307
 308 - Repositories with hundreds of tags have been paying large
 309   overhead, both in storage and in runtime, due to the
 310   traditional one-ref-per-file format.  A new command,
 311   git-pack-refs, can be used to "pack" them in more efficient
 312   representation (you can let git-gc do this for you).
 313
 314 - Clones and fetches over dumb transports are now aware of
 315   packed refs and can download from repositories that use
 316   them.
 317
 318
 319* Configuration
 320
 321 - configuration related to color setting are consolidated under
 322   color.* namespace (older diff.color.*, status.color.* are
 323   still supported).
 324
 325 - 'git-repo-config' command is accessible as 'git-config' now.
 326
 327
 328* Updated features
 329
 330 - git-describe uses better criteria to pick a base ref.  It
 331   used to pick the one with the newest timestamp, but now it
 332   picks the one that is topologically the closest (that is,
 333   among ancestors of commit C, the ref T that has the shortest
 334   output from "git-rev-list T..C" is chosen).
 335
 336 - git-describe gives the number of commits since the base ref
 337   between the refname and the hash suffix.  E.g. the commit one
 338   before v2.6.20-rc6 in the kernel repository is:
 339
 340        v2.6.20-rc5-306-ga21b069
 341
 342   which tells you that its object name begins with a21b069,
 343   v2.6.20-rc5 is an ancestor of it (meaning, the commit
 344   contains everything -rc5 has), and there are 306 commits
 345   since v2.6.20-rc5.
 346
 347 - git-describe with --abbrev=0 can be used to show only the
 348   name of the base ref.
 349
 350 - git-blame learned a new option, --incremental, that tells it
 351   to output the blames as they are assigned.  A sample script
 352   to use it is also included as contrib/blameview.
 353
 354 - git-blame starts annotating from the working tree by default.
 355
 356
 357* Less external dependency
 358
 359 - We no longer require the "merge" program from the RCS suite.
 360   All 3-way file-level merges are now done internally.
 361
 362 - The original implementation of git-merge-recursive which was
 363   in Python has been removed; we have a C implementation of it
 364   now.
 365
 366 - git-shortlog is no longer a Perl script.  It no longer
 367   requires output piped from git-log; it can accept revision
 368   parameters directly on the command line.
 369
 370
 371* I18n
 372
 373 - We have always encouraged the commit message to be encoded in
 374   UTF-8, but the users are allowed to use legacy encoding as
 375   appropriate for their projects.  This will continue to be the
 376   case.  However, a non UTF-8 commit encoding _must_ be
 377   explicitly set with i18n.commitencoding in the repository
 378   where a commit is made; otherwise git-commit-tree will
 379   complain if the log message does not look like a valid UTF-8
 380   string.
 381
 382 - The value of i18n.commitencoding in the originating
 383   repository is recorded in the commit object on the "encoding"
 384   header, if it is not UTF-8.  git-log and friends notice this,
 385   and reencodes the message to the log output encoding when
 386   displaying, if they are different.  The log output encoding
 387   is determined by "git log --encoding=<encoding>",
 388   i18n.logoutputencoding configuration, or i18n.commitencoding
 389   configuration, in the decreasing order of preference, and
 390   defaults to UTF-8.
 391
 392 - Tools for e-mailed patch application now default to -u
 393   behavior; i.e. it always re-codes from the e-mailed encoding
 394   to the encoding specified with i18n.commitencoding.  This
 395   unfortunately forces projects that have happily been using a
 396   legacy encoding without setting i18n.commitencoding to set
 397   the configuration, but taken with other improvement, please
 398   excuse us for this very minor one-time inconvenience.
 399
 400
 401* e-mailed patches
 402
 403 - See the above I18n section.
 404
 405 - git-format-patch now enables --binary without being asked.
 406   git-am does _not_ default to it, as sending binary patch via
 407   e-mail is unusual and is harder to review than textual
 408   patches and it is prudent to require the person who is
 409   applying the patch to explicitly ask for it.
 410
 411 - The default suffix for git-format-patch output is now ".patch",
 412   not ".txt".  This can be changed with --suffix=.txt option,
 413   or setting the config variable "format.suffix" to ".txt".
 414
 415
 416* Foreign SCM interfaces
 417
 418 - git-svn now requires the Perl SVN:: libraries, the
 419   command-line backend was too slow and limited.
 420
 421 - the 'commit' subcommand of git-svn has been renamed to
 422   'set-tree', and 'dcommit' is the recommended replacement for
 423   day-to-day work.
 424
 425 - git fast-import backend.
 426
 427
 428* User support
 429
 430 - Quite a lot of documentation updates.
 431
 432 - Bash completion scripts have been updated heavily.
 433
 434 - Better error messages for often used Porcelainish commands.
 435
 436 - Git GUI.  This is a simple Tk based graphical interface for
 437   common Git operations.
 438
 439
 440* Sliding mmap
 441
 442 - We used to assume that we can mmap the whole packfile while
 443   in use, but with a large project this consumes huge virtual
 444   memory space and truly huge ones would not fit in the
 445   userland address space on 32-bit platforms.  We now mmap huge
 446   packfile in pieces to avoid this problem.
 447
 448
 449* Shallow clones
 450
 451 - There is a partial support for 'shallow' repositories that
 452   keeps only recent history.  A 'shallow clone' is created by
 453   specifying how deep that truncated history should be
 454   (e.g. "git clone --depth=5 git://some.where/repo.git").
 455
 456   Currently a shallow repository has number of limitations:
 457
 458   - Cloning and fetching _from_ a shallow clone are not
 459     supported (nor tested -- so they might work by accident but
 460     they are not expected to).
 461
 462   - Pushing from nor into a shallow clone are not expected to
 463     work.
 464
 465   - Merging inside a shallow repository would work as long as a
 466     merge base is found in the recent history, but otherwise it
 467     will be like merging unrelated histories and may result in
 468     huge conflicts.
 469
 470   but this would be more than adequate for people who want to
 471   look at near the tip of a big project with a deep history and
 472   send patches in e-mail format.