diff options
Diffstat (limited to 'Documentation')
38 files changed, 512 insertions, 257 deletions
diff --git a/Documentation/RelNotes-1.5.3.txt b/Documentation/RelNotes-1.5.3.txt index 9c36e8baeb..51ff53b370 100644 --- a/Documentation/RelNotes-1.5.3.txt +++ b/Documentation/RelNotes-1.5.3.txt @@ -28,7 +28,7 @@ Updates since v1.5.2 * For people who need to import from Perforce, a front-end for fast-import is in contrib/fast-import/. -* Comes with git-gui 0.8.0. +* Comes with git-gui 0.8.2. * Comes with updated gitk. @@ -130,6 +130,9 @@ Updates since v1.5.2 - "git init -q" makes the command quieter. + - "git -p command" now has a cousin of opposite sex, "git --no-pager + command". + * Updated behavior of existing commands. - "gitweb" can offer multiple snapshot formats. @@ -172,6 +175,15 @@ Updates since v1.5.2 - "git log" learned --log-size to show the number of bytes in the log message part of the output to help qgit. + - "git log --name-status" does not require you to give "-r" anymore. + As a general rule, Porcelain commands should recurse when showing + diff. + + - "git format-patch --root A" can be used to format everything + since the beginning up to A. This was supported with + "git format-patch --root A A" for a long time, but was not + properly documented. + - "git svn dcommit" retains local merge information. - "git svnimport" allows an empty string to be specified as the @@ -301,8 +313,8 @@ Updates since v1.5.2 when switching branches that have differences in only a handful paths. - - "git commit paths..." has also been optimized. - + - "git add paths..." and "git commit paths..." has also been + heavily optimized. Fixes since v1.5.2 ------------------ @@ -315,8 +327,26 @@ this release, unless otherwise noted. - "gitweb" had trouble handling non UTF-8 text with older Encode.pm Perl module. + - "git-write-tree" had a bad interaction with racy-git avoidance and + gitattributes mechanisms. + + - "git --bare command" overrode existing GIT_DIR setting and always + made it treat the current working directory as GIT_DIR. + + - "git ls-files --error-unmatch" does not complain if you give the + same path pattern twice by mistake. + + - "git init" autodetected core.filemode but not core.symlinks, which + made a new directory created automatically by "git clone" cumbersome + to use on filesystems that require these configurations to be set. + + - "git log" family of commands behaved differently when run as "git + log" (no pathspec) and as "git log --" (again, no pathspec). This + inconsistency was introduced somewhere in v1.3.0 series but now has + been corrected. + -- exec >/var/tmp/1 -O=v1.5.3-rc4 +O=v1.5.3-rc7-15-ga65f200 echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 01354c2bb5..61635bf04d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -31,7 +31,8 @@ Checklist (and a short version for the impatient): corrupt whitespaces. - provide additional information (which is unsuitable for the commit message) between the "---" and the diffstat - - send the patch to the list _and_ the maintainer + - send the patch to the list (git@vger.kernel.org) and the + maintainer (gitster@pobox.com). - if you change, add, or remove a command line option or make some other user interface change, the associated documentation should be updated as well. diff --git a/Documentation/config.txt b/Documentation/config.txt index de9e72b562..866e0534b8 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -192,7 +192,7 @@ core.worktree:: variable and the '--work-tree' command line option. core.logAllRefUpdates:: - Updates to a ref <ref> is logged to the file + Enable the reflog. Updates to a ref <ref> is logged to the file "$GIT_DIR/logs/<ref>", by appending the new and old SHA1, the date/time and the reason of the update, but only when the file exists. If this configuration @@ -283,7 +283,7 @@ core.excludesfile:: core.editor:: Commands such as `commit` and `tag` that lets you edit - messages by lauching an editor uses the value of this + messages by launching an editor uses the value of this variable when it is set, and the environment variable `GIT_EDITOR` is not set. The order of preference is `GIT_EDITOR` environment, `core.editor`, `VISUAL` and @@ -301,12 +301,12 @@ alias.*:: hide existing git commands are ignored. Arguments are split by spaces, the usual shell quoting and escaping is supported. quote pair and a backslash can be used to quote them. - - If the alias expansion is prefixed with an exclamation point, - it will be treated as a shell command. For example, defining - "alias.new = !gitk --all --not ORIG_HEAD", the invocation - "git new" is equivalent to running the shell command - "gitk --all --not ORIG_HEAD". ++ +If the alias expansion is prefixed with an exclamation point, +it will be treated as a shell command. For example, defining +"alias.new = !gitk --all --not ORIG_HEAD", the invocation +"git new" is equivalent to running the shell command +"gitk --all --not ORIG_HEAD". apply.whitespace:: Tells `git-apply` how to handle whitespaces, in the same way @@ -396,6 +396,16 @@ color.status.<slot>:: commit.template:: Specify a file to use as the template for new commit messages. +diff.autorefreshindex:: + When using `git diff` to compare with work tree + files, do not consider stat-only change as changed. + Instead, silently run `git update-index --refresh` to + update the cached stat information for paths whose + contents in the work tree match the contents in the + index. This option defaults to true. Note that this + affects only `git diff` Porcelain, and not lower level + `diff` commands, such as `git diff-files`. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. @@ -465,11 +475,11 @@ rerere.enabled:: be encountered again. See gitlink:git-rerere[1]. gitcvs.enabled:: - Whether the cvs server interface is enabled for this repository. + Whether the CVS server interface is enabled for this repository. See gitlink:git-cvsserver[1]. gitcvs.logfile:: - Path to a log file where the cvs server interface well... logs + Path to a log file where the CVS server interface well... logs various stuff. See gitlink:git-cvsserver[1]. gitcvs.allbinary:: @@ -500,10 +510,10 @@ gitcvs.dbuser, gitcvs.dbpass:: 'gitcvs.dbuser' supports variable substitution (see gitlink:git-cvsserver[1] for details). -All gitcvs variables except for 'gitcvs.allbinary' can also specifed -as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one -of "ext" and "pserver") to make them apply only for the given access -method. +All gitcvs variables except for 'gitcvs.allbinary' can also be +specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' +is one of "ext" and "pserver") to make them apply only for the given +access method. http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing @@ -615,7 +625,7 @@ pack.compression:: not set, defaults to -1. pack.deltaCacheSize:: - The maxium memory in bytes used for caching deltas in + The maximum memory in bytes used for caching deltas in gitlink:git-pack-objects[1]. A value of 0 means no limit. Defaults to 0. @@ -675,15 +685,11 @@ showbranch.default:: See gitlink:git-show-branch[1]. tar.umask:: - By default, gitlink:git-tar-tree[1] sets file and directories modes - to 0666 or 0777. While this is both useful and acceptable for projects - such as the Linux Kernel, it might be excessive for other projects. - With this variable, it becomes possible to tell - gitlink:git-tar-tree[1] to apply a specific umask to the modes above. - The special value "user" indicates that the user's current umask will - be used. This should be enough for most projects, as it will lead to - the same permissions as gitlink:git-checkout[1] would use. The default - value remains 0, which means world read-write. + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) and + gitlink:git-archive[1]. user.email:: Your email address to be recorded in any newly created commits. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 3383aca9af..2fe7355555 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -7,7 +7,9 @@ git-add - Add file contents to the index SYNOPSIS -------- -'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--refresh] [--] <file>... +[verse] +'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--refresh] + [--] <filepattern>... DESCRIPTION ----------- @@ -31,9 +33,9 @@ files have changes that are staged for the next commit. The 'git add' command will not add ignored files by default. If any ignored files were explicitly specified on the command line, 'git add' will fail with a list of ignored files. Ignored files reached by -directory recursion or filename globbing will be silently ignored. -The 'add' command can be used to add ignored files with the `-f` -(force) option. +directory recursion or filename globbing performed by Git (quote your +globs before the shell) will be silently ignored. The 'add' command can +be used to add ignored files with the `-f` (force) option. Please see gitlink:git-commit[1] for alternative ways to add content to a commit. @@ -41,7 +43,7 @@ commit. OPTIONS ------- -<file>...:: +<filepattern>...:: Files to add content from. Fileglobs (e.g. `*.c`) can be given to add all matching files. Also a leading directory name (e.g. `dir` to add `dir/file1` diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 4da07c1580..f2080eb6ad 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -72,16 +72,13 @@ zip CONFIGURATION ------------- -By default, file and directories modes are set to 0666 or 0777 in tar -archives. It is possible to change this by setting the "umask" variable -in the repository configuration as follows : -[tar] - umask = 002 ;# group friendly - -The special umask value "user" indicates that the user's current umask -will be used instead. The default value remains 0, which means world -readable/writable files and directories. +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) for + details. EXAMPLES -------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 818b720b91..734928bf96 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -35,7 +35,7 @@ working tree. OPTIONS ------- -q:: - Quiet, supress feedback messages. + Quiet, suppress feedback messages. -f:: Proceed even if the index or the working tree differs diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 5870c2ce47..a2537e179a 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -51,9 +51,9 @@ A commit encapsulates: - author name, email and date - committer name and email and the commit time. -If not provided, "git-commit-tree" uses your name, hostname and domain to -provide author and committer info. This can be overridden by -either `.git/config` file, or using the following environment variables. +While parent object ids are provided on the command line, author and +committer information is taken from the following environment variables, +if set: GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL @@ -65,12 +65,9 @@ either `.git/config` file, or using the following environment variables. (nb "<", ">" and "\n"s are stripped) -In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and -GIT_AUTHOR_EMAIL: - - [user] - name = "Your Name" - email = "your@email.address.xz" +In case (some of) these environment variables are not set, the information +is taken from the configuration items user.name and user.email, or, if not +present, system user name and fully qualified hostname. A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, "git-commit-tree" will just wait diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index c3dffffe32..5b794f4399 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -139,7 +139,7 @@ See also <<FILES>>. FILES ----- -If not set explicitely with '--file', there are three files where +If not set explicitly with '--file', there are three files where git-config will search for configuration options: .git/config:: diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 6c423e3a2f..4c8d1e6386 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -59,7 +59,7 @@ OPTIONS Useful for patch series and the like. -u:: - Update affected files from cvs repository before attempting export. + Update affected files from CVS repository before attempting export. -v:: Verbose. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 60d0bcf0f3..258a62f7e9 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -102,7 +102,7 @@ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename git-cvsserver to cvs. -Note: Newer cvs versions (>= 1.12.11) also support specifying +Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like ------ diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index f902161c08..99e47c9c25 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -124,7 +124,8 @@ OPTIONS Detach from the shell. Implies --syslog. --pid-file=file:: - Save the process id in 'file'. + Save the process id in 'file'. Ignored when the daemon + is run under `--inetd`. --user=user, --group=group:: Change daemon's uid and gid before entering the service loop. @@ -157,6 +158,13 @@ the facility of inet daemon to achieve the same before spawning SERVICES -------- +These services can be globally enabled/disabled using the +command line options of this command. If a finer-grained +control is desired (e.g. to allow `git-archive` to be run +against only in a few selected repositories the daemon serves), +the per-repository configuration file can be used to enable or +disable them. + upload-pack:: This serves `git-fetch-pack` and `git-peek-remote` clients. It is enabled by default, but a repository can @@ -164,7 +172,19 @@ upload-pack:: item to `false`. upload-archive:: - This serves `git-archive --remote`. + This serves `git-archive --remote`. It is disabled by + default, but a repository can enable it by setting + `daemon.uploadarchive` configuration item to `true`. + +receive-pack:: + This serves `git-send-pack` clients, allowing anonymous + push. It is disabled by default, as there is _no_ + authentication in the protocol (in other words, anybody + can push anything into the repository, including removal + of refs). This is solely meant for a closed LAN setting + where everybody is friendly. This service can be + enabled by `daemon.receivepack` configuration item to + `true`. EXAMPLES -------- @@ -228,6 +248,18 @@ a subdirectory for each virtual host IP address supported. Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. +selectively enable/disable services per repository:: + To enable `git-archive --remote` and disable `git-fetch` against + a repository, have the following in the configuration file in the + repository (that is the file 'config' next to 'HEAD', 'refs' and + 'objects'). ++ +---------------------------------------------------------------- + [daemon] + uploadpack = false + uploadarchive = true +---------------------------------------------------------------- + Author ------ diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index b36e705dd0..db2eb46a19 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -22,10 +22,10 @@ tree and the index file, or the index file and the working tree. words, the differences are what you _could_ tell git to further add to the index but you still haven't. You can stage these changes by using gitlink:git-add[1]. - - If exactly two paths are given, and at least one is untracked, - compare the two files / directories. This behavior can be - forced by --no-index. ++ +If exactly two paths are given, and at least one is untracked, +compare the two files / directories. This behavior can be +forced by --no-index. 'git-diff' [--options] --cached [<commit>] [--] [<path>...]:: @@ -44,16 +44,34 @@ tree and the index file, or the index file and the working tree. 'git-diff' [--options] <commit> <commit> [--] [<path>...]:: - This form is to view the changes between two <commit>, - for example, tips of two branches. + This is to view the changes between two arbitrary + <commit>. + +'git-diff' [--options] <commit>..<commit> [--] [<path>...]:: + + This is synonymous to the previous form. If <commit> on + one side is omitted, it will have the same effect as + using HEAD instead. + +'git-diff' [--options] <commit>\...<commit> [--] [<path>...]:: + + This form is to view the changes on the branch containing + and up to the second <commit>, starting at a common ancestor + of both <commit>. "git-diff A\...B" is equivalent to + "git-diff $(git-merge-base A B) B". You can omit any one + of <commit>, which has the same effect as using HEAD instead. Just in case if you are doing something exotic, it should be -noted that all of the <commit> in the above description can be -any <tree-ish>. +noted that all of the <commit> in the above description, except +for the last two forms that use ".." notations, can be any +<tree-ish>. For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. - +However, "diff" is about comparing two _endpoints_, not ranges, +and the range notations ("<commit>..<commit>" and +"<commit>\...<commit>") do not mean a range as defined in the +"SPECIFYING RANGES" section in gitlink:git-rev-parse[1]. OPTIONS ------- @@ -97,6 +115,18 @@ the tip of the current branch, but limit the comparison to the file "test". <3> Compare the version before the last commit and the last commit. +Comparing branches:: ++ +------------ +$ git diff topic master <1> +$ git diff topic..master <2> +$ git diff topic...master <3> +------------ ++ +<1> Changes between the tips of the topic and the master branches. +<2> Same as above. +<3> Changes that occured on the master branch since when the topic +branch was started off it. Limiting the diff output:: + diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 30ee98d17f..d5119678b5 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -176,6 +176,15 @@ results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters unexpected input. +Stream Comments +~~~~~~~~~~~~~~~ +To aid in debugging frontends fast-import ignores any line that +begins with `#` (ASCII pound/hash) up to and including the line +ending `LF`. A comment line may contain any sequence of bytes +that does not contain an LF and therefore may be used to include +any detailed debugging information that might be specific to the +frontend and useful when inspecting a fast-import data stream. + Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select @@ -232,7 +241,7 @@ been well tested in the wild. + Frontends should prefer the `raw` format if the source material already uses UNIX-epoch format, can be coaxed to give dates in that -format, or its format is easiliy convertible to it, as there is no +format, or its format is easily convertible to it, as there is no ambiguity in parsing. `now`:: @@ -289,6 +298,11 @@ and control the current import process. More detailed discussion This command is optional and is not needed to perform an import. +`progress`:: + Causes fast-import to echo the entire line to its own + standard output. This command is optional and is not needed + to perform an import. + `commit` ~~~~~~~~ Create or update a branch with a new commit, recording one logical @@ -303,7 +317,7 @@ change to the project. ('from' SP <committish> LF)? ('merge' SP <committish> LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall)* - LF + LF? .... where `<ref>` is the name of the branch to make the commit on. @@ -329,11 +343,13 @@ Zero or more `filemodify`, `filedelete`, `filecopy`, `filerename` and `filedeleteall` commands may be included to update the contents of the branch prior to creating the commit. These commands may be supplied in any order. -However it is recommended that a `filedeleteall` command preceed +However it is recommended that a `filedeleteall` command precede all `filemodify`, `filecopy` and `filerename` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). +The `LF` after the command is optional (it used to be required). + `author` ^^^^^^^^ An `author` command may optionally appear, if the author information @@ -386,7 +402,7 @@ Here `<committish>` is any of the following: + The reason fast-import uses `:` to denote a mark reference is this character is not legal in a Git branch name. The leading `:` makes it easy -to distingush between the mark 42 (`:42`) and the branch 42 (`42` +to distinguish between the mark 42 (`:42`) and the branch 42 (`42` or `refs/heads/42`), or an abbreviated SHA-1 which happened to consist only of base-10 digits. + @@ -471,7 +487,7 @@ start with double quote (`"`). If an `LF` or double quote must be encoded into `<path>` shell-style quoting should be used, e.g. `"path/with\n and \" in it"`. -The value of `<path>` must be in canoncial form. That is it must not: +The value of `<path>` must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), * end with a directory separator (e.g. `foo/` is invalid), @@ -645,12 +661,14 @@ branch from an existing commit without creating a new commit. .... 'reset' SP <ref> LF ('from' SP <committish> LF)? - LF + LF? .... For a detailed description of `<ref>` and `<committish>` see above under `commit` and `from`. +The `LF` after the command is optional (it used to be required). + The `reset` command can also be used to create lightweight (non-annotated) tags. For example: @@ -689,29 +707,40 @@ intended for production-quality conversions should always use the exact byte count format, as it is more robust and performs better. The delimited format is intended primarily for testing fast-import. +Comment lines appearing within the `<raw>` part of `data` commands +are always taken to be part of the body of the data and are therefore +never ignored by fast-import. This makes it safe to import any +file/message content whose lines might start with `#`. + Exact byte count format:: The frontend must specify the number of bytes of data. + .... 'data' SP <count> LF - <raw> LF + <raw> LF? .... + where `<count>` is the exact number of bytes appearing within `<raw>`. The value of `<count>` is expressed as an ASCII decimal integer. The `LF` on either side of `<raw>` is not included in `<count>` and will not be included in the imported data. ++ +The `LF` after `<raw>` is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if `<raw>` did not end with an `LF`. Delimited format:: A delimiter string is used to mark the end of the data. fast-import will compute the length by searching for the delimiter. - This format is primarly useful for testing and is not + This format is primarily useful for testing and is not recommended for real data. + .... 'data' SP '<<' <delim> LF <raw> LF <delim> LF + LF? .... + where `<delim>` is the chosen delimiter string. The string `<delim>` @@ -720,6 +749,8 @@ fast-import will think the data ends earlier than it really does. The `LF` immediately trailing `<raw>` is part of `<raw>`. This is one of the limitations of the delimited format, it is impossible to supply a data chunk which does not have an LF as its last byte. ++ +The `LF` after `<delim> LF` is optional (it used to be required). `checkpoint` ~~~~~~~~~~~~ @@ -728,7 +759,7 @@ save out all current branch refs, tags and marks. .... 'checkpoint' LF - LF + LF? .... Note that fast-import automatically switches packfiles when the current @@ -747,6 +778,32 @@ process access to a branch. However given that a 30 GiB Subversion repository can be loaded into Git through fast-import in about 3 hours, explicit checkpointing may not be necessary. +The `LF` after the command is optional (it used to be required). + +`progress` +~~~~~~~~~~ +Causes fast-import to print the entire `progress` line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import's internal state. + +.... + 'progress' SP <any> LF + LF? +.... + +The `<any>` part of the command may contain any sequence of bytes +that does not contain `LF`. The `LF` after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example: + +==== + frontend | git-fast-import | sed 's/^progress //' +==== + +Placing a `progress` command immediately after a `checkpoint` will +inform the reader when the `checkpoint` has been completed and it +can safely access the refs that fast-import updated. Tips and Tricks --------------- @@ -816,7 +873,7 @@ to remove the dummy branch. Import Now, Repack Later ~~~~~~~~~~~~~~~~~~~~~~~~ As soon as fast-import completes the Git repository is completely valid -and ready for use. Typicallly this takes only a very short time, +and ready for use. Typically this takes only a very short time, even for considerably large projects (100,000+ commits). However repacking the repository is necessary to improve data @@ -840,6 +897,15 @@ This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. +Include Some Progress Messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Every once in a while have your frontend emit a `progress` message +to fast-import. The contents of the messages are entirely free-form, +so one suggestion would be to output the current month and year +each time the current commit date moves into the next month. +Your users will feel better knowing how much of the data stream +has been processed. + Packfile Optimization --------------------- @@ -876,8 +942,8 @@ Memory Utilization ------------------ There are a number of factors which affect how much memory fast-import requires to perform an import. Like critical sections of core -Git, fast-import uses its own memory allocators to ammortize any overheads -associated with malloc. In practice fast-import tends to ammoritize any +Git, fast-import uses its own memory allocators to amortize any overheads +associated with malloc. In practice fast-import tends to amortize any malloc overheads to 0, due to its use of large block allocations. per object @@ -934,7 +1000,7 @@ per active tree ~~~~~~~~~~~~~~~ Trees (aka directories) use just 12 bytes of memory on top of the memory required for their entries (see ``per active file'' below). -The cost of a tree is virtually 0, as its overhead ammortizes out +The cost of a tree is virtually 0, as its overhead amortizes out over the individual file entries. per active file entry diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 915258f410..29bb8cec0c 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -12,23 +12,24 @@ SYNOPSIS [--index-filter <command>] [--parent-filter <command>] [--msg-filter <command>] [--commit-filter <command>] [--tag-name-filter <command>] [--subdirectory-filter <directory>] - [-d <directory>] [-f | --force] [<rev-list options>...] + [--original <namespace>] [-d <directory>] [-f | --force] + [<rev-list options>...] DESCRIPTION ----------- -Lets you rewrite git revision history by creating a new branch from -your current branch, applying custom filters on each revision. +Lets you rewrite git revision history by rewriting the branches mentioned +in the <rev-list options>, applying custom filters on each revision. Those filters can modify each tree (e.g. removing a file or running a perl rewrite on all files) or information about each commit. Otherwise, all information (including original commit times or merge information) will be preserved. -The command takes the new branch name as a mandatory argument and -the filters as optional arguments. If you specify no filters, the -commits will be recommitted without any changes, which would normally -have no effect. Nevertheless, this may be useful in the future for -compensating for some git bugs or such, therefore such a usage is -permitted. +The command will only rewrite the _positive_ refs mentioned in the +command line (i.e. if you pass 'a..b', only 'b' will be rewritten). +If you specify no filters, the commits will be recommitted without any +changes, which would normally have no effect. Nevertheless, this may be +useful in the future for compensating for some git bugs or such, +therefore such a usage is permitted. *WARNING*! The rewritten history will have different object names for all the objects and will not converge with the original branch. You will not @@ -42,8 +43,8 @@ if different from the rewritten ones, will be stored in the namespace 'refs/original/'. Note that since this operation is extensively I/O expensive, it might -be a good idea to redirect the temporary directory off-disk, e.g. on -tmpfs. Reportedly the speedup is very noticeable. +be a good idea to redirect the temporary directory off-disk with the +'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable. Filters @@ -111,6 +112,11 @@ OPTIONS As a special extension, the commit filter may emit multiple commit ids; in that case, ancestors of the original commit will have all of them as parents. ++ +You can use the 'map' convenience function in this filter, and other +convenience functions, too. For example, calling 'skip_commit "$@"' +will leave out the current commit (but not its changes! If you want +that, use gitlink:git-rebase[1] instead). --tag-name-filter <command>:: This is the filter for rewriting tag names. When passed, @@ -120,7 +126,7 @@ have all of them as parents. tag name is expected on standard output. + The original tags are not deleted, but can be overwritten; -use "--tag-name-filter=cat" to simply update the tags. In this +use "--tag-name-filter cat" to simply update the tags. In this case, be very careful and make sure you have the old tags backed up in case the conversion has run afoul. + @@ -134,6 +140,10 @@ definition impossible to preserve signatures at any rate.) The result will contain that directory (and only that) as its project root. +--original <namespace>:: + Use this option to set the namespace where the original commits + will be stored. The default value is 'refs/original'. + -d <directory>:: Use this option to set the path to the temporary directory used for rewriting. When applying a tree filter, the command needs to @@ -181,8 +191,8 @@ order to paste the other history behind the current history: git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD ------------------------------------------------------------------- -(if the parent string is empty - therefore we are dealing with the -initial commit - add graftcommit as a parent). Note that this assumes +(if the parent string is empty - which happens when we are dealing with +the initial commit - add graftcommit as a parent). Note that this assumes history with a single root (that is, no merge without common ancestors happened). If this is not the case, use: @@ -204,34 +214,50 @@ To remove commits authored by "Darl McBribe" from the history: git filter-branch --commit-filter ' if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ]; then - shift; - while [ -n "$1" ]; - do - shift; - echo "$1"; - shift; - done; + skip_commit "$@"; else git commit-tree "$@"; fi' HEAD ------------------------------------------------------------------------------ +Note that the changes introduced by the commits, and not reverted by +subsequent commits, will still be in the rewritten branch. If you want +to throw out _changes_ together with the commits, you should use the +interactive mode of gitlink:git-rebase[1]. + +The function 'skip_commits' is defined as follows: + +-------------------------- +skip_commit() +{ + shift; + while [ -n "$1" ]; + do + shift; + map "$1"; + shift; + done; +} +-------------------------- + The shift magic first throws away the tree id and then the -p parameters. Note that this handles merges properly! In case Darl committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. + To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will point to the top-most revision that a 'git rev-list' of this range will print. -Note that the changes introduced by the commits, and not reverted by -subsequent commits, will still be in the rewritten branch. If you want +*NOTE* the changes introduced by the commits, and which are not reverted +by subsequent commits, will still be in the rewritten branch. If you want to throw out _changes_ together with the commits, you should use the interactive mode of gitlink:git-rebase[1]. + Consider this history: ------------------ diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 6affc5bb4d..7088ed4095 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] git-fmt-merge-msg [--summary | --no-summary] <$GIT_DIR/FETCH_HEAD -git-fmt-merge-msg [--summary | --no-summray] -F <file> +git-fmt-merge-msg [--summary | --no-summary] -F <file> DESCRIPTION ----------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6cbcf937bc..c9857a2d62 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -16,21 +16,35 @@ SYNOPSIS [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] - <since>[..<until>] + [ <since> | <revision range> ] DESCRIPTION ----------- -Prepare each commit between <since> and <until> with its patch in +Prepare each commit with its patch in one file per commit, formatted to resemble UNIX mailbox format. -If ..<until> is not specified, the head of the current working -tree is implied. For a more complete list of ways to spell -<since> and <until>, see "SPECIFYING REVISIONS" section in -gitlink:git-rev-parse[1]. - The output of this command is convenient for e-mail submission or for use with gitlink:git-am[1]. +There are two ways to specify which commits to operate on. + +1. A single commit, <since>, specifies that the commits leading + to the tip of the current branch that are not in the history + that leads to the <since> to be output. + +2. Generic <revision range> expression (see "SPECIFYING + REVISIONS" section in gitlink:git-rev-parse[1]) means the + commits in the specified range. + +A single commit, when interpreted as a <revision range> +expression, means "everything that leads to that commit", but +if you write 'git format-patch <commit>', the previous rule +applies to that command line and you do not get "everything +since the beginning of the time". If you want to format +everything since project inception to one commit, say "git +format-patch \--root <commit>" to make it clear that it is the +latter case. + By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as the filename. With the --numbered-files option, the output file names @@ -118,7 +132,7 @@ include::diff-options.txt[] --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated - filenames, use specifed suffix. A common alternative is + filenames, use specified suffix. A common alternative is `--suffix=.txt`. + Note that you would need to include the leading dot `.` if you @@ -153,6 +167,10 @@ git-format-patch origin:: not in the origin branch. For each commit a separate file is created in the current directory. +git-format-patch \--root origin:: + Extract all commits which that leads to 'origin' since the + inception of the project. + git-format-patch -M -B origin:: The same as the previous one. Additionally, it detects and handles renames and complete rewrites intelligently to diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index bd613b2fcf..13252a1aa6 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -89,7 +89,7 @@ See Also Other ----- git-gui is actually maintained as an independent project, but stable -versions are distributed as part of the Git suite for the convience +versions are distributed as part of the Git suite for the convenience of end users. A git-gui development repository can be obtained from: diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 45e48453a1..389c6edfb8 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -34,7 +34,7 @@ commit-id:: the local end after the transfer is complete. --stdin:: - Instead of a commit id on the commandline (which is not expected in this + Instead of a commit id on the command line (which is not expected in this case), 'git-http-fetch' expects lines on stdin in the format <commit-id>['\t'<filename-as-in--w>] diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt index 141b76768c..e830deeff3 100644 --- a/Documentation/git-local-fetch.txt +++ b/Documentation/git-local-fetch.txt @@ -44,7 +44,7 @@ OPTIONS the local end after the transfer is complete. --stdin:: - Instead of a commit id on the commandline (which is not expected in this + Instead of a commit id on the command line (which is not expected in this case), 'git-local-fetch' expects lines on stdin in the format <commit-id>['\t'<filename-as-in--w>] diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 5a90f65b5e..5ec547cc0c 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -49,6 +49,7 @@ include::pretty-options.txt[] -g, \--walk-reflogs:: Show commits as they were recorded in the reflog. The log contains a record about how the tip of a reference was changed. + Cannot be combined with --reverse. See also gitlink:git-reflog[1]. --decorate:: @@ -95,7 +96,7 @@ git log --since="2 weeks ago" \-- gitk:: The "--" is necessary to avoid confusion with the *branch* named 'gitk' -git log -r --name-status release..test:: +git log --name-status release..test:: Show the commits that are in the "test" branch but not yet in the "release" branch, along with the list of paths diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 91eede120e..306e1a4956 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -37,7 +37,7 @@ OPTIONS --name-only:: Instead of printing both the SHA-1 and the name, print only the name. If given with --tags the usual tag prefix of - "tags/" is also ommitted from the name, matching the output + "tags/" is also omitted from the name, matching the output of gitlink::git-describe[1] more closely. This option cannot be combined with --stdin. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index a1b6dce73d..61b1810dba 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,7 +8,7 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git-rebase' [-i | --interactive] [-v | --verbose] [--merge] [-C<n>] +'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] [-C<n>] [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort @@ -188,7 +188,7 @@ OPTIONS --skip:: Restart the rebasing process by skipping the current patch. ---merge:: +-m, \--merge:: Use merging strategies to rebase. When the recursive (default) merge strategy is used, this allows rebase to be aware of renames on the upstream side. @@ -211,7 +211,8 @@ OPTIONS -i, \--interactive:: Make a list of the commits which are about to be rebased. Let the - user edit that list before rebasing. + user edit that list before rebasing. This mode can also be used to + split commits (see SPLITTING COMMITS below). -p, \--preserve-merges:: Instead of ignoring merges, try to recreate them. This option @@ -325,6 +326,42 @@ sure that the current HEAD is "B", and call $ git rebase -i -p --onto Q O ----------------------------- + +SPLITTING COMMITS +----------------- + +In interactive mode, you can mark commits with the action "edit". However, +this does not necessarily mean that 'git rebase' expects the result of this +edit to be exactly one commit. Indeed, you can undo the commit, or you can +add other commits. This can be used to split a commit into two: + +- Start an interactive rebase with 'git rebase -i <commit>^', where + <commit> is the commit you want to split. In fact, any commit range + will do, as long as it contains that commit. + +- Mark the commit you want to split with the action "edit". + +- When it comes to editing that commit, execute 'git reset HEAD^'. The + effect is that the HEAD is rewound by one, and the index follows suit. + However, the working tree stays the same. + +- Now add the changes to the index that you want to have in the first + commit. You can use gitlink:git-add[1] (possibly interactively) and/or + gitlink:git-gui[1] to do that. + +- Commit the now-current index with whatever commit message is appropriate + now. + +- Repeat the last two steps until your working tree is clean. + +- Continue the rebase with 'git rebase --continue'. + +If you are not absolutely sure that the intermediate revisions are +consistent (they compile, pass the testsuite, etc.) you should use +gitlink:git-stash[1] to stash away the not-yet-committed changes +after each commit, test, and amend the commit if fixes are necessary. + + Authors ------ Written by Junio C Hamano <junkio@cox.net> and diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 4ef1840472..2633d94c59 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -78,7 +78,7 @@ The hook should exit with non-zero status if it wants to disallow updating the named ref. Otherwise it should exit with zero. Successful execution (a zero exit status) of this hook does not -ensure the ref will actully be updated, it is only a prerequisite. +ensure the ref will actually be updated, it is only a prerequisite. As such it is not a good idea to send notices (e.g. email) from this hook. Consider using the post-receive hook instead. diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 89bc9c51ea..5180f6810d 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -30,9 +30,10 @@ Entries older than `expire` time, or entries older than tip, are removed from the reflog. This is typically not used directly by the end users -- instead, see gitlink:git-gc[1]. -The subcommand "show" (which is also the default, in the absense of any +The subcommand "show" (which is also the default, in the absence of any subcommands) will take all the normal log options, and show the log of -the current branch. It is basically an alias for 'git log -g --abbrev-commit +`HEAD`, which will cover all recent actions, including branch switches. +It is basically an alias for 'git log -g --abbrev-commit --pretty=oneline', see gitlink:git-log[1]. diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 5283ef84a9..12e2079a7c 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -14,7 +14,7 @@ DESCRIPTION ----------- This script is used to combine all objects that do not currently -reside in a "pack", into a pack. It can also be used to re-organise +reside in a "pack", into a pack. It can also be used to re-organize existing packs into a single, more efficient pack. A pack is a collection of objects, individually compressed, with diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 1c1978140f..7cd0e8913e 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -113,7 +113,7 @@ e.g. "2 hours ago". `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 format, often found in E-mail messages. + -`--date=short` shows only date but not time, in `YYYY-MM-DD` fomat. +`--date=short` shows only date but not time, in `YYYY-MM-DD` format. + `--date=default` shows timestamps in the original timezone (either committer's or author's). @@ -299,6 +299,8 @@ used in the output. When the starting commit is specified as instead. Under '\--pretty=oneline', the commit message is prefixed with this information on the same line. +Cannot be combined with '\--reverse'. + --merge:: After a failed merge, show refs that touch files having a @@ -373,6 +375,7 @@ By default, the commits are shown in reverse chronological order. --reverse:: Output the commits in reverse order. + Cannot be combined with '\--walk-reflogs'. Object Traversal ~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4b4d229e60..4758c33dee 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -215,7 +215,10 @@ blobs contained in a commit. * A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path; this names a blob object in the index at the given path. Missing stage number (and the colon - that follows it) names an stage 0 entry. + that follows it) names an stage 0 entry. During a merge, stage + 1 is the common ancestor, stage 2 is the target branch's version + (typically the current branch), and stage 3 is the version from + the branch being merged. Here is an illustration, by Jon Loeliger. Both node B and C are a commit parents of commit node A. Parent commits are ordered diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index a63a3adab0..16bfd7be22 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -68,7 +68,7 @@ The --cc option must be repeated for each user you want on the cc list. --signed-off-by-cc, --no-signed-off-by-cc:: If this is set, add emails found in Signed-off-by: or Cc: lines to the cc list. - Default is the value of 'sendemail.signedoffbycc' configuration value; + Default is the value of 'sendemail.signedoffcc' configuration value; if that is unspecified, default to --signed-off-by-cc. --quiet:: @@ -94,7 +94,7 @@ The --cc option must be repeated for each user you want on the cc list. If this is set, do not add the From: address to the cc: list, if it shows up in a From: line. Default is the value of 'sendemail.suppressfrom' configuration value; - if that is unspecified, default to --no-supress-from. + if that is unspecified, default to --no-suppress-from. --thread, --no-thread:: If this is set, the In-Reply-To header will be set on each email sent. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 816340b944..be2e34eb8f 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -44,10 +44,15 @@ COMMANDS --tags=<tags_subdir>;; -b<branches_subdir>;; --branches=<branches_subdir>;; +-s;; +--stdlayout;; These are optional command-line options for init. Each of these flags can point to a relative repository path (--tags=project/tags') or a full url - (--tags=https://foo.org/project/tags) + (--tags=https://foo.org/project/tags). The option --stdlayout is + a shorthand way of setting trunk,tags,branches as the relative paths, + which is the Subversion default. If any of the other options are given + as well, they take precedence. --no-metadata;; Set the 'noMetadata' option in the [svn-remote] config. --use-svm-props;; @@ -94,7 +99,7 @@ COMMANDS This works similarly to 'svn update' or 'git-pull' except that it preserves linear history with 'git-rebase' instead of -'git-merge' for ease of dcommit-ing with git-svn. +'git-merge' for ease of dcommiting with git-svn. This accepts all options that 'git-svn fetch' and 'git-rebase' accepts. However '--fetch-all' only fetches from the current @@ -479,6 +484,38 @@ the user on the git side. git-svn does however follow copy history of the directory that it is tracking, however (much like how 'svn log' works). +CAVEATS +------- + +For the sake of simplicity and interoperating with a less-capable system +(SVN), it is recommended that all git-svn users clone, fetch and dcommit +directly from the SVN server, and avoid all git-clone/pull/merge/push +operations between git repositories and branches. The recommended +method of exchanging code between git branches and users is +git-format-patch and git-am, or just dcommiting to the SVN repository. + +Running 'git-merge' or 'git-pull' is NOT recommended on a branch you +plan to dcommit from. Subversion does not represent merges in any +reasonable or useful fashion; so users using Subversion cannot see any +merges you've made. Furthermore, if you merge or pull from a git branch +that is a mirror of an SVN branch, dcommit may commit to the wrong +branch. + +'git-clone' does not clone branches under the refs/remotes/ hierarchy or +any git-svn metadata, or config. So repositories created and managed with +using git-svn should use rsync(1) for cloning, if cloning is to be done +at all. + +Since 'dcommit' uses rebase internally, any git branches you git-push to +before dcommit on will require forcing an overwrite of the existing ref +on the remote repository. This is generally considered bad practice, +see the git-push(1) documentation for details. + +Do not use the --amend option of git-commit(1) on a change you've +already dcommitted. It is considered bad practice to --amend commits +you've already pushed to a remote repository for other users, and +dcommit with SVN is analogous to that. + BUGS ---- @@ -512,9 +549,9 @@ listed below are allowed: ------------------------------------------------------------------------ Keep in mind that the '*' (asterisk) wildcard of the local ref -(left of the ':') *must* be the farthest right path component; +(right of the ':') *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's own -independent path componet (surrounded by '/' or EOL). This +independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using gitlink:git-config[1] diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt index e97d15e8f2..71aad8b45b 100644 --- a/Documentation/git-svnimport.txt +++ b/Documentation/git-svnimport.txt @@ -68,6 +68,9 @@ When importing incrementally, you might need to edit the .git/svn2git file. Prepend 'rX: ' to commit messages, where X is the imported subversion revision. +-u:: + Replace underscores in tag names with periods. + -I <ignorefile_name>:: Import the svn:ignore directory property to files with this name in each directory. (The Subversion and GIT ignore diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 119117f0bd..990ae4f948 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -34,13 +34,6 @@ A GnuPG signed tag object will be created when `-s` or `-u committer identity for the current user is used to find the GnuPG key for signing. -`-d <tag>` deletes the tag. - -`-v <tag>` verifies the gpg signature of the tag. - -`-l <pattern>` lists tags with names that match the given pattern -(or all if no pattern is given). - OPTIONS ------- -a:: diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 2d01d9666f..434607bfb5 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -42,16 +42,13 @@ OPTIONS CONFIGURATION ------------- -By default, file and directories modes are set to 0666 or 0777. It is -possible to change this by setting the "umask" variable in the -repository configuration as follows : -[tar] - umask = 002 ;# group friendly - -The special umask value "user" indicates that the user's current umask -will be used instead. The default value is 002, which means group -readable/writable files and directories. +tar.umask:: + This variable can be used to restrict the permission bits of + tar archive entries. The default is 0002, which turns off the + world write bit. The special value "user" indicates that the + archiving user's umask will be used instead. See umask(2) for + details. EXAMPLES -------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 8017997fb9..ceca892a0d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,7 +9,8 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate] +'git' [--version] [--exec-path[=GIT_EXEC_PATH]] + [-p|--paginate|--no-pager] [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] [--help] COMMAND [ARGS] @@ -103,6 +104,9 @@ OPTIONS -p|--paginate:: Pipe all output into 'less' (or if set, $PAGER). +--no-pager:: + Do not pipe git output into a pager. + --git-dir=<path>:: Set the path to the repository. This can also be controlled by setting the GIT_DIR environment variable. @@ -116,7 +120,10 @@ OPTIONS variable. --bare:: - Same as --git-dir=`pwd`. + Treat the repository as a bare repository. If GIT_DIR + environment is not set, it is set to the current working + directory. + FURTHER DOCUMENTATION --------------------- @@ -469,7 +476,7 @@ include::core-intro.txt[] Authors ------- * git's founding father is Linus Torvalds <torvalds@osdl.org>. -* The current git nurse is Junio C Hamano <junkio@cox.net>. +* The current git nurse is Junio C Hamano <gitster@pobox.com>. * The git potty was written by Andres Ericsson <ae@op5.se>. * General upbringing is handled by the git-list <git@vger.kernel.org>. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 8b90a5b980..46f9d591aa 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -285,7 +285,7 @@ want to appear as the hunk header, like this: Note. A single level of backslashes are eaten by the configuration file parser, so you would need to double the backslashes; the pattern above picks a line that begins with a -backslash, and zero or more occurences of `sub` followed by +backslash, and zero or more occurrences of `sub` followed by `section` followed by open brace, to the end of line. There are a few built-in patterns to make this easier, and `tex` @@ -394,7 +394,7 @@ abc -foo -bar the attributes given to path `t/abc` are computed as follows: 1. By examining `t/.gitattributes` (which is in the same - diretory as the path in question), git finds that the first + directory as the path in question), git finds that the first line matches. `merge` attribute is set. It also finds that the second line matches, and attributes `foo` and `bar` are unset. @@ -410,7 +410,7 @@ the attributes given to path `t/abc` are computed as follows: a match, and `foo` is set, `bar` is reverted to unspecified state, and `baz` is unset. -As the result, the attributes assignement to `t/abc` becomes: +As the result, the attributes assignment to `t/abc` becomes: ---------------------------------------------------------------- foo set to true diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index 6836477ca8..c39edc57c4 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -176,7 +176,7 @@ hook does on its standard input. This hook does not affect the outcome of `git-receive-pack`, as it is called after the real work is done. -This supersedes the <<post-update,'post-update'>> hook in that it get's +This supersedes the <<post-update,'post-update'>> hook in that it gets both old and new values of all the refs in addition to their names. diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index bd9fbee99a..fff1068c54 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -339,7 +339,7 @@ $ git pull . remotes/bob/master ------------------------------------- Note that git pull always merges into the current branch, -regardless of what else is given on the commandline. +regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using diff --git a/Documentation/urls.txt b/Documentation/urls.txt index b38145faff..e67f9140ab 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -10,6 +10,7 @@ to name the remote repository: - https://host.xz/path/to/repo.git/ - git://host.xz/path/to/repo.git/ - git://host.xz/~user/path/to/repo.git/ +- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git @@ -18,7 +19,8 @@ to name the remote repository: SSH is the default transport protocol over the network. You can optionally specify which user to log-in as, and an alternate, scp-like syntax is also supported. Both syntaxes support -username expansion, as does the native git protocol. The following +username expansion, as does the native git protocol, but +only the former supports port specification. The following three are identical to the last three above, respectively: =============================================================== diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index f89952ad84..35298e626b 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4,7 +4,7 @@ ______________________________________________ Git is a fast distributed revision control system. -This manual is designed to be readable by someone with basic unix +This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git. <<repositories-and-branches>> and <<exploring-git-history>> explain how @@ -42,10 +42,9 @@ How to get a git repository It will be useful to have a git repository to experiment with as you read this manual. -The best way to get one is by using the gitlink:git-clone[1] command -to download a copy of an existing repository for a project that you -are interested in. If you don't already have a project in mind, here -are some interesting examples: +The best way to get one is by using the gitlink:git-clone[1] command to +download a copy of an existing repository. If you don't already have a +project in mind, here are some interesting examples: ------------------------------------------------ # git itself (approx. 10MB download): @@ -63,21 +62,18 @@ directory, you will see that it contains a copy of the project files, together with a special top-level directory named ".git", which contains all the information about the history of the project. -In most of the following, examples will be taken from one of the two -repositories above. - [[how-to-check-out]] How to check out a different version of a project ------------------------------------------------- -Git is best thought of as a tool for storing the history of a -collection of files. It stores the history as a compressed -collection of interrelated snapshots (versions) of the project's -contents. +Git is best thought of as a tool for storing the history of a collection +of files. It stores the history as a compressed collection of +interrelated snapshots of the project's contents. In git each such +version is called a <<def_commit,commit>>. A single git repository may contain multiple branches. It keeps track of them by keeping a list of <<def_head,heads>> which reference the -latest version on each branch; the gitlink:git-branch[1] command shows +latest commit on each branch; the gitlink:git-branch[1] command shows you the list of branch heads: ------------------------------------------------ @@ -149,32 +145,27 @@ current branch: ------------------------------------------------ $ git show -commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2 -Author: Jamal Hadi Salim <hadi@cyberus.ca> -Date: Sat Dec 2 22:22:25 2006 -0800 - - [XFRM]: Fix aevent structuring to be more complete. - - aevents can not uniquely identify an SA. We break the ABI with this - patch, but consensus is that since it is not yet utilized by any - (known) application then it is fine (better do it now than later). - - Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca> - Signed-off-by: David S. Miller <davem@davemloft.net> - -diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt -index 8be626f..d7aac9d 100644 ---- a/Documentation/networking/xfrm_sync.txt -+++ b/Documentation/networking/xfrm_sync.txt -@@ -47,10 +47,13 @@ aevent_id structure looks like: - - struct xfrm_aevent_id { - struct xfrm_usersa_id sa_id; -+ xfrm_address_t saddr; - __u32 flags; -+ __u32 reqid; - }; -... +commit 17cf781661e6d38f737f15f53ab552f1e95960d7 +Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)> +Date: Tue Apr 19 14:11:06 2005 -0700 + + Remove duplicate getenv(DB_ENVIRONMENT) call + + Noted by Tony Luck. + +diff --git a/init-db.c b/init-db.c +index 65898fa..b002dc6 100644 +--- a/init-db.c ++++ b/init-db.c +@@ -7,7 +7,7 @@ + + int main(int argc, char **argv) + { +- char *sha1_dir = getenv(DB_ENVIRONMENT), *path; ++ char *sha1_dir, *path; + int len, i; + + if (mkdir(".git", 0755) < 0) { ------------------------------------------------ As you can see, a commit shows who made the latest change, what they @@ -217,7 +208,7 @@ commits will help understand how the git organizes history. In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y. Equivalently, you could say -that Y is a descendent of X, or that there is a chain of parents +that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X. [[history-diagrams]] @@ -923,14 +914,14 @@ they look OK. [[Finding-comments-with-given-content]] Finding commits referencing a file with given content ------------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Somebody hands you a copy of a file, and asks which commits modified a file such that it contained the given content either before or after the commit. You can find out with this: ------------------------------------------------- -$ git log --raw -r --abbrev=40 --pretty=oneline -- filename | +$ git log --raw --abbrev=40 --pretty=oneline -- filename | grep -B 1 `git hash-object filename` ------------------------------------------------- @@ -1105,20 +1096,14 @@ backup files made by your editor. Of course, 'not' tracking files with git is just a matter of 'not' calling "`git add`" on them. But it quickly becomes annoying to have these untracked files lying around; e.g. they make "`git add .`" and "`git commit -a`" practically useless, and they keep -showing up in the output of "`git status`", etc. +showing up in the output of "`git status`". -Git therefore provides "exclude patterns" for telling git which files to -actively ignore. Exclude patterns are thoroughly explained in the -gitlink:gitignore[5] manual page, but the heart of the concept is simply -a list of files which git should ignore. Entries in the list may contain -globs to specify multiple files, or may be prefixed by "`!`" to -explicitly include (un-ignore) a previously excluded (ignored) file -(i.e. later exclude patterns override earlier ones). The following -example should illustrate such patterns: +You can tell git to ignore certain files by creating a file called .gitignore +in the top level of your working directory, with contents such as: ------------------------------------------------- # Lines starting with '#' are considered comments. -# Ignore foo.txt. +# Ignore any file named foo.txt. foo.txt # Ignore (generated) html files, *.html @@ -1128,41 +1113,20 @@ foo.txt *.[oa] ------------------------------------------------- -The next question is where to put these exclude patterns so that git can -find them. Git looks for exclude patterns in the following files: - -`.gitignore` files in your working tree::: - You may store multiple `.gitignore` files at various locations in your - working tree. Each `.gitignore` file is applied to the directory where - it's located, including its subdirectories. Furthermore, the - `.gitignore` files can be tracked like any other files in your working - tree; just do a "`git add .gitignore`" and commit. `.gitignore` is - therefore the right place to put exclude patterns that are meant to - be shared between all project participants, such as build output files - (e.g. `\*.o`), etc. -`.git/info/exclude` in your repo::: - Exclude patterns in this file are applied to the working tree as a - whole. Since the file is not located in your working tree, it does - not follow push/pull/clone like `.gitignore` can do. This is therefore - the place to put exclude patterns that are local to your copy of the - repo (i.e. 'not' shared between project participants), such as - temporary backup files made by your editor (e.g. `\*~`), etc. -The file specified by the `core.excludesfile` config directive::: - By setting the `core.excludesfile` config directive you can tell git - where to find more exclude patterns (see gitlink:git-config[1] for - more information on configuration options). This config directive - can be set in the per-repo `.git/config` file, in which case the - exclude patterns will apply to that repo only. Alternatively, you - can set the directive in the global `~/.gitconfig` file to apply - the exclude pattern to all your git repos. As with the above - `.git/info/exclude` (and, indeed, with git config directives in - general), this directive does not follow push/pull/clone, but remain - local to your repo(s). - -[NOTE] -In addition to the above alternatives, there are git commands that can take -exclude patterns directly on the command line. See gitlink:git-ls-files[1] -for an example of this. +See gitlink:gitignore[5] for a detailed explanation of the syntax. You can +also place .gitignore files in other directories in your working tree, and they +will apply to those directories and their subdirectories. The `.gitignore` +files can be added to your repository like any other files (just run `git add +.gitignore` and `git commit`, as usual), which is convenient when the exclude +patterns (such as patterns matching build output files) would also make sense +for other users who clone your repository. + +If you wish the exclude patterns to affect only certain repositories +(instead of every repository for a given project), you may instead put +them in a file in your repository named .git/info/exclude, or in any file +specified by the `core.excludesfile` configuration variable. Some git +commands can also take exclude patterns directly on the command line. +See gitlink:gitignore[5] for the details. [[how-to-merge]] How to merge @@ -1796,11 +1760,12 @@ taken from the message containing each patch. Public git repositories ----------------------- -Another way to submit changes to a project is to tell the maintainer of -that project to pull the changes from your repository using git-pull[1]. -In the section "<<getting-updates-with-git-pull, Getting updates with -git pull>>" we described this as a way to get updates from the "main" -repository, but it works just as well in the other direction. +Another way to submit changes to a project is to tell the maintainer +of that project to pull the changes from your repository using +gitlink:git-pull[1]. In the section "<<getting-updates-with-git-pull, +Getting updates with git pull>>" we described this as a way to get +updates from the "main" repository, but it works just as well in the +other direction. If you and the maintainer both have accounts on the same machine, then you can just pull changes from each other's repositories directly; @@ -1911,7 +1876,7 @@ gitlink:git-update-server-info[1], and the documentation link:hooks.html[Hooks used by git].) Advertise the url of proj.git. Anybody else should then be able to -clone or pull from that url, for example with a commandline like: +clone or pull from that url, for example with a command line like: ------------------------------------------------- $ git clone http://yourserver.com/~you/proj.git @@ -2057,7 +2022,8 @@ $ cd work Linus's tree will be stored in the remote branch named origin/master, and can be updated using gitlink:git-fetch[1]; you can track other public trees using gitlink:git-remote[1] to set up a "remote" and -git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>. +gitlink:git-fetch[1] to keep them up-to-date; see +<<repositories-and-branches>>. Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using @@ -2512,9 +2478,9 @@ $ gitk origin..mywork & And browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using cherry-pick, and possibly modifying them as you go using commit --amend. -The git-gui[1] command may also help as it allows you to individually -select diff hunks for inclusion in the index (by right-clicking on the -diff hunk and choosing "Stage Hunk for Commit"). +The gitlink:git-gui[1] command may also help as it allows you to +individually select diff hunks for inclusion in the index (by +right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches: @@ -2531,7 +2497,7 @@ them again with gitlink:git-am[1]. Other tools ----------- -There are numerous other tools, such as stgit, which exist for the +There are numerous other tools, such as StGIT, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual. @@ -3961,8 +3927,8 @@ This is a work in progress. The basic requirements: - It must be readable in order, from beginning to end, by - someone intelligent with a basic grasp of the unix - commandline, but without any special knowledge of git. If + someone intelligent with a basic grasp of the UNIX + command line, but without any special knowledge of git. If necessary, any other prerequisites should be specifically mentioned as they arise. - Whenever possible, section headings should clearly describe |