summaryrefslogtreecommitdiff
path: root/Documentation/revisions.txt
AgeCommit message (Collapse)AuthorFilesLines
2016-02-10Merge branch 'wp/sha1-name-negative-match'Libravatar Junio C Hamano1-5/+6
A new "<branch>^{/!-<pattern>}" notation can be used to name a commit that is reachable from <branch> that does not match the given <pattern>. * wp/sha1-name-negative-match: object name: introduce '^{/!-<negative pattern>}' notation test for '!' handling in rev-parse's named commits
2016-02-01object name: introduce '^{/!-<negative pattern>}' notationLibravatar Will Palmer1-5/+6
To name a commit, you can now use the :/!-<negative pattern> regex style, and consequentially, say $ git rev-parse HEAD^{/!-foo} and it will return the hash of the first commit reachable from HEAD, whose commit message does not contain "foo". This is the opposite of the existing <rev>^{/<pattern>} syntax. The specific use-case this is intended for is to perform an operation, excluding the most-recent commits containing a particular marker. For example, if you tend to make "work in progress" commits, with messages beginning with "WIP", you work, then it could be useful to diff against "the most recent commit which was not a WIP commit". That sort of thing now possible, via commands such as: $ git diff @^{/!-^WIP} The leader '/!-', rather than simply '/!', to denote a negative match, is chosen to leave room for additional modifiers in the future. Signed-off-by: Will Palmer <wmpalmer@gmail.com> Signed-off-by: Stephen P. Smith <ischis2@cox.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-20Documentation: remove unnecessary backslashesLibravatar Matthew Kraai1-10/+10
asciidoctor does not remove backslashes used to escape curly brackets from the HTML output if the contents of the curly brackets are empty or contain at least a <, -, or space. asciidoc does not require the backslashes in these cases, so just remove them. Signed-off-by: Matthew Kraai <matt.kraai@abbott.com> Reported-by: Philip Oakley <philipoakley@iee.org> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-05-22sha1_name: implement @{push} shorthandLibravatar Jeff King1-0/+25
In a triangular workflow, each branch may have two distinct points of interest: the @{upstream} that you normally pull from, and the destination that you normally push to. There isn't a shorthand for the latter, but it's useful to have. For instance, you may want to know which commits you haven't pushed yet: git log @{push}.. Or as a more complicated example, imagine that you normally pull changes from origin/master (which you set as your @{upstream}), and push changes to your own personal fork (e.g., as myfork/topic). You may push to your fork from multiple machines, requiring you to integrate the changes from the push destination, rather than upstream. With this patch, you can just do: git rebase @{push} rather than typing out the full name. The heavy lifting is all done by branch_get_push; here we just wire it up to the "@{push}" syntax. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-13Documentation: mention config sources for @{upstream}Libravatar W. Trevor King1-1/+3
The earlier documentation made vague references to "is set to build on". Flesh that out with references to the config settings, so folks can use git-config(1) to get more detail on what @{upstream} means. For example, @{upstream} does not care about remote.pushdefault or branch.<name>.pushremote. Signed-off-by: W. Trevor King <wking@tremily.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-01-21Documentation: @{-N} can refer to a commitLibravatar Thomas Rast1-1/+1
The @{-N} syntax always referred to the N-th last thing checked out, which can be either a branch or a commit (for detached HEAD cases). However, the documentation only mentioned branches. Edit in a "/commit" in the appropriate places. Reported-by: Kevin <ikke@ikke.info> Signed-off-by: Thomas Rast <tr@thomasrast.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-20Merge branch 'fc/at-head'Libravatar Junio C Hamano1-0/+3
Instead of typing four capital letters "HEAD", you can say "@" now, e.g. "git log @". * fc/at-head: Add new @ shortcut for HEAD sha1-name: pass len argument to interpret_branch_name()
2013-09-20Merge branch 'rh/peeling-tag-to-tag'Libravatar Junio C Hamano1-0/+3
Make "foo^{tag}" to peel a tag to itself, i.e. no-op., and fail if "foo" is not a tag. "git rev-parse --verify v1.0^{tag}" would be a more convenient way to say "test $(git cat-file -t v1.0) = tag". * rh/peeling-tag-to-tag: peel_onion: do not assume length of x_type globals peel_onion(): add support for <rev>^{tag}
2013-09-12Add new @ shortcut for HEADLibravatar Felipe Contreras1-0/+3
Typing 'HEAD' is tedious, especially when we can use '@' instead. The reason for choosing '@' is that it follows naturally from the ref@op syntax (e.g. HEAD@{u}), except we have no ref, and no operation, and when we don't have those, it makes sens to assume 'HEAD'. So now we can use 'git show @~1', and all that goody goodness. Until now '@' was a valid name, but it conflicts with this idea, so let's make it invalid. Probably very few people, if any, used this name. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-04revisions.txt: fix and clarify <rev>^{<type>}Libravatar Richard Hansen1-4/+8
If possible, <rev> will be dereferenced even if it is not a tag type (e.g., commit dereferenced to a tree). Signed-off-by: Richard Hansen <rhansen@bbn.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-03peel_onion(): add support for <rev>^{tag}Libravatar Richard Hansen1-0/+3
Complete the <rev>^{<type>} family of object descriptors by having <rev>^{tag} dereference <rev> until a tag object is found (or fail if unable). At first glance this may not seem very useful, as commits, trees, and blobs cannot be peeled to a tag, and a tag would just peel to itself. However, this can be used to ensure that <rev> names a tag object: $ git rev-parse --verify v1.8.4^{tag} 04f013dc38d7512eadb915eba22efc414f18b869 $ git rev-parse --verify master^{tag} error: master^{tag}: expected tag type, but the object dereferences to tree type fatal: Needed a single revision Users can already ensure that <rev> is a tag object by checking the output of 'git cat-file -t <rev>', but: * users may expect <rev>^{tag} to exist given that <rev>^{commit}, <rev>^{tree}, and <rev>^{blob} all exist * this syntax is more convenient/natural in some circumstances Signed-off-by: Richard Hansen <rhansen@bbn.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-14Revert "Add new @ shortcut for HEAD"Libravatar Junio C Hamano1-3/+0
This reverts commit cdfd94837b27c220f70f032b596ea993d195488f, as it does not just apply to "@" (and forms with modifiers like @{u} applied to it), but also affects e.g. "refs/heads/@/foo", which it shouldn't. The basic idea of giving a short-hand might be good, and the topic can be retried later, but let's revert to avoid affecting existing use cases for now for the upcoming release.
2013-05-08Add new @ shortcut for HEADLibravatar Felipe Contreras1-0/+3
Typing 'HEAD' is tedious, especially when we can use '@' instead. The reason for choosing '@' is that it follows naturally from the ref@op syntax (e.g. HEAD@{u}), except we have no ref, and no operation, and when we don't have those, it makes sens to assume 'HEAD'. So now we can use 'git show @~1', and all that goody goodness. Until now '@' was a valid name, but it conflicts with this idea, so let's make it invalid. Probably very few people, if any, used this name. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-26Merge branch 'rr/shortlog-doc'Libravatar Junio C Hamano1-2/+4
Update documentation for "log" and "shortlog". * rr/shortlog-doc: builtin/shortlog.c: make usage string consistent with log builtin/log.c: make usage string consistent with doc git-shortlog.txt: make SYNOPSIS match log, update OPTIONS git-log.txt: rewrite note on why "--" may be required git-log.txt: generalize <since>..<until> git-log.txt: order OPTIONS properly; move <since>..<until> revisions.txt: clarify the .. and ... syntax git-shortlog.txt: remove (-h|--help) from OPTIONS
2013-04-21revisions.txt: clarify the .. and ... syntaxLibravatar Ramkumar Ramachandra1-2/+4
In <rev1>..<rev2> and <rev1>...<rev2>, if either <rev1> or <rev2> is omitted, it defaults to 'HEAD'. Add this detail to the document. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-21Merge branch 'ta/glossary'Libravatar Junio C Hamano1-2/+2
* ta/glossary: glossary: improve definitions of refspec and pathspec The name of the hash function is "SHA-1", not "SHA1" glossary: improve description of SHA-1 related topics glossary: remove outdated/misleading/irrelevant entries
2013-04-15The name of the hash function is "SHA-1", not "SHA1"Libravatar Thomas Ackermann1-2/+2
Use "SHA-1" instead of "SHA1" whenever we talk about the hash function. When used as a programming symbol, we keep "SHA1". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-12Sync with 'maint'Libravatar Junio C Hamano1-1/+1
* maint: Correct common spelling mistakes in comments and tests kwset: fix spelling in comments precompose-utf8: fix spelling of "want" in error message compat/nedmalloc: fix spelling in comments compat/regex: fix spelling and grammar in comments obstack: fix spelling of similar contrib/subtree: fix spelling of accidentally git-remote-mediawiki: spelling fixes doc: various spelling fixes fast-export: fix argument name in error messages Documentation: distinguish between ref and offset deltas in pack-format i18n: make the translation of -u advice in one go
2013-04-12doc: various spelling fixesLibravatar Stefano Lattarini1-1/+1
Most of these were found using Lucas De Marchi's codespell tool. Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-03Merge branch 'jc/sha1-name-object-peeler'Libravatar Junio C Hamano1-0/+5
There was no good way to ask "I have a random string that came from outside world. I want to turn it into a 40-hex object name while making sure such an object exists". A new peeling suffix ^{object} can be used for that purpose, together with "rev-parse --verify". * jc/sha1-name-object-peeler: peel_onion(): teach $foo^{object} peeler peel_onion: disambiguate to favor tree-ish when we know we want a tree-ish
2013-03-31peel_onion(): teach $foo^{object} peelerLibravatar Junio C Hamano1-0/+5
A string that names an object can be suffixed with ^{type} peeler to say "I have this object name; peel it until you get this type. If you cannot do so, it is an error". v1.8.2^{commit} asks for a commit that is pointed at an annotated tag v1.8.2; v1.8.2^{tree} unwraps it further to the top-level tree object. A special suffix ^{} (i.e. no type specified) means "I do not care what it unwraps to; just peel annotated tag until you get something that is not a tag". When you have a random user-supplied string, you can turn it to a bare 40-hex object name, and cause it to error out if such an object does not exist, with: git rev-parse --verify "$userstring^{}" for most objects, but this does not yield the tag object name when $userstring refers to an annotated tag. Introduce a new suffix, ^{object}, that only makes sure the given name refers to an existing object. Then git rev-parse --verify "$userstring^{object}" becomes a way to make sure $userstring refers to an existing object. This is necessary because the plumbing "rev-parse --verify" is only about "make sure the argument is something we can feed to get_sha1() and turn it into a raw 20-byte object name SHA-1" and is not about "make sure that 20-byte object name SHA-1 refers to an object that exists in our object store". When the given $userstring is already a 40-hex, by definition "rev-parse --verify $userstring" can turn it into a raw 20-byte object name. With "$userstring^{object}", we can make sure that the 40-hex string names an object that exists in our object store before "--verify" kicks in. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-03-17Merge branch 'maint'Libravatar Junio C Hamano1-4/+4
* maint: rev-parse: clarify documentation of $name@{upstream} syntax sha1_name: pass object name length to diagnose_invalid_sha1_path() Makefile: keep LIB_H entries together and sorted
2013-03-17rev-parse: clarify documentation of $name@{upstream} syntaxLibravatar Kacper Kornet1-4/+4
"git rev-parse" interprets string in string@{upstream} as a name of a branch not a ref. For example, refs/heads/master@{upstream} looks for an upstream branch that is merged by git-pull to ref refs/heads/refs/heads/master not to refs/heads/master. However the documentation could mislead a user to believe that the string is interpreted as ref. Signed-off-by: Kacper Kornet <draenog@pld-linux.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-1/+1
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-07Merge branch 'nd/branch-v-alignment'Libravatar Junio C Hamano1-0/+2
Output from "git branch -v" contains "(no branch)" that could be localized, but the code to align it along with the names of branches were counting in bytes, not in display columns. * nd/branch-v-alignment: branch -v: align even when branch names are in UTF-8
2012-08-27branch -v: align even when branch names are in UTF-8Libravatar Nguyễn Thái Ngọc Duy1-0/+2
Branch names are usually in ASCII so they are not the problem. The problem most likely comes from "(no branch)" translation, which is in UTF-8 and makes display-width calculation just wrong. Clarify this by renaming the field "len" in struct ref_item to "width", as it stores the display-width and is used to compute the width of the screen needed to show the names of all the branches, and compute the display width using utf8_strwidth(), not byte-length with strlen(). Update document to mention the fact that we may want ref names in UTF-8. Encodings that produce invalid UTF-8 are safe as utf8_strwidth() falls back to strlen(). The ones that incidentally produce valid UTF-8 sequences will cause misalignment. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-23specifying ranges: we did not mean to make ".." an empty setLibravatar Junio C Hamano1-0/+7
Either end of revision range operator can be omitted to default to HEAD, as in "origin.." (what did I do since I forked) or "..origin" (what did they do since I forked). But the current parser interprets ".." as an empty range "HEAD..HEAD", and worse yet, because ".." does exist on the filesystem, we get this annoying output: $ cd Documentation/howto $ git log .. ;# give me recent commits that touch Documentation/ area. fatal: ambiguous argument '..': both revision and filename Use '--' to separate filenames from revisions Surely we could say "git log ../" or even "git log -- .." to disambiguate, but we shouldn't have to. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-07-24Enumerate revision range specifiers in the documentationLibravatar Junio C Hamano1-0/+31
It was a bit hard to learn how <rev>^@, <rev>^! and various other forms of range specifiers are used, because they were discussed mostly in the prose part of the documentation, unlike various forms of extended SHA-1 expressions that are listed in an enumerated list. Also add a few more examples showing use of <rev>, <rev>..<rev> and <rev>^! forms, stolen from a patch by Max Horn. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-07-05Make <refname> documentation more consistent.Libravatar Max Horn1-6/+6
Formerly, the documentation for <refname> would occasionally say <name> instead of <refname>. Now it uniformly uses <refname>. Signed-off-by: Max Horn <max@quendi.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-03-02Documentation: do not assume that n > 1 in <rev>~$nLibravatar Junio C Hamano1-1/+1
We explained <rev>~<n> as <n>th generation grand-parent, but a reader got confused by the "grand-" part when <n> is 1. Reword it with "ancestor"; with the "generation" and "following only the first parents" around there, what we try to describe should be clear enough now. Noticed-by: Luke Diamand <luke@diamand.org> Helped-by: Thomas Rast <trast@inf.ethz.ch> Helped-by: Andreas Ericsson <ae@op5.se> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-04revisions.txt: language improvementsLibravatar Michael J Gruber1-35/+35
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-01revisions.txt: structure with a labelled listLibravatar Michael J Gruber1-35/+51
Currently, the reader has to parse a textual description in order to find a specific syntax in the list. Restructure as a labelled list with systematic labels as well as concrete examples as a visual guide. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-01revisions.txt: consistent use of quotesLibravatar Michael J Gruber1-52/+52
Our use of quotes is inconsistent everywhere and within some files. Before reworking the structure of revisions.txt, make the quotes consistent: `git command` 'some snippet or term' The former gets typeset as code, the latter with some form of emphasis. the man backend uses two types of emphasis. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-02-21Introduce CHERRY_PICK_HEADLibravatar Jay Soffian1-1/+4
When a cherry-pick conflicts git advises: $ git commit -c <original commit id> to preserve the original commit message and authorship. Instead, let's record the original commit id in CHERRY_PICK_HEAD and advise: $ git commit -c CHERRY_PICK_HEAD A later patch teaches git to handle the '-c CHERRY_PICK_HEAD' part. Note that we record CHERRY_PICK_HEAD even in the case where there are no conflicts so that we may use it to communicate authorship to commit; this will then allow us to remove set_author_ident_env from revert.c. However, we do not record CHERRY_PICK_HEAD when --no-commit is used, as presumably the user intends to further edit the commit and possibly even cherry-pick additional commits on top. Tests and documentation contributed by Jonathan Nieder. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Jay Soffian <jaysoffian@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-12-21Merge branch 'nd/oneline-sha1-name-from-specific-ref'Libravatar Junio C Hamano1-0/+6
* nd/oneline-sha1-name-from-specific-ref: get_sha1: handle special case $commit^{/} get_sha1: support $commit^{/regex} syntax get_sha1_oneline: make callers prepare the commit list to traverse get_sha1_oneline: fix lifespan rule of temp_commit_buffer variable
2010-12-14get_sha1: support $commit^{/regex} syntaxLibravatar Nguyễn Thái Ngọc Duy1-0/+6
This works like ":/regex" syntax that finds a recently created commit starting from all refs, but limits the discovery to those reachable from the named commit. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-12-07get_sha1: support relative path ":path" syntaxLibravatar Nguyễn Thái Ngọc Duy1-0/+4
Currently :path and ref:path can be used to refer to a specific object in index or ref respectively. "path" component is absolute path. This patch allows "path" to be written as "./path" or "../path", which is relative to user's original cwd. This does not work in commands for which startup_info is NULL (i.e. non-builtin ones, it seems none of them needs this anyway). Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-09-27update comment and documentation for :/foo syntaxLibravatar Matthieu Moy1-1/+3
The documentation in revisions.txt did not match the implementation, and the comment in sha1_name.c was incomplete. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-05Documentation: split off rev doc into include fileLibravatar Michael J Gruber1-0/+199
Currently, the documentation for revisions and ranges sits in the git-rev-parse man page, i.e. a plumbing man page, along with the documentation of all rev-parse modes. Split off the revisions and ranges section into an included file to prepare for restructuring. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>