On Friday 25 March 2016 11:08 PM, Junio C Hamano wrote: > Sidhant Sharma <tigerkid001@xxxxxxxxx> writes: > >> $ ggit rebase >> >> [WARNING] You are about to rebase your commits in <topic-branch> onto the >> $BASE_BRANCH, which will essentially replay the work done in $TOPIC_BRANCH >> since last merge onto $BASE_BRANCH. >> For instance, >> Current state: >> >> o---o---A---B $BASE_BRANCH >> \ >> X---Y $TOPIC_BRANCH >> >> State after rebasing: >> >> o---o---A---B---X'---Y' $BASE_BRANCH >> \ >> X---Y $TOPIC_BRANCH >> >> where X' and Y' are the commits making changes identical to those made by X and >> Y respectively. > The topology may be correct, but the branch labels are both wrong, > no? The tip of the base branch will stay at B, and the tip of the > topic will point at Y'. Thanks for pointing that out, will correct that. >> Rebasing is not usually problematic except in cases when you are rebasing >> commits that do not exist in your repository. > This cannot be correct, as you fundamentally cannot work on (not > limited to rebasing) commits that do not exist in your repository. > Actually I meant to refer to the commits that exist outside the local repo (eg. on the remote), like it says in the 'The Perils of Rebasing' section of the Git Branching and Rebasing documentation [1]. I'll rephrase it to make it clearer. >> $ ggit reset --hard >> >> Resetting to <destination-commit-hash> >> [WARNING] You are about to hard reset the current HEAD (master) by <n> commit(s). > If I were on B and did "git reset --hard Y", i.e. > > o---o---A---B $CURRENT_BRANCH > \ > X---Y $CURRENT_BRANCH_AFTER_RESETTING > > does the phrasing "about to reset by <n> commit(s):" make any sense? > >> This will take you back to commit <destination-commit-hash>, and discard all >> changes make thereafter. For instance, >> Current state: >> >> o---o---A---B---C---D---E $CURRENT_BRANCH >> >> After resetting 3 commits: >> >> o---o---A---B $CURRENT_BRANCH > The above two examples make me wonder if these should be static > text. "ggit rebase" and "ggit reset" have full information of the > concrete branch names, commit object names and the actual topology > of the history, so it should be able to give a description more > tailored to the user's situation. Instead of giving a fictional > drawing with "For instance, Current state:", it should be able to > draw the actual before-and-after picture based on where the end-user > actually is. I see _some_ attempts (e.g. with "<n>", mention of > "(master)" and $BASE_BRANCH, you may have meant that they will be > replaced with actual values), but I suspect that telling some truth > (i.e. use of the real branch names) while showing pictures that do > not match the reality (i.e. if the topology and the description are > done as fixed text) would only confuse the users. On Sunday 27 March 2016 01:06 PM, Jacob Keller wrote: > On Sat, Mar 26, 2016 at 8:12 AM, Matthieu Moy > <Matthieu.Moy@xxxxxxxxxxxxxxx> wrote: >> Jacob Keller <jacob.keller@xxxxxxxxx> writes: >> >>> If possible, I would suggest aiming for generating the actual topology >>> that the user is seeing, customized so that it gives relevenat >>> information, rather than static examples. >> Using the real topology in a useful way is actually pretty hard. It's >> quite easy to throw the output of "git log --graph --oneline ..." to the >> user, but as soon as the rebase deals with more than a handfull of >> commits, we'd want to simplify the history to show something >> understandable to the user (which by definition should be a beginner if >> he uses ggit), like replacing long sequences of commits with "..." or >> so. That is hard to get right. >> > Yes, in which case we should go Junio's route of not using anything > from the real topology. > I now understand why using the actual names with a hypothetical topology would only confuse the user. I'll update the diagrams with hypothetical names. Also, other than these commands, what others should I include in the list? I think we may also have warnings for the following: * git checkout -- <path> * git rm --cached * git stash drop [<stash>] * git stash clear * All plumbing commands? Comments? Thanks and regards, Sidhant Sharma [1]: https://git-scm.com/book/en/v2/Git-Branching-Rebasing#The-Perils-of-Rebasing -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html