From b8ec59234ba2c1833e29eece9ed87f7a471cbae2 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Sun, 22 Oct 2006 13:23:31 +0200 Subject: Build in shortlog [jc: with minimum squelching of compiler warning under "-pedantic" compilation options.] Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- Documentation/git-shortlog.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index d54fc3e5c6..95fa9010c1 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,6 +8,7 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- git-log --pretty=short | 'git-shortlog' [-h] [-n] [-s] +git-shortlog [-n|--number] [-s|--summary] [...] DESCRIPTION ----------- -- cgit v1.3-5-g9baa From 17bcdad3b7baa3b12c662663372f1e3cd560dd8e Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 20 Nov 2006 01:06:09 -0800 Subject: git-merge: make it usable as the first class UI This teaches the oft-requested syntax git merge $commit to implement merging the named commit to the current branch. This hopefully would make "git merge" usable as the first class UI instead of being a mere backend for "git pull". Most notably, $commit above can be any committish, so you can say for example: git merge js/shortlog~2 to merge early part of a topic branch without merging the rest of it. A custom merge message can be given with the new --message= parameter. The message is prepended in front of the usual "Merge ..." message autogenerated with fmt-merge-message. Signed-off-by: Junio C Hamano --- Documentation/git-merge.txt | 18 +++++++++---- git-merge.sh | 61 +++++++++++++++++++++++++++++++++++++++------ 2 files changed, 67 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index bebf30ad3d..e2954aa76e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -8,12 +8,14 @@ git-merge - Grand Unified Merge Driver SYNOPSIS -------- -'git-merge' [-n] [--no-commit] [-s ]... ... - +[verse] +'git-merge' [-n] [--no-commit] [--squash] [-s ]... + [--reflog-action=] + -m= ... DESCRIPTION ----------- -This is the top-level user interface to the merge machinery +This is the top-level interface to the merge machinery which drives multiple merge strategy scripts. @@ -27,13 +29,19 @@ include::merge-options.txt[] to give a good default for automated `git-merge` invocations. :: - our branch head commit. + Our branch head commit. This has to be `HEAD`, so new + syntax does not require it :: - other branch head merged into our branch. You need at + Other branch head merged into our branch. You need at least one . Specifying more than one obviously means you are trying an Octopus. +--reflog-action=:: + This is used internally when `git-pull` calls this command + to record that the merge was created by `pull` command + in the `ref-log` entry that results from the merge. + include::merge-strategies.txt[] diff --git a/git-merge.sh b/git-merge.sh index 84c3acfe63..25deb1e867 100755 --- a/git-merge.sh +++ b/git-merge.sh @@ -3,7 +3,8 @@ # Copyright (c) 2005 Junio C Hamano # -USAGE='[-n] [--no-commit] [--squash] [-s ]... +' +USAGE='[-n] [--no-commit] [--squash] [-s ] [--reflog-action=] [-m=] +' + . git-sh-setup LF=' @@ -92,7 +93,7 @@ finish () { case "$#" in 0) usage ;; esac -rloga= +rloga= have_message= while case "$#" in 0) break ;; esac do case "$1" in @@ -125,17 +126,63 @@ do --reflog-action=*) rloga=`expr "z$1" : 'z-[^=]*=\(.*\)'` ;; + -m=*|--m=*|--me=*|--mes=*|--mess=*|--messa=*|--messag=*|--message=*) + merge_msg=`expr "z$1" : 'z-[^=]*=\(.*\)'` + have_message=t + ;; + -m|--m|--me|--mes|--mess|--messa|--messag|--message) + shift + case "$#" in + 1) usage ;; + esac + merge_msg="$1" + have_message=t + ;; -*) usage ;; *) break ;; esac shift done -merge_msg="$1" -shift -head_arg="$1" -head=$(git-rev-parse --verify "$1"^0) || usage -shift +# This could be traditional "merge HEAD ..." and the +# way we can tell it is to see if the second token is HEAD, but some +# people might have misused the interface and used a committish that +# is the same as HEAD there instead. Traditional format never would +# have "-m" so it is an additional safety measure to check for it. + +if test -z "$have_message" && + second_token=$(git-rev-parse --verify "$2^0" 2>/dev/null) && + head_commit=$(git-rev-parse --verify "HEAD" 2>/dev/null) && + test "$second_token" = "$head_commit" +then + merge_msg="$1" + shift + head_arg="$1" + shift +else + # We are invoked directly as the first-class UI. + head_arg=HEAD + + # All the rest are the commits being merged; prepare + # the standard merge summary message to be appended to + # the given message. If remote is invalid we will die + # later in the common codepath so we discard the error + # in this loop. + merge_name=$(for remote + do + rh=$(git-rev-parse --verify "$remote"^0 2>/dev/null) + if git show-ref -q --verify "refs/heads/$remote" + then + what=branch + else + what=commit + fi + echo "$rh $what '$remote'" + done | git-fmt-merge-msg + ) + merge_msg="${merge_msg:+$merge_msg$LF$LF}$merge_name" +fi +head=$(git-rev-parse --verify "$head_arg"^0) || usage # All the rest are remote heads test "$#" = 0 && usage ;# we need at least one remote head. -- cgit v1.3-5-g9baa From 75e6e2132006770156d9df1881b4114862919c94 Mon Sep 17 00:00:00 2001 From: Lars Hjemli Date: Fri, 24 Nov 2006 14:45:10 +0100 Subject: Add -v and --abbrev options to git-branch The new -v option makes git-branch show the abbreviated sha1 + subjectline for each branch. Additionally, minimum abbreviation length can be specified with --abbrev= Signed-off-by: Lars Hjemli Signed-off-by: Junio C Hamano --- Documentation/git-branch.txt | 9 ++++++++- builtin-branch.c | 48 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 51 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 5376760813..4f5b5d5028 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r] [-a] +'git-branch' [-r] [-a] [-v] [--abbrev=] 'git-branch' [-l] [-f] [] 'git-branch' (-d | -D) ... @@ -52,6 +52,13 @@ OPTIONS -a:: List both remote-tracking branches and local branches. +-v:: + Show sha1 and subject message for each head. + +--abbrev=:: + Alter minimum display length for sha1 in output listing, + default value is 7. + :: The name of the branch to create or delete. The new branch name must pass all checks defined by diff --git a/builtin-branch.c b/builtin-branch.c index 22e3285a4c..69b7b55d86 100644 --- a/builtin-branch.c +++ b/builtin-branch.c @@ -11,7 +11,7 @@ #include "builtin.h" static const char builtin_branch_usage[] = -"git-branch (-d | -D) | [-l] [-f] [] | [-r] | [-a]"; +"git-branch (-d | -D) | [-l] [-f] [] | [-r | -a] [-v] [--abbrev=] "; static const char *head; @@ -87,10 +87,11 @@ static void delete_branches(int argc, const char **argv, int force) struct ref_item { char *name; unsigned int kind; + unsigned char sha1[20]; }; struct ref_list { - int index, alloc; + int index, alloc, maxwidth; struct ref_item *list; int kinds; }; @@ -100,6 +101,7 @@ static int append_ref(const char *refname, const unsigned char *sha1, int flags, struct ref_list *ref_list = (struct ref_list*)(cb_data); struct ref_item *newitem; int kind = REF_UNKNOWN_TYPE; + int len; /* Detect kind */ if (!strncmp(refname, "refs/heads/", 11)) { @@ -128,6 +130,10 @@ static int append_ref(const char *refname, const unsigned char *sha1, int flags, newitem = &(ref_list->list[ref_list->index++]); newitem->name = xstrdup(refname); newitem->kind = kind; + hashcpy(newitem->sha1, sha1); + len = strlen(newitem->name); + if (len > ref_list->maxwidth) + ref_list->maxwidth = len; return 0; } @@ -151,7 +157,24 @@ static int ref_cmp(const void *r1, const void *r2) return strcmp(c1->name, c2->name); } -static void print_ref_list(int kinds) +static void print_ref_info(const unsigned char *sha1, int abbrev) +{ + struct commit *commit; + char subject[256]; + + + commit = lookup_commit(sha1); + if (commit && !parse_commit(commit)) + pretty_print_commit(CMIT_FMT_ONELINE, commit, ~0, + subject, sizeof(subject), 0, + NULL, NULL, 0); + else + strcpy(subject, " **** invalid ref ****"); + + printf(" %s %s\n", find_unique_abbrev(sha1, abbrev), subject); +} + +static void print_ref_list(int kinds, int verbose, int abbrev) { int i; char c; @@ -169,7 +192,13 @@ static void print_ref_list(int kinds) !strcmp(ref_list.list[i].name, head)) c = '*'; - printf("%c %s\n", c, ref_list.list[i].name); + if (verbose) { + printf("%c %-*s", c, ref_list.maxwidth, + ref_list.list[i].name); + print_ref_info(ref_list.list[i].sha1, abbrev); + } + else + printf("%c %s\n", c, ref_list.list[i].name); } free_ref_list(&ref_list); @@ -215,6 +244,7 @@ static void create_branch(const char *name, const char *start, int cmd_branch(int argc, const char **argv, const char *prefix) { int delete = 0, force_delete = 0, force_create = 0; + int verbose = 0, abbrev = DEFAULT_ABBREV; int reflog = 0; int kinds = REF_LOCAL_BRANCH; int i; @@ -255,6 +285,14 @@ int cmd_branch(int argc, const char **argv, const char *prefix) reflog = 1; continue; } + if (!strncmp(arg, "--abbrev=", 9)) { + abbrev = atoi(arg+9); + continue; + } + if (!strcmp(arg, "-v")) { + verbose = 1; + continue; + } usage(builtin_branch_usage); } @@ -268,7 +306,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix) if (delete) delete_branches(argc - i, argv + i, force_delete); else if (i == argc) - print_ref_list(kinds); + print_ref_list(kinds, verbose, abbrev); else if (i == argc - 1) create_branch(argv[i], head, force_create, reflog); else if (i == argc - 2) -- cgit v1.3-5-g9baa From 61f5cb7f0d9ea6990f331bd7082630691c88abd2 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 24 Oct 2006 21:48:55 -0700 Subject: git-commit: show --summary after successful commit. Sometimes people accidentally commit files in wrong mode bits. Show --summary output for the HEAD commit after successful commit as a final sanity check. Signed-off-by: Junio C Hamano --- Documentation/tutorial-2.txt | 1 + git-commit.sh | 3 +++ 2 files changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 42b6e7d7d2..6389de5ef7 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -23,6 +23,7 @@ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe + create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" ------------------------------------------------ diff --git a/git-commit.sh b/git-commit.sh index 81c3a0cb61..7e9742d5e7 100755 --- a/git-commit.sh +++ b/git-commit.sh @@ -629,4 +629,7 @@ if test -x "$GIT_DIR"/hooks/post-commit && test "$ret" = 0 then "$GIT_DIR"/hooks/post-commit fi + +test "$ret" = 0 && git-diff-tree --summary --root --no-commit-id HEAD + exit "$ret" -- cgit v1.3-5-g9baa From 93ee7823c0a48b7a51ac0e145b5bcc450c805ea4 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Sat, 25 Nov 2006 22:45:02 -0500 Subject: Documentation: clarify tutorial pull/merge discussion Attempt to clarify somewhat the difference between pull and merge, and give a little more details on the pull syntax. I'm still not happy with this section: the explanation of the origin branch isn't great, but maybe that should be left alone pending the use-separate-remotes change; and we need to explain how to set up a public repository and push to it. Signed-off-by: J. Bruce Fields Signed-off-by: Junio C Hamano --- Documentation/tutorial.txt | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) (limited to 'Documentation') diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 1e4ddfbd11..35af81a3de 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -209,29 +209,28 @@ at /home/bob/myrepo. She does this with: ------------------------------------------------ $ cd /home/alice/project -$ git pull /home/bob/myrepo +$ git pull /home/bob/myrepo master ------------------------------------------------ -This actually pulls changes from the branch in Bob's repository named -"master". Alice could request a different branch by adding the name -of the branch to the end of the git pull command line. +This merges the changes from Bob's "master" branch into Alice's +current branch. If Alice has made her own changes in the meantime, +then she may need to manually fix any conflicts. (Note that the +"master" argument in the above command is actually unnecessary, as it +is the default.) -This merges Bob's changes into her repository; "git log" will -now show the new commits. If Alice has made her own changes in the -meantime, then Bob's changes will be merged in, and she will need to -manually fix any conflicts. +The "pull" command thus performs two operations: it fetches changes +from a remote branch, then merges them into the current branch. -A more cautious Alice might wish to examine Bob's changes before -pulling them. She can do this by creating a temporary branch just -for the purpose of studying Bob's changes: +You can perform the first operation alone using the "git fetch" +command. For example, Alice could create a temporary branch just to +track Bob's changes, without merging them with her own, using: ------------------------------------- $ git fetch /home/bob/myrepo master:bob-incoming ------------------------------------- which fetches the changes from Bob's master branch into a new branch -named bob-incoming. (Unlike git pull, git fetch just fetches a copy -of Bob's line of development without doing any merging). Then +named bob-incoming. Then ------------------------------------- $ git log -p master..bob-incoming @@ -240,8 +239,8 @@ $ git log -p master..bob-incoming shows a list of all the changes that Bob made since he branched from Alice's master branch. -After examining those changes, and possibly fixing things, Alice can -pull the changes into her master branch: +After examining those changes, and possibly fixing things, Alice +could pull the changes into her master branch: ------------------------------------- $ git checkout master @@ -251,6 +250,18 @@ $ git pull . bob-incoming The last command is a pull from the "bob-incoming" branch in Alice's own repository. +Alice could also perform both steps at once with: + +------------------------------------- +$ git pull /home/bob/myrepo master:bob-incoming +------------------------------------- + +This is just like the "git pull /home/bob/myrepo master" that we saw +before, except that it also stores the unmerged changes from bob's +master branch in bob-incoming before merging them into Alice's +current branch. Note that git pull always merges into the current +branch, regardless of what else is given on the commandline. + Later, Bob can update his repo with Alice's latest changes using ------------------------------------- -- cgit v1.3-5-g9baa From fde97d8ac63efa466dd48436d2178bd364b846de Mon Sep 17 00:00:00 2001 From: Sean Date: Mon, 27 Nov 2006 14:37:43 -0500 Subject: Update documentation to remove incorrect GIT_DIFF_OPTS example. Git no longer calls an external diff program to generate patches. Remove the documentation which suggests that you can pass arbitrary diff options via the GIT_DIFF_OPTS environment variable. Signed-off-by: Sean Estabrooks Signed-off-by: Junio C Hamano --- Documentation/diff-format.txt | 57 +++++-------------------------------------- Documentation/git.txt | 32 +++++++++++++++++++++--- 2 files changed, 34 insertions(+), 55 deletions(-) (limited to 'Documentation') diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index e4520e28e5..883c1bb0a6 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -65,62 +65,17 @@ Generating patches with -p When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a '-p' option, they do not produce the output described above; -instead they produce a patch file. +instead they produce a patch file. You can customize the creation +of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS +environment variables. -The patch generation can be customized at two levels. - -1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set, - these commands internally invoke "diff" like this: - - diff -L a/ -L b/ -pu -+ -For added files, `/dev/null` is used for . For removed -files, `/dev/null` is used for -+ -The "diff" formatting options can be customized via the -environment variable 'GIT_DIFF_OPTS'. For example, if you -prefer context diff: - - GIT_DIFF_OPTS=-c git-diff-index -p HEAD - - -2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the - program named by it is called, instead of the diff invocation - described above. -+ -For a path that is added, removed, or modified, -'GIT_EXTERNAL_DIFF' is called with 7 parameters: - - path old-file old-hex old-mode new-file new-hex new-mode -+ -where: - - -file:: are files GIT_EXTERNAL_DIFF can use to read the - contents of , - -hex:: are the 40-hexdigit SHA1 hashes, - -mode:: are the octal representation of the file modes. - -+ -The file parameters can point at the user's working file -(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` -when a new file is added), or a temporary file (e.g. `old-file` in the -index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the -temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. - -For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 -parameter, . - - -git specific extension to diff format -------------------------------------- - -What -p option produces is slightly different from the -traditional diff format. +What the -p option produces is slightly different from the traditional +diff format. 1. It is preceded with a "git diff" header, that looks like this: - diff --git a/file1 b/file2 + diff --git a/file1 b/file2 + The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, diff --git a/Documentation/git.txt b/Documentation/git.txt index 619d65685e..6382ef0a02 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -639,11 +639,35 @@ git Commits git Diffs ~~~~~~~~~ 'GIT_DIFF_OPTS':: + Only valid setting is "--unified=??" or "-u??" to set the + number of context lines shown when a unified diff is created. + This takes precedence over any "-U" or "--unified" option + value passed on the git diff command line. + 'GIT_EXTERNAL_DIFF':: - see the "generating patches" section in : - gitlink:git-diff-index[1]; - gitlink:git-diff-files[1]; - gitlink:git-diff-tree[1] + When the environment variable 'GIT_EXTERNAL_DIFF' is set, the + program named by it is called, instead of the diff invocation + described above. For a path that is added, removed, or modified, + 'GIT_EXTERNAL_DIFF' is called with 7 parameters: + + path old-file old-hex old-mode new-file new-hex new-mode ++ +where: + + -file:: are files GIT_EXTERNAL_DIFF can use to read the + contents of , + -hex:: are the 40-hexdigit SHA1 hashes, + -mode:: are the octal representation of the file modes. + ++ +The file parameters can point at the user's working file +(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` +when a new file is added), or a temporary file (e.g. `old-file` in the +index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the +temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. ++ +For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 +parameter, . other ~~~~~ -- cgit v1.3-5-g9baa From 4511c899e64cbda934ba864c359a2a7a04909264 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 28 Nov 2006 18:51:41 -0800 Subject: git-svn: documentation updates Eliminate 'commit' from some places and plug 'dcommit' more. Also update the section --id (GIT_SVN_ID) usage since we have multi-init/multi-fetch now. Signed-off-by: Eric Wong Signed-off-by: Junio C Hamano --- Documentation/git-svn.txt | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index a764d1f8ee..a45067e164 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -49,7 +49,7 @@ latest revision. Note: You should never attempt to modify the remotes/git-svn branch outside of git-svn. Instead, create a branch from -remotes/git-svn and work on that branch. Use the 'commit' +remotes/git-svn and work on that branch. Use the 'dcommit' command (see below) to write git commits back to remotes/git-svn. @@ -274,7 +274,7 @@ ADVANCED OPTIONS -b:: --branch :: -Used with 'fetch' or 'commit'. +Used with 'fetch', 'dcommit' or 'commit'. This can be used to join arbitrary git branches to remotes/git-svn on new commits where the tree object is equivalent. @@ -368,7 +368,7 @@ SVN was very wrong. Basic Examples ~~~~~~~~~~~~~~ -Tracking and contributing to an Subversion managed-project: +Tracking and contributing to a Subversion-managed project: ------------------------------------------------------------------------ # Initialize a repo (like git init-db): @@ -377,10 +377,9 @@ Tracking and contributing to an Subversion managed-project: git-svn fetch # Create your own branch to hack on: git checkout -b my-branch remotes/git-svn -# Commit only the git commits you want to SVN: - git-svn commit [ ...] -# Commit all the git commits from my-branch that don't exist in SVN: - git-svn commit remotes/git-svn..my-branch +# Do some work, and then commit your new changes to SVN, as well as +# automatically updating your working HEAD: + git-svn dcommit # Something is committed to SVN, rebase the latest into your branch: git-svn fetch && git rebase remotes/git-svn # Append svn:ignore settings to the default git exclude file: @@ -404,26 +403,24 @@ which can lead to merge commits reversing previous commits in SVN. DESIGN PHILOSOPHY ----------------- Merge tracking in Subversion is lacking and doing branched development -with Subversion is cumbersome as a result. git-svn completely forgoes -any automated merge/branch tracking on the Subversion side and leaves it -entirely up to the user on the git side. It's simply not worth it to do -a useful translation when the original signal is weak. +with Subversion is cumbersome as a result. git-svn does not do +automated merge/branch tracking by default and leaves it entirely up to +the user on the git side. [[tracking-multiple-repos]] TRACKING MULTIPLE REPOSITORIES OR BRANCHES ------------------------------------------ -This is for advanced users, most users should ignore this section. - Because git-svn does not care about relationships between different branches or directories in a Subversion repository, git-svn has a simple hack to allow it to track an arbitrary number of related _or_ unrelated -SVN repositories via one git repository. Simply set the GIT_SVN_ID -environment variable to a name other other than "git-svn" (the default) -and git-svn will ignore the contents of the $GIT_DIR/svn/git-svn directory -and instead do all of its work in $GIT_DIR/svn/$GIT_SVN_ID for that -invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of -remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified -by the user outside of git-svn commands. +SVN repositories via one git repository. Simply use the --id/-i flag or +set the GIT_SVN_ID environment variable to a name other other than +"git-svn" (the default) and git-svn will ignore the contents of the +$GIT_DIR/svn/git-svn directory and instead do all of its work in +$GIT_DIR/svn/$GIT_SVN_ID for that invocation. The interface branch will +be remotes/$GIT_SVN_ID, instead of remotes/git-svn. Any +remotes/$GIT_SVN_ID branch should never be modified by the user outside +of git-svn commands. [[fetch-args]] ADDITIONAL FETCH ARGUMENTS @@ -486,7 +483,8 @@ If you are not using the SVN::* Perl libraries and somebody commits a conflicting changeset to SVN at a bad moment (right before you commit) causing a conflict and your commit to fail, your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The easiest thing to do is -probably just to rm -rf $GIT_DIR/git-svn/tree and run 'rebuild'. +probably just to rm -rf $GIT_DIR/git-svn/tree and run 'rebuild'. You +can avoid this problem entirely by using 'dcommit'. We ignore all SVN properties except svn:executable. Too difficult to map them since we rely heavily on git write-tree being _exactly_ the -- cgit v1.3-5-g9baa From 665892307013bccacb35dd619ae6951c7b209379 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 29 Nov 2006 00:17:01 -0800 Subject: tutorial: talk about user.name early and don't start with commit -a Introducing yourself to git early would be a good idea; otherwise the user may not find the mistake until much later when "git log" is learned. Teaching "commit -a" without saying that it is a shortcut for listing the paths to commit leaves the user puzzled. Teach the form with explicit paths first. Signed-off-by: Junio C Hamano --- Documentation/tutorial.txt | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 1e4ddfbd11..6555e58882 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -11,6 +11,18 @@ diff" with: $ man git-diff ------------------------------------------------ +It is a good idea to introduce yourself to git before doing any +operation. The easiest way to do so is: + +------------------------------------------------ +$ cat >~/.gitconfig <<\EOF +[user] + name = Your Name Comes Here + email = you@yourdomain.example.com +EOF +------------------------------------------------ + + Importing a new project ----------------------- @@ -31,7 +43,8 @@ defaulting to local storage area You've now initialized the working directory--you may notice a new directory created, named ".git". Tell git that you want it to track -every file under the current directory with +every file under the current directory with (notice the dot '.' +that means the current directory): ------------------------------------------------ $ git add . @@ -40,7 +53,7 @@ $ git add . Finally, ------------------------------------------------ -$ git commit -a +$ git commit ------------------------------------------------ will prompt you for a commit message, then record the current state @@ -55,11 +68,17 @@ $ git diff to review your changes. When you're done, ------------------------------------------------ -$ git commit -a +$ git commit file1 file2... ------------------------------------------------ will again prompt your for a message describing the change, and then -record the new versions of the modified files. +record the new versions of the files you listed. It is cumbersome +to list all files and you can say `-a` (which stands for 'all') +instead. + +------------------------------------------------ +$ git commit -a +------------------------------------------------ A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) @@ -75,7 +94,7 @@ $ git add path/to/new/file ------------------------------------------------ then commit as usual. No special command is required when removing a -file; just remove it, then commit. +file; just remove it, then tell `commit` about the file as usual. At any point you can view the history of your changes using -- cgit v1.3-5-g9baa From eb07fd59acae0f043b9fac2a8a1cb427036c6f71 Mon Sep 17 00:00:00 2001 From: Andy Parkins Date: Wed, 29 Nov 2006 08:25:40 +0000 Subject: Document git-repo-config --bool/--int options. Signed-off-by: Andy Parkins Signed-off-by: Junio C Hamano --- Documentation/git-repo-config.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index 8199615dde..5bede9ac22 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -77,6 +77,12 @@ OPTIONS -l, --list:: List all variables set in config file. +--bool:: + git-repo-config will ensure that the output is "true" or "false" + +--int:: + git-repo-config will ensure that the output is a simple decimal number + ENVIRONMENT ----------- -- cgit v1.3-5-g9baa From 4c81c213a479e4aae0653a56ad6e8db5c31f019c Mon Sep 17 00:00:00 2001 From: Andreas Ericsson Date: Thu, 30 Nov 2006 12:43:13 +0100 Subject: git-diff: Introduce --index and deprecate --cached. 'git diff --cached' still works, but its use is discouraged in the documentation. 'git diff --index' does the same thing and is consistent with how 'git apply --index' works. Signed-off-by: Andreas Ericsson Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 6 ++++-- builtin-diff.c | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 228c4d95bd..3144864d85 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -22,8 +22,10 @@ the number of trees given to the command. * When one is given, the working tree and the named tree are compared, using `git-diff-index`. The option - `--cached` can be given to compare the index file and + `--index` can be given to compare the index file and the named tree. + `--cached` is a deprecated alias for `--index`. It's use is + discouraged. * When two s are given, these two trees are compared using `git-diff-tree`. @@ -47,7 +49,7 @@ Various ways to check your working tree:: + ------------ $ git diff <1> -$ git diff --cached <2> +$ git diff --index <2> $ git diff HEAD <3> ------------ + diff --git a/builtin-diff.c b/builtin-diff.c index a6590205e8..1c535b1dd6 100644 --- a/builtin-diff.c +++ b/builtin-diff.c @@ -137,7 +137,7 @@ static int builtin_diff_index(struct rev_info *revs, int cached = 0; while (1 < argc) { const char *arg = argv[1]; - if (!strcmp(arg, "--cached")) + if (!strcmp(arg, "--index") || !strcmp(arg, "--cached")) cached = 1; else usage(builtin_diff_usage); -- cgit v1.3-5-g9baa From 22b1c7ee01ef5bc7f81e620bb88a6fad79c1c605 Mon Sep 17 00:00:00 2001 From: Andy Parkins Date: Thu, 30 Nov 2006 10:50:28 +0000 Subject: De-emphasise the symbolic link documentation. The fact that git has previously used symbolic links for representing symbolic refs doesn't seem relevant to the current function of git-symbolic-ref. This patch makes less of a big deal about the symbolic link history and instead focuses on what git does now. Signed-off-by: Andy Parkins Signed-off-by: Junio C Hamano --- Documentation/git-symbolic-ref.txt | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 68ac6a65df..4bc35a1d4b 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -19,29 +19,22 @@ argument to see on which branch your working tree is on. Give two arguments, create or update a symbolic ref to point at the given branch . -Traditionally, `.git/HEAD` is a symlink pointing at -`refs/heads/master`. When we want to switch to another branch, -we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want +A symbolic ref is a regular file that stores a string that +begins with `ref: refs/`. For example, your `.git/HEAD` is +a regular file whose contents is `ref: refs/heads/master`. + +NOTES +----- +In the past, `.git/HEAD` was a symbolic link pointing at +`refs/heads/master`. When we wanted to switch to another branch, +we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we wanted to find out which branch we are on, we did `readlink .git/HEAD`. This was fine, and internally that is what still happens by default, but on platforms that do not have working symlinks, or that do not have the `readlink(1)` command, this was a bit cumbersome. On some platforms, `ln -sf` does not even work as -advertised (horrors). - -A symbolic ref can be a regular file that stores a string that -begins with `ref: refs/`. For example, your `.git/HEAD` *can* -be a regular file whose contents is `ref: refs/heads/master`. -This can be used on a filesystem that does not support symbolic -links. Instead of doing `readlink .git/HEAD`, `git-symbolic-ref -HEAD` can be used to find out which branch we are on. To point -the HEAD to `newbranch`, instead of `ln -sf refs/heads/newbranch -.git/HEAD`, `git-symbolic-ref HEAD refs/heads/newbranch` can be -used. - -Currently, .git/HEAD uses a regular file symbolic ref on Cygwin, -and everywhere else it is implemented as a symlink. This can be -changed at compilation time. +advertised (horrors). Therefore symbolic links are now deprecated +and symbolic refs are used by default. Author ------ -- cgit v1.3-5-g9baa From b360cca0b100e14abffa4cae78521b493c783738 Mon Sep 17 00:00:00 2001 From: Jakub Narebski Date: Mon, 4 Dec 2006 14:29:09 +0100 Subject: git-clone: Rename --use-immingled-remote option to --no-separate-remote With making --use-separate-remote default when creating non-bare clone, there was need for the flag which would turn off this behavior. It was called --use-immingled-remote. Immingle means to blend, to combine into one, to intermingle, but it is a bit obscure word. I think it would be better to use simply --no-separate-remote as the opposite to --use-separate-remote option to git clone. Signed-off-by: Jakub Narebski Signed-off-by: Junio C Hamano --- Documentation/git-clone.txt | 4 ++-- git-clone.sh | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 4cb42237b5..d5efa00dea 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git-clone' [--template=] [-l [-s]] [-q] [-n] [--bare] [-o ] [-u ] [--reference ] - [--use-separate-remote | --use-immingled-remote] + [--use-separate-remote | --no-separate-remote] [] DESCRIPTION @@ -105,7 +105,7 @@ OPTIONS of `$GIT_DIR/refs/heads/`. Only the local master branch is saved in the latter. This is the default. ---use-immingled-remote:: +--no-separate-remote:: Save remotes heads in the same namespace as the local heads, `$GIT_DIR/refs/heads/'. In regular repositories, this is a legacy setup git-clone created by default in diff --git a/git-clone.sh b/git-clone.sh index d4ee93f75b..89640396e9 100755 --- a/git-clone.sh +++ b/git-clone.sh @@ -14,7 +14,7 @@ die() { } usage() { - die "Usage: $0 [--template=] [--use-immingled-remote] [--reference ] [--bare] [-l [-s]] [-q] [-u ] [--origin ] [-n] []" + die "Usage: $0 [--template=] [--no-separate-remote] [--reference ] [--bare] [-l [-s]] [-q] [-u ] [--origin ] [-n] []" } get_repo_base() { @@ -140,7 +140,7 @@ while *,--use-separate-remote) # default use_separate_remote=t ;; - *,--use-immingled-remote) + *,--no-separate-remote) use_separate_remote= ;; 1,--reference) usage ;; *,--reference) @@ -176,7 +176,7 @@ repo="$1" test -n "$repo" || die 'you must specify a repository to clone.' -# --bare implies --no-checkout and --use-immingled-remote +# --bare implies --no-checkout and --no-separate-remote if test yes = "$bare" then if test yes = "$origin_override" -- cgit v1.3-5-g9baa From 8ebe185bbf3f1f4f59bcc61e3d1849a76f6af983 Mon Sep 17 00:00:00 2001 From: Jakub Narebski Date: Sun, 3 Dec 2006 17:24:41 +0100 Subject: Document git-diff whitespace flags -b and -w Document git diff options -b / --ignore-space-change and -w / --ignore-all-space, introduced by Johannes Schindelin in commit 0d21efa5, "Teach diff about -b and -w flags". The description of options is taken from GNU diff man page and GNU Diffutils info documentation. Signed-off-by: Jakub Narebski Signed-off-by: Junio C Hamano --- Documentation/diff-options.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'Documentation') diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index e112172ca5..9cdd171af7 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -129,5 +129,21 @@ -a:: Shorthand for "--text". +--ignore-space-change:: + Ignore changes in amount of white space. This ignores white + space at line end, and consider all other sequences of one or + more white space characters to be equivalent. + +-b:: + Shorthand for "--ignore-space-change". + +--ignore-all-space:: + Ignore white space when comparing lines. This ignores + difference even if one line has white space where the other + line has none. + +-w:: + Shorthand for "--ignore-all-space". + For more detailed explanation on these common options, see also link:diffcore.html[diffcore documentation]. -- cgit v1.3-5-g9baa From 366bfcb68f4d98a43faaf17893a1aa0a7a9e2c58 Mon Sep 17 00:00:00 2001 From: Nicolas Pitre Date: Mon, 4 Dec 2006 11:13:39 -0500 Subject: make 'git add' a first class user friendly interface to the index This brings the power of the index up front using a proper mental model without talking about the index at all. See for example how all the technical discussion has been evacuated from the git-add man page. Any content to be committed must be added together. Whether that content comes from new files or modified files doesn't matter. You just need to "add" it, either with git-add, or by providing git-commit with -a (for already known files only of course). No need for a separate command to distinguish new vs modified files please. That would only screw the mental model everybody should have when using GIT. Signed-off-by: Nicolas Pitre Signed-off-by: Junio C Hamano --- Documentation/git-add.txt | 53 ++++++++++++++++++++++++---------------------- Documentation/tutorial.txt | 46 ++++++++++++++++++++++++++++++++++------ builtin-add.c | 6 +++--- wt-status.c | 2 +- 4 files changed, 72 insertions(+), 35 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 6342ea33e4..d86c0e7f19 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -3,7 +3,7 @@ git-add(1) NAME ---- -git-add - Add files to the index file +git-add - Add file contents to the changeset to be committed next SYNOPSIS -------- @@ -11,16 +11,31 @@ SYNOPSIS DESCRIPTION ----------- -A simple wrapper for git-update-index to add files to the index, -for people used to do "cvs add". +All the changed file contents to be committed together in a single set +of changes must be "added" with the 'add' command before using the +'commit' command. This is not only for adding new files. Even modified +files must be added to the set of changes about to be committed. -It only adds non-ignored files, to add ignored files use +This command can be performed multiple times before a commit. The added +content corresponds to the state of specified file(s) at the time the +'add' command is used. This means the 'commit' command will not consider +subsequent changes to already added content if it is not added again before +the commit. + +The 'git status' command can be used to obtain a summary of what is included +for the next commit. + +This command only adds non-ignored files, to add ignored files use "git update-index --add". +Please see gitlink:git-commit[1] for alternative ways to add content to a +commit. + + OPTIONS ------- ...:: - Files to add to the index (see gitlink:git-ls-files[1]). + Files to add content from. -n:: Don't actually add the file(s), just show if they exist. @@ -34,27 +49,12 @@ OPTIONS for command-line options). -DISCUSSION ----------- - -The list of given to the command is fed to `git-ls-files` -command to list files that are not registered in the index and -are not ignored/excluded by `$GIT_DIR/info/exclude` file or -`.gitignore` file in each directory. This means two things: - -. You can put the name of a directory on the command line, and - the command will add all files in it and its subdirectories; - -. Giving the name of a file that is already in index does not - run `git-update-index` on that path. - - EXAMPLES -------- git-add Documentation/\\*.txt:: - Adds all `\*.txt` files that are not in the index under - `Documentation` directory and its subdirectories. + Adds content from all `\*.txt` files under `Documentation` + directory and its subdirectories. + Note that the asterisk `\*` is quoted from the shell in this example; this lets the command to include the files from @@ -62,15 +62,18 @@ subdirectories of `Documentation/` directory. git-add git-*.sh:: - Adds all git-*.sh scripts that are not in the index. + Considers adding content from all git-*.sh scripts. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not - add `subdir/git-foo.sh` to the index. + consider `subdir/git-foo.sh`. See Also -------- +gitlink:git-status[1] gitlink:git-rm[1] -gitlink:git-ls-files[1] +gitlink:git-mv[1] +gitlink:git-commit[1] +gitlink:git-update-index[1] Author ------ diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index fe4491de41..02dede320c 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -87,14 +87,48 @@ thorough description. Tools that turn commits into email, for example, use the first line on the Subject line and the rest of the commit in the body. -To add a new file, first create the file, then ------------------------------------------------- -$ git add path/to/new/file ------------------------------------------------- +Git tracks content not files +---------------------------- + +With git you have to explicitly "add" all the changed _content_ you +want to commit together. This can be done in a few different ways: + +1) By using 'git add ...' + + This can be performed multiple times before a commit. Note that this + is not only for adding new files. Even modified files must be + added to the set of changes about to be committed. The "git status" + command gives you a summary of what is included so far for the + next commit. When done you should use the 'git commit' command to + make it real. + + Note: don't forget to 'add' a file again if you modified it after the + first 'add' and before 'commit'. Otherwise only the previous added + state of that file will be committed. This is because git tracks + content, so what you're really 'add'ing to the commit is the *content* + of the file in the state it is in when you 'add' it. + +2) By using 'git commit -a' directly + + This is a quick way to automatically 'add' the content from all files + that were modified since the previous commit, and perform the actual + commit without having to separately 'add' them beforehand. This will + not add content from new files i.e. files that were never added before. + Those files still have to be added explicitly before performing a + commit. + +But here's a twist. If you do 'git commit ...' then only +the changes belonging to those explicitly specified files will be +committed, entirely bypassing the current "added" changes. Those "added" +changes will still remain available for a subsequent commit though. + +However, for normal usage you only have to remember 'git add' + 'git commit' +and/or 'git commit -a'. + -then commit as usual. No special command is required when removing a -file; just remove it, then tell `commit` about the file as usual. +Viewing the changelog +--------------------- At any point you can view the history of your changes using diff --git a/builtin-add.c b/builtin-add.c index febb75ed99..b3f920676a 100644 --- a/builtin-add.c +++ b/builtin-add.c @@ -94,9 +94,6 @@ int cmd_add(int argc, const char **argv, const char *prefix) newfd = hold_lock_file_for_update(&lock_file, get_index_file(), 1); - if (read_cache() < 0) - die("index file corrupt"); - for (i = 1; i < argc; i++) { const char *arg = argv[i]; @@ -131,6 +128,9 @@ int cmd_add(int argc, const char **argv, const char *prefix) return 0; } + if (read_cache() < 0) + die("index file corrupt"); + for (i = 0; i < dir.nr; i++) add_file_to_index(dir.entries[i]->name, verbose); diff --git a/wt-status.c b/wt-status.c index de1be5bc66..4b8b5705b4 100644 --- a/wt-status.c +++ b/wt-status.c @@ -163,7 +163,7 @@ static void wt_status_print_changed_cb(struct diff_queue_struct *q, int i; if (q->nr) wt_status_print_header("Changed but not updated", - "use git-update-index to mark for commit"); + "use git-add on files to include for commit"); for (i = 0; i < q->nr; i++) wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]); if (q->nr) -- cgit v1.3-5-g9baa From 22f741dab7cc93f00f7cf96cd65d7481677cd855 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 5 Dec 2006 23:44:23 -0800 Subject: read-tree: document --exclude-per-directory This documents the new option to read-tree that is used for the improved "branch switching" code. Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 16 +++++++++++++++- builtin-read-tree.c | 2 +- 2 files changed, 16 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 11bd9c0adc..0ff2890c7f 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' ( | [[-m [--aggressive] | --reset | --prefix=] [-u | -i]] [ []]) +'git-read-tree' ( | [[-m [--aggressive] | --reset | --prefix=] [-u | -i]] [--exclude-per-directory=] [ []]) DESCRIPTION @@ -71,6 +71,20 @@ OPTIONS directory. Note that the `/` value must end with a slash. +--exclude-per-directory=:: + When running the command with `-u` and `-m` options, the + merge result may need to overwrite paths that are not + tracked in the current branch. The command usually + refuses to proceed with the merge to avoid losing such a + path. However this safety valve sometimes gets in the + way. For example, it often happens that the other + branch added a file that used to be a generated file in + your branch, and the safety valve triggers when you try + to switch to that branch after you ran `make` but before + running `make clean` to remove the generated file. This + option tells the command to read per-directory exclude + file (usually '.gitignore') and allows such an untracked + but explicitly ignored file to be overwritten. :: The id of the tree object(s) to be read/merged. diff --git a/builtin-read-tree.c b/builtin-read-tree.c index 3f6cae36ce..8ba436dbac 100644 --- a/builtin-read-tree.c +++ b/builtin-read-tree.c @@ -85,7 +85,7 @@ static void prime_cache_tree(void) } -static const char read_tree_usage[] = "git-read-tree ( | [[-m [--aggressive] | --reset | --prefix=] [-u | -i]] [ []])"; +static const char read_tree_usage[] = "git-read-tree ( | [[-m [--aggressive] | --reset | --prefix=] [-u | -i]] [--exclude-per-directory=] [ []])"; static struct lock_file lock_file; -- cgit v1.3-5-g9baa From c976d415e5352886f0650f8e2edba81866c38587 Mon Sep 17 00:00:00 2001 From: Lars Hjemli Date: Tue, 28 Nov 2006 15:47:40 +0100 Subject: git-branch: add options and tests for branch renaming Extend git-branch with the following options: git-branch -m|-M [] newbranch The -M variation is required to force renaming over an exsisting branchname. This also indroduces $GIT_DIR/RENAME_REF which is a "metabranch" used when renaming branches. It will always hold the original sha1 for the latest renamed branch. Additionally, if $GIT_DIR/logs/RENAME_REF exists, all branch rename events are logged there. Finally, some testcases are added to verify the new options. Signed-off-by: Lars Hjemli Signed-off-by: Junio C Hamano --- Documentation/git-branch.txt | 23 +++++- builtin-branch.c | 47 +++++++++++- refs.c | 169 +++++++++++++++++++++++++++++++++++++------ refs.h | 3 + t/t3200-branch.sh | 34 +++++++++ 5 files changed, 250 insertions(+), 26 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 4f5b5d5028..71417feba8 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,8 +8,9 @@ git-branch - List, create, or delete branches. SYNOPSIS -------- [verse] -'git-branch' [-r] [-a] [-v] [--abbrev=] +'git-branch' [-r | -a] [-v [--abbrev=]] 'git-branch' [-l] [-f] [] +'git-branch' (-m | -M) [] 'git-branch' (-d | -D) ... DESCRIPTION @@ -24,6 +25,12 @@ It will start out with a head equal to the one given as . If no is given, the branch will be created with a head equal to that of the currently checked out branch. +With a '-m' or '-M' option, will be renamed to . +If had a corresponding reflog, it is renamed to match +, and a reflog entry is created to remember the branch +renaming. If exists, -M must be used to force the rename +to happen. + With a `-d` or `-D` option, `` will be deleted. You may specify more than one branch for deletion. If the branch currently has a ref log then the ref log will also be deleted. @@ -46,6 +53,12 @@ OPTIONS Force the creation of a new branch even if it means deleting a branch that already exists with the same name. +-m:: + Move/rename a branch and the corresponding reflog. + +-M:: + Move/rename a branch even if the new branchname already exists. + -r:: List the remote-tracking branches. @@ -53,7 +66,7 @@ OPTIONS List both remote-tracking branches and local branches. -v:: - Show sha1 and subject message for each head. + Show sha1 and commit subjectline for each head. --abbrev=:: Alter minimum display length for sha1 in output listing, @@ -70,6 +83,12 @@ OPTIONS be given as a branch name, a commit-id, or a tag. If this option is omitted, the current branch is assumed. +:: + The name of an existing branch to rename. + +:: + The new name for an existing branch. The same restrictions as for + applies. Examples diff --git a/builtin-branch.c b/builtin-branch.c index 3d5cb0e4b2..153682601e 100644 --- a/builtin-branch.c +++ b/builtin-branch.c @@ -11,7 +11,7 @@ #include "builtin.h" static const char builtin_branch_usage[] = -"git-branch (-d | -D) | [-l] [-f] [] | [-r | -a] [-v] [--abbrev=] "; + "git-branch (-d | -D) | [-l] [-f] [] | (-m | -M) [] | [-r | -a] [-v [--abbrev=]]"; static const char *head; @@ -245,9 +245,37 @@ static void create_branch(const char *name, const char *start, die("Failed to write ref: %s.", strerror(errno)); } +static void rename_branch(const char *oldname, const char *newname, int force) +{ + char oldref[PATH_MAX], newref[PATH_MAX]; + unsigned char sha1[20]; + + if (snprintf(oldref, sizeof(oldref), "refs/heads/%s", oldname) > sizeof(oldref)) + die("Old branchname too long"); + + if (check_ref_format(oldref)) + die("Invalid branch name: %s", oldref); + + if (snprintf(newref, sizeof(newref), "refs/heads/%s", newname) > sizeof(newref)) + die("New branchname too long"); + + if (check_ref_format(newref)) + die("Invalid branch name: %s", newref); + + if (resolve_ref(newref, sha1, 1, NULL) && !force) + die("A branch named '%s' already exists.", newname); + + if (rename_ref(oldref, newref)) + die("Branch rename failed"); + + if (!strcmp(oldname, head) && create_symref("HEAD", newref)) + die("Branch renamed to %s, but HEAD is not updated!", newname); +} + int cmd_branch(int argc, const char **argv, const char *prefix) { int delete = 0, force_delete = 0, force_create = 0; + int rename = 0, force_rename = 0; int verbose = 0, abbrev = DEFAULT_ABBREV; int reflog = 0; int kinds = REF_LOCAL_BRANCH; @@ -277,6 +305,15 @@ int cmd_branch(int argc, const char **argv, const char *prefix) force_create = 1; continue; } + if (!strcmp(arg, "-m")) { + rename = 1; + continue; + } + if (!strcmp(arg, "-M")) { + rename = 1; + force_rename = 1; + continue; + } if (!strcmp(arg, "-r")) { kinds = REF_REMOTE_BRANCH; continue; @@ -300,6 +337,10 @@ int cmd_branch(int argc, const char **argv, const char *prefix) usage(builtin_branch_usage); } + if ((delete && rename) || (delete && force_create) || + (rename && force_create)) + usage(builtin_branch_usage); + head = xstrdup(resolve_ref("HEAD", head_sha1, 0, NULL)); if (!head) die("Failed to resolve HEAD as a valid ref."); @@ -311,6 +352,10 @@ int cmd_branch(int argc, const char **argv, const char *prefix) delete_branches(argc - i, argv + i, force_delete); else if (i == argc) print_ref_list(kinds, verbose, abbrev); + else if (rename && (i == argc - 1)) + rename_branch(head, argv[i], force_rename); + else if (rename && (i == argc - 2)) + rename_branch(argv[i], argv[i + 1], force_rename); else if (i == argc - 1) create_branch(argv[i], head, force_create, reflog); else if (i == argc - 2) diff --git a/refs.c b/refs.c index 96ea8b6907..cdedb45f00 100644 --- a/refs.c +++ b/refs.c @@ -610,6 +610,29 @@ static int remove_empty_directories(char *file) return remove_empty_dir_recursive(path, len); } +static int is_refname_available(const char *ref, const char *oldref, + struct ref_list *list, int quiet) +{ + int namlen = strlen(ref); /* e.g. 'foo/bar' */ + while (list) { + /* list->name could be 'foo' or 'foo/bar/baz' */ + if (!oldref || strcmp(oldref, list->name)) { + int len = strlen(list->name); + int cmplen = (namlen < len) ? namlen : len; + const char *lead = (namlen < len) ? list->name : ref; + if (!strncmp(ref, list->name, cmplen) && + lead[cmplen] == '/') { + if (!quiet) + error("'%s' exists; cannot create '%s'", + list->name, ref); + return 0; + } + } + list = list->next; + } + return 1; +} + static struct ref_lock *lock_ref_sha1_basic(const char *ref, const unsigned char *old_sha1, int *flag) { char *ref_file; @@ -643,29 +666,14 @@ static struct ref_lock *lock_ref_sha1_basic(const char *ref, const unsigned char orig_ref, strerror(errno)); goto error_return; } - if (is_null_sha1(lock->old_sha1)) { - /* The ref did not exist and we are creating it. - * Make sure there is no existing ref that is packed - * whose name begins with our refname, nor a ref whose - * name is a proper prefix of our refname. - */ - int namlen = strlen(ref); /* e.g. 'foo/bar' */ - struct ref_list *list = get_packed_refs(); - while (list) { - /* list->name could be 'foo' or 'foo/bar/baz' */ - int len = strlen(list->name); - int cmplen = (namlen < len) ? namlen : len; - const char *lead = (namlen < len) ? list->name : ref; - - if (!strncmp(ref, list->name, cmplen) && - lead[cmplen] == '/') { - error("'%s' exists; cannot create '%s'", - list->name, ref); - goto error_return; - } - list = list->next; - } - } + /* When the ref did not exist and we are creating it, + * make sure there is no existing ref that is packed + * whose name begins with our refname, nor a ref whose + * name is a proper prefix of our refname. + */ + if (is_null_sha1(lock->old_sha1) && + !is_refname_available(ref, NULL, get_packed_refs(), 0)) + goto error_return; lock->lk = xcalloc(1, sizeof(struct lock_file)); @@ -776,6 +784,121 @@ int delete_ref(const char *refname, unsigned char *sha1) return ret; } +int rename_ref(const char *oldref, const char *newref) +{ + static const char renamed_ref[] = "RENAMED-REF"; + unsigned char sha1[20], orig_sha1[20]; + int flag = 0, logmoved = 0; + struct ref_lock *lock; + char msg[PATH_MAX*2 + 100]; + struct stat loginfo; + int log = !stat(git_path("logs/%s", oldref), &loginfo); + + if (S_ISLNK(loginfo.st_mode)) + return error("reflog for %s is a symlink", oldref); + + if (!resolve_ref(oldref, orig_sha1, 1, &flag)) + return error("refname %s not found", oldref); + + if (!is_refname_available(newref, oldref, get_packed_refs(), 0)) + return 1; + + if (!is_refname_available(newref, oldref, get_loose_refs(), 0)) + return 1; + + if (snprintf(msg, sizeof(msg), "renamed %s to %s", oldref, newref) > sizeof(msg)) + return error("Refnames to long"); + + lock = lock_ref_sha1_basic(renamed_ref, NULL, NULL); + if (!lock) + return error("unable to lock %s", renamed_ref); + lock->force_write = 1; + if (write_ref_sha1(lock, orig_sha1, msg)) + return error("unable to save current sha1 in %s", renamed_ref); + + if (log && rename(git_path("logs/%s", oldref), git_path("tmp-renamed-log"))) + return error("unable to move logfile logs/%s to tmp-renamed-log: %s", + oldref, strerror(errno)); + + if (delete_ref(oldref, orig_sha1)) { + error("unable to delete old %s", oldref); + goto rollback; + } + + if (resolve_ref(newref, sha1, 1, &flag) && delete_ref(newref, sha1)) { + if (errno==EISDIR) { + if (remove_empty_directories(git_path("%s", newref))) { + error("Directory not empty: %s", newref); + goto rollback; + } + } else { + error("unable to delete existing %s", newref); + goto rollback; + } + } + + if (log && safe_create_leading_directories(git_path("logs/%s", newref))) { + error("unable to create directory for %s", newref); + goto rollback; + } + + retry: + if (log && rename(git_path("tmp-renamed-log"), git_path("logs/%s", newref))) { + if (errno==EISDIR) { + if (remove_empty_directories(git_path("logs/%s", newref))) { + error("Directory not empty: logs/%s", newref); + goto rollback; + } + goto retry; + } else { + error("unable to move logfile tmp-renamed-log to logs/%s: %s", + newref, strerror(errno)); + goto rollback; + } + } + logmoved = log; + + lock = lock_ref_sha1_basic(newref, NULL, NULL); + if (!lock) { + error("unable to lock %s for update", newref); + goto rollback; + } + + lock->force_write = 1; + hashcpy(lock->old_sha1, orig_sha1); + if (write_ref_sha1(lock, orig_sha1, msg)) { + error("unable to write current sha1 into %s", newref); + goto rollback; + } + + return 0; + + rollback: + lock = lock_ref_sha1_basic(oldref, NULL, NULL); + if (!lock) { + error("unable to lock %s for rollback", oldref); + goto rollbacklog; + } + + lock->force_write = 1; + flag = log_all_ref_updates; + log_all_ref_updates = 0; + if (write_ref_sha1(lock, orig_sha1, NULL)) + error("unable to write current sha1 into %s", oldref); + log_all_ref_updates = flag; + + rollbacklog: + if (logmoved && rename(git_path("logs/%s", newref), git_path("logs/%s", oldref))) + error("unable to restore logfile %s from %s: %s", + oldref, newref, strerror(errno)); + if (!logmoved && log && + rename(git_path("tmp-renamed-log"), git_path("logs/%s", oldref))) + error("unable to restore logfile %s from tmp-renamed-log: %s", + oldref, strerror(errno)); + + return 1; +} + void unlock_ref(struct ref_lock *lock) { if (lock->lock_fd >= 0) { diff --git a/refs.h b/refs.h index cd1e1d620e..ce73d5c7ae 100644 --- a/refs.h +++ b/refs.h @@ -47,4 +47,7 @@ extern int read_ref_at(const char *ref, unsigned long at_time, int cnt, unsigned /** Returns 0 if target has the right format for a ref. **/ extern int check_ref_format(const char *target); +/** rename ref, return 0 on success **/ +extern int rename_ref(const char *oldref, const char *newref); + #endif /* REFS_H */ diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh index acb54b6a07..afaa8536a9 100755 --- a/t/t3200-branch.sh +++ b/t/t3200-branch.sh @@ -70,4 +70,38 @@ test_expect_success \ git-branch -d l/m && git-branch l' +test_expect_success \ + 'git branch -m m m/m should work' \ + 'git-branch -l m && + git-branch -m m m/m && + test -f .git/logs/refs/heads/m/m' + +test_expect_success \ + 'git branch -m n/n n should work' \ + 'git-branch -l n/n && + git-branch -m n/n n + test -f .git/logs/refs/heads/n' + +test_expect_failure \ + 'git branch -m o/o o should fail when o/p exists' \ + 'git-branch o/o && + git-branch o/p && + git-branch -m o/o o' + +test_expect_failure \ + 'git branch -m q r/q should fail when r exists' \ + 'git-branch q && + git-branch r && + git-branch -m q r/q' + +test_expect_success \ + 'git branch -m s/s s should work when s/t is deleted' \ + 'git-branch -l s/s && + test -f .git/logs/refs/heads/s/s && + git-branch -l s/t && + test -f .git/logs/refs/heads/s/t && + git-branch -d s/t && + git-branch -m s/s s && + test -f .git/logs/refs/heads/s' + test_done -- cgit v1.3-5-g9baa From 3a9f1a55eec9cc508abccda6a3fee795b812d66d Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Wed, 6 Dec 2006 13:27:40 +0100 Subject: cvs-migration document: make the need for "push" more obvious It really is an important concept to grasp for people coming from CVS. Even if it is briefly mentioned, it is not obvious enough to sink in. [jc: with wording updates from J. Bruce Fields] Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- Documentation/cvs-migration.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 6812683a16..9c2a395e5a 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -24,6 +24,11 @@ First, note some ways that git differs from CVS: single shared repository which people can synchronize with; see below for details. + * Since every working tree contains a repository, a commit in your + private repository will not publish your changes; it will only create + a revision. You have to "push" your changes to a public repository to + make them visible to others. + Importing a CVS archive ----------------------- -- cgit v1.3-5-g9baa From 4003a58e415e5f51a3becac0079505b72299a7bc Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Wed, 6 Dec 2006 12:19:50 -0500 Subject: cvs-migration: improved section titles, better push/commit explanation Rename the section titles to make the "how-to" content of the section obvious. Also clarify that changes have to be commited before they can be pushed. Signed-off-by: Junio C Hamano --- Documentation/cvs-migration.txt | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 9c2a395e5a..a436180dd4 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -81,8 +81,8 @@ variants of this model. With a small group, developers may just pull changes from each other's repositories without the need for a central maintainer. -Emulating the CVS Development Model ------------------------------------ +Creating a Shared Repository +---------------------------- Start with an ordinary git working directory containing the project, and remove the checked-out files, keeping just the bare .git directory: @@ -110,7 +110,10 @@ $ GIT_DIR=repo.git git repo-config core.sharedrepository true Make sure committers have a umask of at most 027, so that the directories they create are writable and searchable by other group members. -Suppose this repository is now set up in /pub/repo.git on the host +Performing Development on a Shared Repository +--------------------------------------------- + +Suppose a repository is now set up in /pub/repo.git on the host foo.com. Then as an individual committer you can clone the shared repository: @@ -139,15 +142,17 @@ Pull: master:origin ------------ ================================ -You can update the shared repository with your changes using: +You can update the shared repository with your changes by first commiting +your changes, and then using: ------------------------------------------------ $ git push origin master ------------------------------------------------ -If someone else has updated the repository more recently, `git push`, like -`cvs commit`, will complain, in which case you must pull any changes -before attempting the push again. +to "push" those commits to the shared repository. If someone else has +updated the repository more recently, `git push`, like `cvs commit`, will +complain, in which case you must pull any changes before attempting the +push again. In the `git push` command above we specify the name of the remote branch to update (`master`). If we leave that out, `git push` tries to update -- cgit v1.3-5-g9baa From cd976f5c52694acb4b23c3f2425ed4f0a47ec799 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Wed, 6 Dec 2006 23:18:05 -0500 Subject: Documentation: reorganize cvs-migration.txt Modify cvs-migration.txt so it explains first how to develop against a shared repository, then how to set up a shared repository, then how to import a repository from cvs. Though this seems chronologically backwards, it's still readable in this order, and it puts the more commonly needed material closer to the front. Remove the annotate/pickaxe section; perhaps it can find a place elsewhere in the future. Remove most of the "why git is better than cvs" stuff from the introduction. Add some minor clarifications, including two that have come up several times on the mailing list: 1. Recommend committing any changes before running pull. 2. Note that changes must be commited before they can be pushed. Update the clone discussion to reflect the new --use-separate-remotes default, and add a brief mention of git-cvsserver. Signed-off-by: J. Bruce Fields Signed-off-by: Junio C Hamano --- Documentation/cvs-migration.txt | 349 ++++++++++++---------------------------- 1 file changed, 104 insertions(+), 245 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index a436180dd4..47846bdab2 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -1,121 +1,21 @@ git for CVS users ================= -So you're a CVS user. That's OK, it's a treatable condition. The job of -this document is to put you on the road to recovery, by helping you -convert an existing cvs repository to git, and by showing you how to use a -git repository in a cvs-like fashion. +Git differs from CVS in that every working tree contains a repository with +a full copy of the project history, and no repository is inherently more +important than any other. However, you can emulate the CVS model by +designating a single shared repository which people can synchronize with; +this document explains how to do that. Some basic familiarity with git is required. This link:tutorial.html[tutorial introduction to git] should be sufficient. -First, note some ways that git differs from CVS: +Developing against a shared repository +-------------------------------------- - * Commits are atomic and project-wide, not per-file as in CVS. - - * Offline work is supported: you can make multiple commits locally, - then submit them when you're ready. - - * Branching is fast and easy. - - * Every working tree contains a repository with a full copy of the - project history, and no repository is inherently more important than - any other. However, you can emulate the CVS model by designating a - single shared repository which people can synchronize with; see below - for details. - - * Since every working tree contains a repository, a commit in your - private repository will not publish your changes; it will only create - a revision. You have to "push" your changes to a public repository to - make them visible to others. - -Importing a CVS archive ------------------------ - -First, install version 2.1 or higher of cvsps from -link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make -sure it is in your path. The magic command line is then - -------------------------------------------- -$ git cvsimport -v -d -C -------------------------------------------- - -This puts a git archive of the named CVS module in the directory -, which will be created if necessary. The -v option makes -the conversion script very chatty. - -The import checks out from CVS every revision of every file. Reportedly -cvsimport can average some twenty revisions per second, so for a -medium-sized project this should not take more than a couple of minutes. -Larger projects or remote repositories may take longer. - -The main trunk is stored in the git branch named `origin`, and additional -CVS branches are stored in git branches with the same names. The most -recent version of the main trunk is also left checked out on the `master` -branch, so you can start adding your own changes right away. - -The import is incremental, so if you call it again next month it will -fetch any CVS updates that have been made in the meantime. For this to -work, you must not modify the imported branches; instead, create new -branches for your own changes, and merge in the imported branches as -necessary. - -Development Models ------------------- - -CVS users are accustomed to giving a group of developers commit access to -a common repository. In the next section we'll explain how to do this -with git. However, the distributed nature of git allows other development -models, and you may want to first consider whether one of them might be a -better fit for your project. - -For example, you can choose a single person to maintain the project's -primary public repository. Other developers then clone this repository -and each work in their own clone. When they have a series of changes that -they're happy with, they ask the maintainer to pull from the branch -containing the changes. The maintainer reviews their changes and pulls -them into the primary repository, which other developers pull from as -necessary to stay coordinated. The Linux kernel and other projects use -variants of this model. - -With a small group, developers may just pull changes from each other's -repositories without the need for a central maintainer. - -Creating a Shared Repository ----------------------------- - -Start with an ordinary git working directory containing the project, and -remove the checked-out files, keeping just the bare .git directory: - ------------------------------------------------- -$ mv project/.git /pub/repo.git -$ rm -r project/ ------------------------------------------------- - -Next, give every team member read/write access to this repository. One -easy way to do this is to give all the team members ssh access to the -machine where the repository is hosted. If you don't want to give them a -full shell on the machine, there is a restricted shell which only allows -users to do git pushes and pulls; see gitlink:git-shell[1]. - -Put all the committers in the same group, and make the repository -writable by that group: - ------------------------------------------------- -$ chgrp -R $group repo.git -$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s -$ GIT_DIR=repo.git git repo-config core.sharedrepository true ------------------------------------------------- - -Make sure committers have a umask of at most 027, so that the directories -they create are writable and searchable by other group members. - -Performing Development on a Shared Repository ---------------------------------------------- - -Suppose a repository is now set up in /pub/repo.git on the host +Suppose a shared repository is set up in /pub/repo.git on the host foo.com. Then as an individual committer you can clone the shared -repository: +repository over ssh with: ------------------------------------------------ $ git clone foo.com:/pub/repo.git/ my-project @@ -129,7 +29,8 @@ $ git pull origin ------------------------------------------------ which merges in any work that others might have done since the clone -operation. +operation. If there are uncommitted changes in your working tree, commit +them first before running git pull. [NOTE] ================================ @@ -137,8 +38,8 @@ The first `git clone` places the following in the `my-project/.git/remotes/origin` file, and that's why the previous step and the next step both work. ------------ -URL: foo.com:/pub/project.git/ my-project -Pull: master:origin +URL: foo.com:/pub/project.git/ +Pull: refs/heads/master:refs/remotes/origin/master ------------ ================================ @@ -161,21 +62,76 @@ in the local repository. So the last `push` can be done with either of: ------------ $ git push origin -$ git push repo.shared.xz:/pub/scm/project.git/ +$ git push foo.com:/pub/project.git/ ------------ as long as the shared repository does not have any branches other than `master`. -[NOTE] -============ -Because of this behavior, if the shared repository and the developer's -repository both have branches named `origin`, then a push like the above -attempts to update the `origin` branch in the shared repository from the -developer's `origin` branch. The results may be unexpected, so it's -usually best to remove any branch named `origin` from the shared -repository. -============ +Setting Up a Shared Repository +------------------------------ + +We assume you have already created a git repository for your project, +possibly created from scratch or from a tarball (see the +link:tutorial.html[tutorial]), or imported from an already existing CVS +repository (see the next section). + +If your project's working directory is /home/alice/myproject, you can +create a shared repository at /pub/repo.git with: + +------------------------------------------------ +$ git clone -bare /home/alice/myproject /pub/repo.git +------------------------------------------------ + +Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do git pushes and pulls; see gitlink:git-shell[1]. + +Put all the committers in the same group, and make the repository +writable by that group: + +------------------------------------------------ +$ cd /pub +$ chgrp -R $group repo.git +$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s +$ GIT_DIR=repo.git git repo-config core.sharedrepository true +------------------------------------------------ + +Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members. + +Importing a CVS archive +----------------------- + +First, install version 2.1 or higher of cvsps from +link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make +sure it is in your path. The magic command line is then + +------------------------------------------- +$ git cvsimport -v -d -C +------------------------------------------- + +This puts a git archive of the named CVS module in the directory +, which will be created if necessary. The -v option makes +the conversion script very chatty. + +The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer. + +The main trunk is stored in the git branch named `origin`, and additional +CVS branches are stored in git branches with the same names. The most +recent version of the main trunk is also left checked out on the `master` +branch, so you can start adding your own changes right away. + +The import is incremental, so if you call it again next month it will +fetch any CVS updates that have been made in the meantime. For this to +work, you must not modify the imported branches; instead, create new +branches for your own changes, and merge in the imported branches as +necessary. Advanced Shared Repository Management ------------------------------------- @@ -188,127 +144,30 @@ You can enforce finer grained permissions using update hooks. See link:howto/update-hook-example.txt[Controlling access to branches using update hooks]. -CVS annotate ------------- +Providing CVS Access to a git Repository +---------------------------------------- + +It is also possible to provide true CVS access to a git repository, so +that developers can still use CVS; see gitlink:git-cvsserver[1] for +details. + +Alternative Development Models +------------------------------ + +CVS users are accustomed to giving a group of developers commit access to +a common repository. As we've seen, this is also possible with git. +However, the distributed nature of git allows other development models, +and you may want to first consider whether one of them might be a better +fit for your project. + +For example, you can choose a single person to maintain the project's +primary public repository. Other developers then clone this repository +and each work in their own clone. When they have a series of changes that +they're happy with, they ask the maintainer to pull from the branch +containing the changes. The maintainer reviews their changes and pulls +them into the primary repository, which other developers pull from as +necessary to stay coordinated. The Linux kernel and other projects use +variants of this model. -So, something has gone wrong, and you don't know whom to blame, and -you're an ex-CVS user and used to do "cvs annotate" to see who caused -the breakage. You're looking for the "git annotate", and it's just -claiming not to find such a script. You're annoyed. - -Yes, that's right. Core git doesn't do "annotate", although it's -technically possible, and there are at least two specialized scripts out -there that can be used to get equivalent information (see the git -mailing list archives for details). - -git has a couple of alternatives, though, that you may find sufficient -or even superior depending on your use. One is called "git-whatchanged" -(for obvious reasons) and the other one is called "pickaxe" ("a tool for -the software archaeologist"). - -The "git-whatchanged" script is a truly trivial script that can give you -a good overview of what has changed in a file or a directory (or an -arbitrary list of files or directories). The "pickaxe" support is an -additional layer that can be used to further specify exactly what you're -looking for, if you already know the specific area that changed. - -Let's step back a bit and think about the reason why you would -want to do "cvs annotate a-file.c" to begin with. - -You would use "cvs annotate" on a file when you have trouble -with a function (or even a single "if" statement in a function) -that happens to be defined in the file, which does not do what -you want it to do. And you would want to find out why it was -written that way, because you are about to modify it to suit -your needs, and at the same time you do not want to break its -current callers. For that, you are trying to find out why the -original author did things that way in the original context. - -Many times, it may be enough to see the commit log messages of -commits that touch the file in question, possibly along with the -patches themselves, like this: - - $ git-whatchanged -p a-file.c - -This will show log messages and patches for each commit that -touches a-file. - -This, however, may not be very useful when this file has many -modifications that are not related to the piece of code you are -interested in. You would see many log messages and patches that -do not have anything to do with the piece of code you are -interested in. As an example, assuming that you have this piece -of code that you are interested in in the HEAD version: - - if (frotz) { - nitfol(); - } - -you would use git-rev-list and git-diff-tree like this: - - $ git-rev-list HEAD | - git-diff-tree --stdin -v -p -S'if (frotz) { - nitfol(); - }' - -We have already talked about the "\--stdin" form of git-diff-tree -command that reads the list of commits and compares each commit -with its parents (otherwise you should go back and read the tutorial). -The git-whatchanged command internally runs -the equivalent of the above command, and can be used like this: - - $ git-whatchanged -p -S'if (frotz) { - nitfol(); - }' - -When the -S option is used, git-diff-tree command outputs -differences between two commits only if one tree has the -specified string in a file and the corresponding file in the -other tree does not. The above example looks for a commit that -has the "if" statement in it in a file, but its parent commit -does not have it in the same shape in the corresponding file (or -the other way around, where the parent has it and the commit -does not), and the differences between them are shown, along -with the commit message (thanks to the -v flag). It does not -show anything for commits that do not touch this "if" statement. - -Also, in the original context, the same statement might have -appeared at first in a different file and later the file was -renamed to "a-file.c". CVS annotate would not help you to go -back across such a rename, but git would still help you in such -a situation. For that, you can give the -C flag to -git-diff-tree, like this: - - $ git-whatchanged -p -C -S'if (frotz) { - nitfol(); - }' - -When the -C flag is used, file renames and copies are followed. -So if the "if" statement in question happens to be in "a-file.c" -in the current HEAD commit, even if the file was originally -called "o-file.c" and then renamed in an earlier commit, or if -the file was created by copying an existing "o-file.c" in an -earlier commit, you will not lose track. If the "if" statement -did not change across such a rename or copy, then the commit that -does rename or copy would not show in the output, and if the -"if" statement was modified while the file was still called -"o-file.c", it would find the commit that changed the statement -when it was in "o-file.c". - -NOTE: The current version of "git-diff-tree -C" is not eager - enough to find copies, and it will miss the fact that a-file.c - was created by copying o-file.c unless o-file.c was somehow - changed in the same commit. - -You can use the --pickaxe-all flag in addition to the -S flag. -This causes the differences from all the files contained in -those two commits, not just the differences between the files -that contain this changed "if" statement: - - $ git-whatchanged -p -C -S'if (frotz) { - nitfol(); - }' --pickaxe-all - -NOTE: This option is called "--pickaxe-all" because -S - option is internally called "pickaxe", a tool for software - archaeologists. +With a small group, developers may just pull changes from each other's +repositories without the need for a central maintainer. -- cgit v1.3-5-g9baa From db9819a40a56b4747931e637c1c22a104dcab902 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Fri, 8 Dec 2006 01:27:21 -0500 Subject: Documentation: update git-clone man page with new behavior Update git-clone man page to reflect recent changes (--use-separate-remote default and use of .git/config instead of remotes files), and rewrite introduction. Signed-off-by: J. Bruce Fields Signed-off-by: Junio C Hamano --- Documentation/git-clone.txt | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index d5efa00dea..985043faca 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -16,22 +16,21 @@ SYNOPSIS DESCRIPTION ----------- -Clones a repository into a newly created directory. All remote -branch heads are copied under `$GIT_DIR/refs/heads/`, except -that the remote `master` is also copied to `origin` branch. -In addition, `$GIT_DIR/remotes/origin` file is set up to have -this line: +Clones a repository into a newly created directory, creates +remote-tracking branches for each branch in the cloned repository +(visible using `git branch -r`), and creates and checks out a master +branch equal to the cloned repository's master branch. - Pull: master:origin - -This is to help the typical workflow of working off of the -remote `master` branch. Every time `git pull` without argument -is run, the progress on the remote `master` branch is tracked by -copying it into the local `origin` branch, and merged into the -branch you are currently working on. Remote branches other than -`master` are also added there to be tracked. +After the clone, a plain `git fetch` without arguments will update +all the remote-tracking branches, and a `git pull` without +arguments will in addition merge the remote master branch into the +current branch. +This default configuration is achieved by creating references to +the remote branch heads under `$GIT_DIR/refs/remotes/origin` and +by initializing `remote.origin.url` and `remote.origin.fetch` +configuration variables. OPTIONS ------- -- cgit v1.3-5-g9baa From 62b339a544b1fa5199de7571c460d770cb286e65 Mon Sep 17 00:00:00 2001 From: Josef Weidendorfer Date: Sat, 9 Dec 2006 02:28:26 +0100 Subject: Add branch.*.merge warning and documentation update This patch clarifies the meaning of the branch.*.merge option. Previously, if branch.*.merge was specified but did not match any ref, the message "No changes." was not really helpful regarding the misconfiguration. This patch adds a warning for this. Signed-off-by: Josef Weidendorfer Signed-off-by: Junio C Hamano --- Documentation/config.txt | 11 +++++++++-- git-parse-remote.sh | 11 +++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 9090762819..21ec55797b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -125,10 +125,17 @@ apply.whitespace:: branch..remote:: When in branch , it tells `git fetch` which remote to fetch. + If this option is not given, `git fetch` defaults to remote "origin". branch..merge:: - When in branch , it tells `git fetch` the default remote branch - to be merged. + When in branch , it tells `git fetch` the default refspec to + be marked for merging in FETCH_HEAD. The value has exactly to match + a remote part of one of the refspecs which are fetched from the remote + given by "branch..remote". + The merge information is used by `git pull` (which at first calls + `git fetch`) to lookup the default branch for merging. Without + this option, `git pull` defaults to merge the first refspec fetched. + Specify multiple values to get an octopus merge. pager.color:: A boolean to enable/disable colored output when the pager is in diff --git a/git-parse-remote.sh b/git-parse-remote.sh index da064a53f6..6ae534bf89 100755 --- a/git-parse-remote.sh +++ b/git-parse-remote.sh @@ -134,6 +134,8 @@ canon_refs_list_for_fetch () { # or the first one otherwise; add prefix . to the rest # to prevent the secondary branches to be merged by default. merge_branches= + found_mergeref= + curr_branch= if test "$1" = "-d" then shift ; remote="$1" ; shift @@ -171,6 +173,10 @@ canon_refs_list_for_fetch () { dot_prefix= && break done fi + if test -z $dot_prefix + then + found_mergeref=true + fi case "$remote" in '') remote=HEAD ;; refs/heads/* | refs/tags/* | refs/remotes/*) ;; @@ -191,6 +197,11 @@ canon_refs_list_for_fetch () { fi echo "${dot_prefix}${force}${remote}:${local}" done + if test -z "$found_mergeref" -a "$curr_branch" + then + echo >&2 "Warning: No merge candidate found because value of config option + \"branch.${curr_branch}.merge\" does not match any remote branch fetched." + fi } # Returns list of src: (no store), or src:dst (store) -- cgit v1.3-5-g9baa From 4cfeccc75d6ab1ccc433770bac6bf3b15ab486d6 Mon Sep 17 00:00:00 2001 From: "J. Bruce Fields" Date: Fri, 8 Dec 2006 22:58:50 -0500 Subject: Documentation: simpler shared repository creation Take Johannes Schindelin's suggestions for a further simplification of the shared repository creation using git --bare init-db --shared, and for a simplified cvsimport using an existing CVS working directory. Also insert more man page references. Signed-off-by: J. Bruce Fields cvs-migration.txt | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) Signed-off-by: Junio C Hamano --- Documentation/cvs-migration.txt | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt index 47846bdab2..b657f4589f 100644 --- a/Documentation/cvs-migration.txt +++ b/Documentation/cvs-migration.txt @@ -43,8 +43,8 @@ Pull: refs/heads/master:refs/remotes/origin/master ------------ ================================ -You can update the shared repository with your changes by first commiting -your changes, and then using: +You can update the shared repository with your changes by first committing +your changes, and then using the gitlink:git-push[1] command: ------------------------------------------------ $ git push origin master @@ -76,11 +76,15 @@ possibly created from scratch or from a tarball (see the link:tutorial.html[tutorial]), or imported from an already existing CVS repository (see the next section). -If your project's working directory is /home/alice/myproject, you can -create a shared repository at /pub/repo.git with: +Assume your existing repo is at /home/alice/myproject. Create a new "bare" +repository (a repository without a working tree) and fetch your project into +it: ------------------------------------------------ -$ git clone -bare /home/alice/myproject /pub/repo.git +$ mkdir /pub/my-repo.git +$ cd /pub/my-repo.git +$ git --bare init-db --shared +$ git --bare fetch /home/alice/myproject master:master ------------------------------------------------ Next, give every team member read/write access to this repository. One @@ -93,10 +97,7 @@ Put all the committers in the same group, and make the repository writable by that group: ------------------------------------------------ -$ cd /pub -$ chgrp -R $group repo.git -$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s -$ GIT_DIR=repo.git git repo-config core.sharedrepository true +$ chgrp -R $group /pub/my-repo.git ------------------------------------------------ Make sure committers have a umask of at most 027, so that the directories @@ -107,15 +108,15 @@ Importing a CVS archive First, install version 2.1 or higher of cvsps from link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make -sure it is in your path. The magic command line is then +sure it is in your path. Then cd to a checked out CVS working directory +of the project you are interested in and run gitlink:git-cvsimport[1]: ------------------------------------------- -$ git cvsimport -v -d -C +$ git cvsimport -C ------------------------------------------- This puts a git archive of the named CVS module in the directory -, which will be created if necessary. The -v option makes -the conversion script very chatty. +, which will be created if necessary. The import checks out from CVS every revision of every file. Reportedly cvsimport can average some twenty revisions per second, so for a -- cgit v1.3-5-g9baa From d9671b75ad3bbf2f95f11a8571e9beaa12ccf6dd Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 8 Dec 2006 13:29:55 -0800 Subject: rerere: add clear, diff, and status commands git-am and git-rebase will be updated to use 'clear', and diff/status can be used to aid the user in tracking progress in the resolution process. Signed-off-by: Eric Wong Signed-off-by: Junio C Hamano --- Documentation/git-rerere.txt | 27 +++++++++++++++++++++++++-- git-rerere.perl | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 8b6b651237..22494b2b2e 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,8 +7,7 @@ git-rerere - Reuse recorded resolve SYNOPSIS -------- -'git-rerere' - +'git-rerere' [clear|diff|status] DESCRIPTION ----------- @@ -167,6 +166,30 @@ would conflict the same way the test merge you resolved earlier. `git-rerere` is run by `git rebase` to help you resolve this conflict. +COMMANDS +-------- + +Normally, git-rerere is run without arguments or user-intervention. +However, it has several commands that allow it to interact with +its working state. + +'clear':: + +This resets the metadata used by rerere if a merge resolution is to be +is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] +[--skip|--abort] will automatcally invoke this command. + +'diff':: + +This displays diffs for the current state of the resolution. It is +useful for tracking what has changed while the user is resolving +conflicts. Additional arguments are passed directly to the system +diff(1) command installed in PATH. + +'status':: + +Like diff, but this only prints the filenames that will be tracked +for resolutions. Author ------ diff --git a/git-rerere.perl b/git-rerere.perl index d3664ff491..b2550bb2ef 100755 --- a/git-rerere.perl +++ b/git-rerere.perl @@ -172,6 +172,38 @@ sub merge { -d "$rr_dir" || exit(0); read_rr(); + +if (@ARGV) { + my $arg = shift @ARGV; + if ($arg eq 'clear') { + for my $path (keys %merge_rr) { + my $name = $merge_rr{$path}; + if (-d "$rr_dir/$name" && + ! -f "$rr_dir/$name/postimage") { + rmtree(["$rr_dir/$name"]); + } + } + unlink $merge_rr; + } + elsif ($arg eq 'status') { + for my $path (keys %merge_rr) { + print $path, "\n"; + } + } + elsif ($arg eq 'diff') { + for my $path (keys %merge_rr) { + my $name = $merge_rr{$path}; + system('diff', ((@ARGV == 0) ? ('-u') : @ARGV), + '-L', "a/$path", '-L', "b/$path", + "$rr_dir/$name/preimage", $path); + } + } + else { + die "$0 unknown command: $arg\n"; + } + exit 0; +} + my %conflict = map { $_ => 1 } find_conflict(); # MERGE_RR records paths with conflicts immediately after merge -- cgit v1.3-5-g9baa From cda2d3c112a03079af9019c7d6617e65ab88ae7e Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 8 Dec 2006 13:03:12 -0800 Subject: git-rerere: add 'gc' command. Over time, unresolved rr-cache entries are accumulated and they tend to get less and less likely to be useful as the tips of branches advance. Reorder documentation page to show the subcommand section earlier than the discussion section. Signed-off-by: Junio C Hamano --- Documentation/git-rerere.txt | 56 +++++++++++++++++++++++++------------------- git-rerere.perl | 25 ++++++++++++++++++++ 2 files changed, 57 insertions(+), 24 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 22494b2b2e..116dca4c06 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -26,6 +26,38 @@ results and applying the previously recorded hand resolution. You need to create `$GIT_DIR/rr-cache` directory to enable this command. + +COMMANDS +-------- + +Normally, git-rerere is run without arguments or user-intervention. +However, it has several commands that allow it to interact with +its working state. + +'clear':: + +This resets the metadata used by rerere if a merge resolution is to be +is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] +[--skip|--abort] will automatcally invoke this command. + +'diff':: + +This displays diffs for the current state of the resolution. It is +useful for tracking what has changed while the user is resolving +conflicts. Additional arguments are passed directly to the system +diff(1) command installed in PATH. + +'status':: + +Like diff, but this only prints the filenames that will be tracked +for resolutions. + +'gc':: + +This command is used to prune records of conflicted merge that +occurred long time ago. + + DISCUSSION ---------- @@ -166,30 +198,6 @@ would conflict the same way the test merge you resolved earlier. `git-rerere` is run by `git rebase` to help you resolve this conflict. -COMMANDS --------- - -Normally, git-rerere is run without arguments or user-intervention. -However, it has several commands that allow it to interact with -its working state. - -'clear':: - -This resets the metadata used by rerere if a merge resolution is to be -is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] -[--skip|--abort] will automatcally invoke this command. - -'diff':: - -This displays diffs for the current state of the resolution. It is -useful for tracking what has changed while the user is resolving -conflicts. Additional arguments are passed directly to the system -diff(1) command installed in PATH. - -'status':: - -Like diff, but this only prints the filenames that will be tracked -for resolutions. Author ------ diff --git a/git-rerere.perl b/git-rerere.perl index b2550bb2ef..61eef575da 100755 --- a/git-rerere.perl +++ b/git-rerere.perl @@ -169,6 +169,28 @@ sub merge { return 0; } +sub garbage_collect_rerere { + # We should allow specifying these from the command line and + # that is why the caller gives @ARGV to us, but I am lazy. + + my $cutoff_noresolve = 15; # two weeks + my $cutoff_resolve = 60; # two months + my @to_remove; + while (<$rr_dir/*/preimage>) { + my ($dir) = /^(.*)\/preimage$/; + my $cutoff = ((-f "$dir/postimage") + ? $cutoff_resolve + : $cutoff_noresolve); + my $age = -M "$_"; + if ($cutoff <= $age) { + push @to_remove, $dir; + } + } + if (@to_remove) { + rmtree(\@to_remove); + } +} + -d "$rr_dir" || exit(0); read_rr(); @@ -198,6 +220,9 @@ if (@ARGV) { "$rr_dir/$name/preimage", $path); } } + elsif ($arg eq 'gc') { + garbage_collect_rerere(@ARGV); + } else { die "$0 unknown command: $arg\n"; } -- cgit v1.3-5-g9baa From 6c96753df9db7f790a2ac4d95ec2a868394cd5ff Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 8 Dec 2006 21:48:07 -0800 Subject: Documentation/git-commit: rewrite to make it more end-user friendly. Signed-off-by: Junio C Hamano --- Documentation/git-commit.txt | 233 +++++++++++++++++++++++++++++-------------- 1 file changed, 157 insertions(+), 76 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 517a86b238..97d66ef4d2 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -14,25 +14,41 @@ SYNOPSIS DESCRIPTION ----------- -Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command specified -by either the VISUAL or EDITOR environment variables are used to edit -the commit log message. +Use 'git commit' when you want to record your changes into the repository +along with a log message describing what the commit is about. All changes +to be committed must be explicitly identified using one of the following +methods: -Several environment variable are used during commits. They are -documented in gitlink:git-commit-tree[1]. +1. by using gitlink:git-add[1] to incrementally "add" changes to the + next commit before using the 'commit' command (Note: even modified + files must be "added"); +2. by using gitlink:git-rm[1] to identify content removal for the next + commit, again before using the 'commit' command; + +3. by directly listing files containing changes to be committed as arguments + to the 'commit' command, in which cases only those files alone will be + considered for the commit; + +4. by using the -a switch with the 'commit' command to automatically "add" + changes from all known files i.e. files that have already been committed + before, and perform the actual commit. + +The gitlink:git-status[1] command can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters you would give to +this command. + +If you make a commit and then found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more -information. OPTIONS ------- -a|--all:: - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + Tell the command to automatically stage files that have + been modified and deleted, but new files you have not + told git about are not affected. -c or -C :: Take existing commit object, and reuse the log message @@ -55,16 +71,13 @@ OPTIONS -s|--signoff:: Add Signed-off-by line at the end of the commit message. --v|--verify:: - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - 'suspicious lines' is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. - --n|--no-verify:: - The opposite of `--verify`. +--no-verify:: + By default, the command looks for suspicious lines the + commit introduces, and aborts committing if there is one. + The definition of 'suspicious lines' is currently the + lines that has trailing whitespaces, and the lines whose + indentation has a SP character immediately followed by a + TAB character. This option turns off the check. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +108,137 @@ but can be used to amend a merge commit. -- -i|--include:: - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. - --o|--only:: - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. + Before making a commit out of staged contents so far, + stage the contents of paths given on the command line + as well. This is usually not what you want unless you + are concluding a conflicted merge. \--:: Do not interpret any more arguments as options. ...:: - Files to be committed. The meaning of these is - different between `--include` and `--only`. Without - either, it defaults `--only` semantics. - -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. + When files are given on the command line, the command + commits the contents of the named files, without + recording the changes already staged. The contents of + these files are also staged for the next commit on top + of what have been staged before. -Discussion ----------- - -`git commit` without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory. - -`git commit --include paths...` is equivalent to - - git update-index --remove paths... - git commit - -That is, update the specified paths to the index and then commit -the whole tree. - -`git commit paths...` largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion. - -. It refuses to run during a merge (i.e. when - `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users - that the traditional semantics now needs -i flag. - -. It refuses to run if named `paths...` are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier `git diff` (not `git diff HEAD`) - would have shown the differences since the last `git - update-index paths...` to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last `git - update-index paths...` was done) are not being committed. - -. It reads HEAD commit into a temporary index file, updates the - specified `paths...` and makes a commit. At the same time, - the real index file is also updated with the same `paths...`. +EXAMPLES +-------- +When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with gitlink:git-add[1]. Removal +of a file is staged with gitlink:git-rm[1]. After building the +state to be committed incrementally with these commands, `git +commit` (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example: + +------------ +$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit +------------ + +//////////// +We should fix 'git rm' to remove goodbye.c from both index and +working tree for the above example. +//////////// + +Instead of staging files after each individual change, you can +tell `git commit` to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding `git add` and `git rm` +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree: + +------------ +$ edit hello.c +$ rm goodbye.c +$ git commit -a +------------ + +The command `git commit -a` first looks at your working tree, +notices that you have modified hello.c and removed goodbye.c, +and performs necessary `git add` and `git rm` for you. + +After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to `git commit`. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths: + +------------ +$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile +------------ + +This makes a commit that records the modification to `Makefile`. +The changes staged for `hello.c` and `hello.h` are not included +in the resulting commit. However, their changes are not lost -- +they are still staged and merely held back. After the above +sequence, if you do: + +------------ +$ git commit +------------ + +this second commit would record the changes to `hello.c` and +`hello.h` as expected. + +After a merge (initiated by either gitlink:git-merge[1] or +gitlink:git-pull[1]) stops because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with gitlink:git-status[1] +and after fixing them manually in your working tree, you would +stage the result as usual with gitlink:git-add[1]: + +------------ +$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c +------------ + +After resolving conflicts and staging the result, `git ls-files -u` +would stop mentioning the conflicted path. When you are done, +run `git commit` to finally record the merge: + +------------ +$ git commit +------------ + +As with the case to record your own changes, you can use `-a` +option to save typing. One difference is that during a merge +resolution, you cannot use `git commit` with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see `-i` option). + + +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. + +HOOKS +----- +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. -`git commit --all` updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in. +SEE ALSO +-------- +gitlink:git-add[1], +gitlink:git-rm[1], +gitlink:git-mv[1], +gitlink:git-merge[1], +gitlink:git-commit-tree[1] Author ------ -- cgit v1.3-5-g9baa From d44c92d6ab4ded7a1960bb0b4a1da0c2fc102b89 Mon Sep 17 00:00:00 2001 From: Chris Wright Date: Sun, 10 Dec 2006 23:39:32 -0800 Subject: no need to install manpages as executable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No need to install manpages as executable. Noticed by Ville Skytt,Ad(B. Signed-off-by: Chris Wright Signed-off-by: Junio C Hamano --- Documentation/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/Makefile b/Documentation/Makefile index c00f5f62b7..d68bc4a788 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -56,8 +56,8 @@ man7: $(DOC_MAN7) install: man $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir) - $(INSTALL) $(DOC_MAN1) $(DESTDIR)$(man1dir) - $(INSTALL) $(DOC_MAN7) $(DESTDIR)$(man7dir) + $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) # -- cgit v1.3-5-g9baa From dd31da2fdc199132c9fd42023aea5b33672d73cc Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 12 Dec 2006 14:47:01 -0800 Subject: git-svn: allow dcommit to take an alternate head Previously dcommit would unconditionally commit all patches up-to and including the current HEAD. Now if an optional command-line argument is specified, it will only commit up to the specified revision. Signed-off-by: Eric Wong Signed-off-by: Junio C Hamano --- Documentation/git-svn.txt | 6 ++++-- git-svn.perl | 11 ++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index a45067e164..c589a98630 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -57,11 +57,13 @@ See '<>' if you are interested in manually joining branches on commit. 'dcommit':: - Commit all diffs from the current HEAD directly to the SVN + Commit all diffs from a specified head directly to the SVN repository, and then rebase or reset (depending on whether or - not there is a diff between SVN and HEAD). It is recommended + not there is a diff between SVN and head). It is recommended that you run git-svn fetch and rebase (not pull) your commits against the latest changes in the SVN repository. + An optional command-line argument may be specified as an + alternative to HEAD. This is advantageous over 'commit' (below) because it produces cleaner, more linear history. diff --git a/git-svn.perl b/git-svn.perl index 06e89ffecf..819584baf5 100755 --- a/git-svn.perl +++ b/git-svn.perl @@ -604,8 +604,9 @@ sub commit_lib { } sub dcommit { + my $head = shift || 'HEAD'; my $gs = "refs/remotes/$GIT_SVN"; - chomp(my @refs = safe_qx(qw/git-rev-list --no-merges/, "$gs..HEAD")); + chomp(my @refs = safe_qx(qw/git-rev-list --no-merges/, "$gs..$head")); my $last_rev; foreach my $d (reverse @refs) { if (quiet_run('git-rev-parse','--verify',"$d~1") != 0) { @@ -632,16 +633,16 @@ sub dcommit { } return if $_dry_run; fetch(); - my @diff = safe_qx(qw/git-diff-tree HEAD/, $gs); + my @diff = safe_qx('git-diff-tree', $head, $gs); my @finish; if (@diff) { @finish = qw/rebase/; push @finish, qw/--merge/ if $_merge; push @finish, "--strategy=$_strategy" if $_strategy; - print STDERR "W: HEAD and $gs differ, using @finish:\n", @diff; + print STDERR "W: $head and $gs differ, using @finish:\n", @diff; } else { - print "No changes between current HEAD and $gs\n", - "Hard resetting to the latest $gs\n"; + print "No changes between current $head and $gs\n", + "Resetting to the latest $gs\n"; @finish = qw/reset --mixed/; } sys('git', @finish, $gs); -- cgit v1.3-5-g9baa From e2b7008752d85874919ea718d098fec01b4a9019 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Wed, 13 Dec 2006 00:01:41 +0100 Subject: Get rid of the dependency on RCS' merge program Now that we have git-merge-file, an RCS merge lookalike, we no longer need it. So long, merge, and thanks for all the fish! Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- .gitignore | 1 + Documentation/git-merge-index.txt | 4 +-- INSTALL | 9 ----- git-cvsserver.perl | 2 +- git-rerere.perl | 2 +- git.spec.in | 2 +- merge-file.c | 75 +++++++-------------------------------- t/t0000-basic.sh | 14 +------- 8 files changed, 20 insertions(+), 89 deletions(-) (limited to 'Documentation') diff --git a/.gitignore b/.gitignore index 7f2cd55088..d706dd92c6 100644 --- a/.gitignore +++ b/.gitignore @@ -60,6 +60,7 @@ git-mailsplit git-merge git-merge-base git-merge-index +git-merge-file git-merge-tree git-merge-octopus git-merge-one-file diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 6cd0601082..0cf505ea84 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -40,8 +40,8 @@ If "git-merge-index" is called with multiple s (or -a) then it processes them in turn only stopping if merge returns a non-zero exit code. -Typically this is run with the a script calling the merge command from -the RCS package. +Typically this is run with the a script calling git's imitation of +the merge command from the RCS package. A sample script called "git-merge-one-file" is included in the distribution. diff --git a/INSTALL b/INSTALL index 8f69039fb9..b5dd9f0abb 100644 --- a/INSTALL +++ b/INSTALL @@ -82,15 +82,6 @@ Issues of note: do that even if it wasn't for git. There's no point in living in the dark ages any more. - - "merge", the standard UNIX three-way merge program. It usually - comes with the "rcs" package on most Linux distributions, so if - you have a developer install you probably have it already, but a - "graphical user desktop" install might have left it out. - - You'll only need the merge program if you do development using - git, and if you only use git to track other peoples work you'll - never notice the lack of it. - - "wish", the Tcl/Tk windowing shell is used in gitk to show the history graphically diff --git a/git-cvsserver.perl b/git-cvsserver.perl index ca519b7e49..55ff83b1a3 100755 --- a/git-cvsserver.perl +++ b/git-cvsserver.perl @@ -945,7 +945,7 @@ sub req_update $log->debug("Temporary directory for merge is $dir"); - my $return = system("merge", $file_local, $file_old, $file_new); + my $return = system("git merge-file", $file_local, $file_old, $file_new); $return >>= 8; if ( $return == 0 ) diff --git a/git-rerere.perl b/git-rerere.perl index d3664ff491..2e8dbbd4ea 100755 --- a/git-rerere.perl +++ b/git-rerere.perl @@ -154,7 +154,7 @@ sub find_conflict { sub merge { my ($name, $path) = @_; record_preimage($path, "$rr_dir/$name/thisimage"); - unless (system('merge', map { "$rr_dir/$name/${_}image" } + unless (system('git merge-file', map { "$rr_dir/$name/${_}image" } qw(this pre post))) { my $in; open $in, "<$rr_dir/$name/thisimage" or diff --git a/git.spec.in b/git.spec.in index f2374b7331..fb95e37594 100644 --- a/git.spec.in +++ b/git.spec.in @@ -24,7 +24,7 @@ This is a dummy package which brings in all subpackages. %package core Summary: Core git tools Group: Development/Tools -Requires: zlib >= 1.2, rsync, rcs, curl, less, openssh-clients, expat +Requires: zlib >= 1.2, rsync, curl, less, openssh-clients, expat %description core This is a stupid (but extremely fast) directory content manager. It doesn't do a whole lot, but what it _does_ do is track directory diff --git a/merge-file.c b/merge-file.c index fc9b148993..69dc1ebbf7 100644 --- a/merge-file.c +++ b/merge-file.c @@ -3,52 +3,6 @@ #include "xdiff-interface.h" #include "blob.h" -static void rm_temp_file(const char *filename) -{ - unlink(filename); - free((void *)filename); -} - -static const char *write_temp_file(mmfile_t *f) -{ - int fd; - const char *tmp = getenv("TMPDIR"); - char *filename; - - if (!tmp) - tmp = "/tmp"; - filename = mkpath("%s/%s", tmp, "git-tmp-XXXXXX"); - fd = mkstemp(filename); - if (fd < 0) - return NULL; - filename = xstrdup(filename); - if (f->size != xwrite(fd, f->ptr, f->size)) { - rm_temp_file(filename); - return NULL; - } - close(fd); - return filename; -} - -static void *read_temp_file(const char *filename, unsigned long *size) -{ - struct stat st; - char *buf = NULL; - int fd = open(filename, O_RDONLY); - if (fd < 0) - return NULL; - if (!fstat(fd, &st)) { - *size = st.st_size; - buf = xmalloc(st.st_size); - if (st.st_size != xread(fd, buf, st.st_size)) { - free(buf); - buf = NULL; - } - } - close(fd); - return buf; -} - static int fill_mmfile_blob(mmfile_t *f, struct blob *obj) { void *buf; @@ -72,22 +26,19 @@ static void free_mmfile(mmfile_t *f) static void *three_way_filemerge(mmfile_t *base, mmfile_t *our, mmfile_t *their, unsigned long *size) { - void *res; - const char *t1, *t2, *t3; - - t1 = write_temp_file(base); - t2 = write_temp_file(our); - t3 = write_temp_file(their); - res = NULL; - if (t1 && t2 && t3) { - int code = run_command("merge", t2, t1, t3, NULL); - if (!code || code == -1) - res = read_temp_file(t2, size); - } - rm_temp_file(t1); - rm_temp_file(t2); - rm_temp_file(t3); - return res; + mmbuffer_t res; + xpparam_t xpp; + int merge_status; + + memset(&xpp, 0, sizeof(xpp)); + merge_status = xdl_merge(base, our, ".our", their, ".their", + &xpp, XDL_MERGE_ZEALOUS, &res); + + if (merge_status < 0) + return NULL; + + *size = res.size; + return res.ptr; } static int common_outf(void *priv_, mmbuffer_t *mb, int nbuf) diff --git a/t/t0000-basic.sh b/t/t0000-basic.sh index 81f3bedc90..3260d1d7a7 100755 --- a/t/t0000-basic.sh +++ b/t/t0000-basic.sh @@ -19,11 +19,7 @@ modification *should* take notice and update the test vectors here. ' ################################################################ -# It appears that people are getting bitten by not installing -# 'merge' (usually part of RCS package in binary distributions). -# Check this and error out before running any tests. Also catch -# the bogosity of trying to run tests without building while we -# are at it. +# It appears that people try to run tests without building... ../git >/dev/null if test $? != 1 @@ -32,14 +28,6 @@ then exit 1 fi -merge >/dev/null 2>/dev/null -if test $? = 127 -then - echo >&2 'You do not seem to have "merge" installed. -Please check INSTALL document.' - exit 1 -fi - . ./test-lib.sh ################################################################ -- cgit v1.3-5-g9baa From 25fb62905890d7860f742b4f2215fdf754ae7fee Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 13 Dec 2006 00:59:58 -0800 Subject: git-push: document removal of remote ref with : pathspec Signed-off-by: Junio C Hamano --- Documentation/git-push.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index d4ae99fa53..197f4b512f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -49,12 +49,14 @@ corresponding remotes file---see below), then all the refs that exist both on the local side and on the remote side are updated. + -Some short-cut notations are also supported. +`tag ` means the same as `refs/tags/:refs/tags/`. + -* `tag ` means the same as `refs/tags/:refs/tags/`. -* A parameter without a colon is equivalent to - `:`, hence updates in the destination from - in the source. +A parameter without a colon is equivalent to +`:`, hence updates in the destination from +in the source. ++ +Pushing an empty allows you to delete the ref from +the remote repository. \--all:: Instead of naming each ref to push, specifies that all @@ -75,7 +77,8 @@ include::urls.txt[] Author ------ -Written by Junio C Hamano +Written by Junio C Hamano , later rewritten in C +by Linus Torvalds Documentation -------------- -- cgit v1.3-5-g9baa From a159ca0cb7e0acdd37cb066327dcb020d95602d0 Mon Sep 17 00:00:00 2001 From: Andy Parkins Date: Wed, 13 Dec 2006 09:13:28 +0000 Subject: Allow subcommand.color and color.subcommand color configuration While adding colour to the branch command it was pointed out that a config option like "branch.color" conflicts with the pre-existing "branch.something" namespace used for specifying default merge urls and branches. The suggested solution was to flip the order of the components to "color.branch", which I did for colourising branch. This patch does the same thing for - git-log (color.diff) - git-status (color.status) - git-diff (color.diff) - pager (color.pager) I haven't removed the old config options; but they should probably be deprecated and eventually removed to prevent future namespace collisions. I've done this deprecation by changing the documentation for the config file to match the new names; and adding the "color.XXX" options to contrib/completion/git-completion.bash. Unfortunately git-svn reads "diff.color" and "pager.color"; which I don't like to change unilaterally. Signed-off-by: Andy Parkins Signed-off-by: Junio C Hamano --- Documentation/config.txt | 12 ++++++------ builtin-log.c | 2 +- config.c | 2 +- contrib/completion/git-completion.bash | 3 +++ diff.c | 4 ++-- wt-status.c | 4 ++-- 6 files changed, 15 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 21ec55797b..f5a552ee87 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -137,16 +137,16 @@ branch..merge:: this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. -pager.color:: +color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true). -diff.color:: +color.diff:: When true (or `always`), always use colors in patch. When false (or `never`), never. When set to `auto`, use colors only when the output is to the terminal. -diff.color.:: +color.diff.:: Use customized color for diff colorization. `` specifies which part of the patch to use the specified color, and is one of `plain` (context text), `meta` @@ -271,19 +271,19 @@ showbranch.default:: The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. -status.color:: +color.status:: A boolean to enable/disable color in the output of gitlink:git-status[1]. May be set to `true` (or `always`), `false` (or `never`) or `auto`, in which case colors are used only when the output is to a terminal. Defaults to false. -status.color.:: +color.status.:: Use customized color for status colorization. `` is one of `header` (the header text of the status message), `updated` (files which are updated but not committed), `changed` (files which are changed but not updated in the index), or `untracked` (files which are not tracked by git). The values of - these variables may be specified as in diff.color.. + these variables may be specified as in color.diff.. tar.umask:: By default, gitlink:git-tar-tree[1] sets file and directories modes diff --git a/builtin-log.c b/builtin-log.c index 7acf5d3b0c..6821a08442 100644 --- a/builtin-log.c +++ b/builtin-log.c @@ -118,7 +118,7 @@ static int git_format_config(const char *var, const char *value) strcat(extra_headers, value); return 0; } - if (!strcmp(var, "diff.color")) { + if (!strcmp(var, "diff.color") || !strcmp(var, "color.diff")) { return 0; } return git_log_config(var, value); diff --git a/config.c b/config.c index 3cae3901aa..1bdef44a3a 100644 --- a/config.c +++ b/config.c @@ -314,7 +314,7 @@ int git_default_config(const char *var, const char *value) return 0; } - if (!strcmp(var, "pager.color")) { + if (!strcmp(var, "pager.color") || !strcmp(var, "color.pager")) { pager_use_color = git_config_bool(var,value); return 0; } diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash index 447ec20467..9c4d23a23c 100755 --- a/contrib/completion/git-completion.bash +++ b/contrib/completion/git-completion.bash @@ -712,10 +712,13 @@ _git_repo_config () core.legacyHeaders i18n.commitEncoding diff.color + color.diff diff.renameLimit diff.renames pager.color + color.pager status.color + color.status log.showroot show.difftree showbranch.default diff --git a/diff.c b/diff.c index 33153787b8..726b01e75e 100644 --- a/diff.c +++ b/diff.c @@ -60,7 +60,7 @@ int git_diff_ui_config(const char *var, const char *value) diff_rename_limit_default = git_config_int(var, value); return 0; } - if (!strcmp(var, "diff.color")) { + if (!strcmp(var, "diff.color") || !strcmp(var, "color.diff")) { diff_use_color_default = git_config_colorbool(var, value); return 0; } @@ -74,7 +74,7 @@ int git_diff_ui_config(const char *var, const char *value) diff_detect_rename_default = DIFF_DETECT_RENAME; return 0; } - if (!strncmp(var, "diff.color.", 11)) { + if (!strncmp(var, "diff.color.", 11) || !strncmp(var, "color.diff.", 11)) { int slot = parse_diff_color_slot(var, 11); color_parse(value, var, diff_colors[slot]); return 0; diff --git a/wt-status.c b/wt-status.c index de1be5bc66..df582a03ef 100644 --- a/wt-status.c +++ b/wt-status.c @@ -297,11 +297,11 @@ void wt_status_print(struct wt_status *s) int git_status_config(const char *k, const char *v) { - if (!strcmp(k, "status.color")) { + if (!strcmp(k, "status.color") || !strcmp(k, "color.status")) { wt_status_use_color = git_config_colorbool(k, v); return 0; } - if (!strncmp(k, "status.color.", 13)) { + if (!strncmp(k, "status.color.", 13) || !strncmp(k, "color.status", 13)) { int slot = parse_status_slot(k, 13); color_parse(v, k, wt_status_colors[slot]); } -- cgit v1.3-5-g9baa From f2dd1c9adfe961ea611545b018bc67e5d83ee3db Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 13 Dec 2006 01:33:43 -0800 Subject: Revert "git-diff: Introduce --index and deprecate --cached." This reverts commit 4c81c213a479e4aae0653a56ad6e8db5c31f019c. Although --cached and --index are confusing wording, the use of word --cached for git-diff is consistent with git-apply. It means "work with index without looking at the working tree". We should probably come up with better wording for --cached, if somebody wants to deprecate it. But making --index and --cached synonyms for diff while leaving them mean different things for apply is no good. --- Documentation/git-diff.txt | 6 ++---- builtin-diff.c | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 3144864d85..228c4d95bd 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -22,10 +22,8 @@ the number of trees given to the command. * When one is given, the working tree and the named tree are compared, using `git-diff-index`. The option - `--index` can be given to compare the index file and + `--cached` can be given to compare the index file and the named tree. - `--cached` is a deprecated alias for `--index`. It's use is - discouraged. * When two s are given, these two trees are compared using `git-diff-tree`. @@ -49,7 +47,7 @@ Various ways to check your working tree:: + ------------ $ git diff <1> -$ git diff --index <2> +$ git diff --cached <2> $ git diff HEAD <3> ------------ + diff --git a/builtin-diff.c b/builtin-diff.c index 1c535b1dd6..a6590205e8 100644 --- a/builtin-diff.c +++ b/builtin-diff.c @@ -137,7 +137,7 @@ static int builtin_diff_index(struct rev_info *revs, int cached = 0; while (1 < argc) { const char *arg = argv[1]; - if (!strcmp(arg, "--index") || !strcmp(arg, "--cached")) + if (!strcmp(arg, "--cached")) cached = 1; else usage(builtin_diff_usage); -- cgit v1.3-5-g9baa From 7ef0435088f41165ece95b6f226d3c15438505a5 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 13 Dec 2006 00:58:28 -0800 Subject: spurious .sp in manpages This is just a random hack to work around problems people seem to be seeing in manpage backend of xmlto (it appears we are getting ".sp" at the end of line without line break). Could people test this out? Signed-off-by: Junio C Hamano --- Documentation/callouts.xsl | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'Documentation') diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl index ad03755d8f..6a361a2136 100644 --- a/Documentation/callouts.xsl +++ b/Documentation/callouts.xsl @@ -13,4 +13,18 @@ .br + + + + + + + + + + + + -- cgit v1.3-5-g9baa From 1d77043b005921cf7fcebfe680777df23ad10119 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 13 Dec 2006 12:11:03 -0800 Subject: config documentation: group color items together. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index f5a552ee87..a3587f8397 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -137,10 +137,6 @@ branch..merge:: this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. -color.pager:: - A boolean to enable/disable colored output when the pager is in - use (default is true). - color.diff:: When true (or `always`), always use colors in patch. When false (or `never`), never. When set to `auto`, use @@ -157,6 +153,24 @@ color.diff.:: `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or `white`. +color.pager:: + A boolean to enable/disable colored output when the pager is in + use (default is true). + +color.status:: + A boolean to enable/disable color in the output of + gitlink:git-status[1]. May be set to `true` (or `always`), + `false` (or `never`) or `auto`, in which case colors are used + only when the output is to a terminal. Defaults to false. + +color.status.:: + Use customized color for status colorization. `` is + one of `header` (the header text of the status message), + `updated` (files which are updated but not committed), + `changed` (files which are changed but not updated in the index), + or `untracked` (files which are not tracked by git). The values of + these variables may be specified as in color.diff.. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. @@ -271,20 +285,6 @@ showbranch.default:: The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. -color.status:: - A boolean to enable/disable color in the output of - gitlink:git-status[1]. May be set to `true` (or `always`), - `false` (or `never`) or `auto`, in which case colors are used - only when the output is to a terminal. Defaults to false. - -color.status.:: - Use customized color for status colorization. `` is - one of `header` (the header text of the status message), - `updated` (files which are updated but not committed), - `changed` (files which are changed but not updated in the index), - or `untracked` (files which are not tracked by git). The values of - these variables may be specified as in color.diff.. - 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 -- cgit v1.3-5-g9baa From f5e6b89b3a4420481a6ecdc05df325cb6d69d114 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 14 Dec 2006 00:03:18 -0800 Subject: Update git-diff documentation Porcelain documentation should talk in terms of end-user workflow, not in terms of implementation details. Do not suggest update-index, but git-add instead. Explain differences among 0-, 1- and 2-tree cases not as differences of number of trees given to the command, but say why user would want to give these number of trees to the command in what situation. Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 52 +++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 17 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 228c4d95bd..127d68c962 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -14,30 +14,48 @@ DESCRIPTION ----------- Show changes between two trees, a tree and the working tree, a tree and the index file, or the index file and the working tree. -The combination of what is compared with what is determined by -the number of trees given to the command. -* When no is given, the working tree and the index - file are compared, using `git-diff-files`. +'git-diff' [--options] [--] [...]:: -* When one is given, the working tree and the named - tree are compared, using `git-diff-index`. The option - `--cached` can be given to compare the index file and - the named tree. + This form is to view the changes you made relative to + the index (staging area for the next commit). In other + 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]. + +'git-diff' [--options] --cached [] [--] [...]:: + + This form is to view the changes you staged for the next + commit relative to the named . Typically you + would want comparison with the latest commit, so if you + do not give , it defaults to HEAD. + +'git-diff' [--options] -- [...]:: + + This form is to view the changes you have in your + working tree relative to the named . You can + use HEAD to compare it with the latest commit, or a + branch name to compare with the tip of a different + branch. + +'git-diff' [--options] -- [...]:: + + This form is to view the changes between two , + for example, tips of two branches. + +Just in case if you are doing something exotic, it should be +noted that all of the in the above description can be +any . -* When two s are given, these two trees are compared - using `git-diff-tree`. OPTIONS ------- ---diff-options:: - '--diff-options' are passed to the `git-diff-files`, - `git-diff-index`, and `git-diff-tree` commands. See the - documentation for these commands for description. +include::diff-options.txt[] ...:: - The arguments are also passed to `git-diff-\*` - commands. + The parameters, when given, are used to limit + the diff to the named paths (you can give directory + names and get diff for all files under them). EXAMPLES @@ -51,7 +69,7 @@ $ git diff --cached <2> $ git diff HEAD <3> ------------ + -<1> changes in the working tree since your last git-update-index. +<1> changes in the working tree not yet staged for the next commit. <2> changes between the index and your last commit; what you would be committing if you run "git commit" without "-a" option. <3> changes in the working tree since your last commit; what you -- cgit v1.3-5-g9baa From 5d7eeee2ac64e277e47ce2cdabd1af0d2501a96f Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Thu, 14 Dec 2006 11:31:05 +0100 Subject: git-show: grok blobs, trees and tags, too Since git-show is pure Porcelain, it is the ideal candidate to pretty print other things than commits, too. Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- Documentation/git-show.txt | 40 ++++++++++++++++++---- builtin-log.c | 82 +++++++++++++++++++++++++++++++++++++++++++++- generate-cmdlist.sh | 2 +- 3 files changed, 115 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 4c880a8717..98dea6125d 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -3,20 +3,27 @@ git-show(1) NAME ---- -git-show - Show one commit with difference it introduces +git-show - Show various types of objects SYNOPSIS -------- -'git-show'