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/tutorial.txt') 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 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/tutorial.txt') 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 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/tutorial.txt') 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 From ef0a89a604acb7fc2e3c08566641b95b23d87fd6 Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Fri, 15 Dec 2006 00:44:58 -0500 Subject: Provide more meaningful output from 'git init-db'. Back in the old days of Git when people messed around with their GIT_DIR environment variable more often it was nice to know whether or not git-init-db created a .git directory or used GIT_DIR. As most users at that time were rather technical UNIXy folk the message "defaulting to local storage area" made sense to some and seemed reasonable. But it doesn't really convey any meaning to the new Git user, as they don't know what a 'local storage area is' nor do they know enough about Git to care. It also really doesn't tell the experienced Git user a whole lot about the command they just ran, especially if they might be reinitializing an existing repository (e.g. to update hooks). So now we print out what we did ("Initialized empty" or "Reinitialized existing"), what type of repository ("" or "shared"), and what location the repository will be in ("$GIT_DIR"). Suggested in part by Andy Parkins in his Git 'niggles' list (<200612132237.10051.andyparkins@gmail.com>). Signed-off-by: Shawn O. Pearce Signed-off-by: Junio C Hamano --- Documentation/core-tutorial.txt | 2 +- Documentation/tutorial-2.txt | 2 +- Documentation/tutorial.txt | 2 +- builtin-init-db.c | 21 ++++++++++++++------- 4 files changed, 17 insertions(+), 10 deletions(-) (limited to 'Documentation/tutorial.txt') diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 1c311590c7..5ea611748c 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -57,7 +57,7 @@ $ git-init-db to which git will reply ---------------- -defaulting to local storage area +Initialized empty Git repository in .git/ ---------------- which is just git's way of saying that you haven't been doing anything diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 8606381e6c..aa62e13de9 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -18,7 +18,7 @@ Let's start a new project and create a small amount of history: $ mkdir test-project $ cd test-project $ git init-db -defaulting to local storage area +Initialized empty Git repository in .git/ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 02dede320c..cb808d924b 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -38,7 +38,7 @@ $ git init-db Git will reply ------------------------------------------------ -defaulting to local storage area +Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new diff --git a/builtin-init-db.c b/builtin-init-db.c index 235a0ee48f..8f2b7500dc 100644 --- a/builtin-init-db.c +++ b/builtin-init-db.c @@ -164,13 +164,14 @@ static void copy_templates(const char *git_dir, int len, const char *template_di closedir(dir); } -static void create_default_files(const char *git_dir, const char *template_path) +static int create_default_files(const char *git_dir, const char *template_path) { unsigned len = strlen(git_dir); static char path[PATH_MAX]; unsigned char sha1[20]; struct stat st1; char repo_version_string[10]; + int reinit; if (len > sizeof(path)-50) die("insane git directory %s", git_dir); @@ -218,7 +219,8 @@ static void create_default_files(const char *git_dir, const char *template_path) * branch, if it does not exist yet. */ strcpy(path + len, "HEAD"); - if (read_ref("HEAD", sha1) < 0) { + reinit = !read_ref("HEAD", sha1); + if (!reinit) { if (create_symref("HEAD", "refs/heads/master") < 0) exit(1); } @@ -239,6 +241,8 @@ static void create_default_files(const char *git_dir, const char *template_path) git_config_set("core.filemode", filemode ? "true" : "false"); } + + return reinit; } static const char init_db_usage[] = @@ -256,7 +260,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix) const char *sha1_dir; const char *template_dir = NULL; char *path; - int len, i; + int len, i, reinit; for (i = 1; i < argc; i++, argv++) { const char *arg = argv[1]; @@ -274,10 +278,8 @@ int cmd_init_db(int argc, const char **argv, const char *prefix) * Set up the default .git directory contents */ git_dir = getenv(GIT_DIR_ENVIRONMENT); - if (!git_dir) { + if (!git_dir) git_dir = DEFAULT_GIT_DIR_ENVIRONMENT; - fprintf(stderr, "defaulting to local storage area\n"); - } safe_create_dir(git_dir, 0); /* Check to see if the repository version is right. @@ -287,7 +289,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix) */ check_repository_format(); - create_default_files(git_dir, template_dir); + reinit = create_default_files(git_dir, template_dir); /* * And set up the object store. @@ -314,5 +316,10 @@ int cmd_init_db(int argc, const char **argv, const char *prefix) git_config_set("receive.denyNonFastforwards", "true"); } + printf("%s%s Git repository in %s/\n", + reinit ? "Reinitialized existing" : "Initialized empty", + shared_repository ? " shared" : "", + git_dir); + return 0; } -- cgit v1.3