[PATCH] Documentation: add a planning document for the next CLI revamp

From

Sam Vilain <sam@vilain.net>

Date

Oct 30, 2008, 03:48 UTC

Message-ID

<1225338485-11046-1-git-send-email-sam@vilain.net>

From: Sam Vilain <samv@vilain.net>

Signed-off-by: Sam Vilain <sam@vilain.net>
---
 Some suggestions, which have been briefly scanned over by some of the
 (remaining @4pm) GitTogether attendees.

 Please keep it constructive! :)

 Documentation/cli-revamp.txt |  135 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 135 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/cli-revamp.txt

diff --git a/Documentation/cli-revamp.txt b/Documentation/cli-revamp.txt
new file mode 100644
index 0000000..980ea07
--- /dev/null
+++ b/Documentation/cli-revamp.txt
@@ -0,0 +1,135 @@
+GIT command line revamp
+=======================
+
+This design document is designed for review and critique over planned
+direction for changing the command set used by git, rather than
+reviewing and critiquing individual changes.
+
+In general, old commands will be grandfathered for a year or longer,
+and all plumbing commands will still work as originally designed.
+
+Please bear in mind when critiquing that each of these changes might
+themselves have a progressive implementation, for instance the new
+behaviour being optional initially.
+
+Please try to be positive with your comments; let's try to come up
+with solutions and not argue about the details of the solutions
+presented until those details are submitted.  In particular, critical
+comments that do not acknowledge the presence of a problem are
+worthless at this stage.
+
+Add/rm/reset/checkout/revert
+----------------------------
+
+Many find these confusing.
+
+  * 'git stage' would do what 'git add' does now.
+
+  * 'git unstage' would do what 'git reset --' does now
+
+  * 'git status' would encourage the user to use
+    'git diff --staged' to see staged changes as a patch
+
+  * 'git commit' with no changes should give useful information about
+    using 'git stage', 'git commit -a' or 'git commit filename ...'
+
+  * 'git add' and 'git rm': no change
+
+  * 'git update-index' considered plumbing, not changed
+
+  * 'git revert' deprecated in favour of 'git cherry-pick --revert'
+
+  * 'git undo' would do what 'git checkout HEAD --' does now
+
+  * 'git checkout branch' would, if there is a remote branch called
+    'branch' on exactly one remote, do what
+    'git checkout -b branch thatremote/branch' does now.  If it is
+    ambiguous, it would be an error, forcing the explicit notation.
+
+  * 'git branch --switch' : alternative to checkout
+
+
+Push/pull
+---------
+
+These commands are asymmetric, and this seems mostly historical.
+
+  * 'git push --matching' does what 'git push' does today (without
+    explicit configuration)
+
+  * 'git push' with no ref args and no 'push =' configuration does
+    what:
+    'git push origin $(git symbolic-ref HEAD | sed "s!refs/heads/!!")'
+    does today.  ie, it only pushes the current branch.
+    If a branch was defined in branch.<name>.push, push to that ref
+    instead of the matching one.  If there is no matching ref, and
+    there is a branch.<name>.merge, push back there.
+
+  * 'git pull' behaviour unchanged
+
+  * 'git push' to checked out branch of non-bare repository not
+    allowed without special configuration.  Configuration available
+    that allows working directory to be updated, known caveats
+    notwithstanding.  Ideally, it would refuse only in situations
+    where a broken working copy would be left (because you couldn't
+    fix it), and work when it can be known to be safe.
+
+
+Informational
+-------------
+
+  * 'git branch' should default to '--color=auto -v'
+
+  * 'git tag -l' should show more information
+
+
+Working with patches
+--------------------
+
+  * 'git send-email' should prompt for all SMTP-related information
+    about sending e-mail when it is running with no configuration.
+    Because these days /usr/lib/sendmail is rarely configured
+    correctly.
+
+  * other git send-email functionality which has bitten people -
+    particularly building the recipient list - should prompt for
+    confirmation until configured to be automatic.
+
+  * 'git am -3' the default; with global option to make it not the
+    default for those that prefer the speed of -2
+
+
+Submodules
+----------
+
+  * submodules should be able to refer to symbolic ref names, svn
+    style - in the .gitmodules file.  The actual commit used is still
+    recorded in the index.
+
+  * when switching branches, if the checked out revision of a submodule
+    changes, then it should be switched as well
+
+  * 'git submodule update' should be able to be triggered when
+    switching branches (but not be the default behaviour)
+
+
+Others
+------
+
+  * 'git export' command that does what
+    'git archive --format=tar --prefix=dir | tar x' does now
+
+  * conflicted merges should point the user immediately to
+    'git mergetool' and mention you need to use 'git stage' to mark
+    resolved files and 'git commit' when done.
+
+  * 'git init --server' (or similar) should do everything required for
+    exporting::
+----
+chmod -R a+rX
+touch git-daemon-export-ok
+git gc
+git update-server-info
+chmod u+x .git/hooks/post-update
+git config core.sharedrepository=1
+----

-- 
debian.1.5.6.1