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.