branch: improve documentation and naming of create_branch() parameters

The documentation for 'create_branch()' was incomplete as it didn't say
what certain parameters were used for. Further a parameter name wasn't
very communicative.

So, add missing documentation for the sake of completeness and easy
reference. Also, rename the concerned parameter to make its name more
communicative.

Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/branch.c b/branch.c
index 62f7b0d8c2d6a89fde5abffb6c836d0ce7706ac4..3e8d2f93f8be6b4c92c17d6bb682719fb03f5e41 100644 (file)
--- a/branch.c
+++ b/branch.c
@@ -228,7 +228,7 @@ N_("\n"
 "\"git push -u\" to set the upstream config as you push.");
 
 void create_branch(const char *name, const char *start_name,
-                  int force, int reflog, int clobber_head,
+                  int force, int reflog, int clobber_head_ok,
                   int quiet, enum branch_track track)
 {
        struct commit *commit;
@@ -244,7 +244,7 @@ void create_branch(const char *name, const char *start_name,
 
        if (validate_new_branchname(name, &ref, force,
                                    track == BRANCH_TRACK_OVERRIDE ||
-                                   clobber_head)) {
+                                   clobber_head_ok)) {
                if (!force)
                        dont_change_ref = 1;
                else

diff --git a/branch.h b/branch.h
index b07788558c0e76a701b571f73c0462dcf2abcc63..cb6411f840548c1ec27dcc08f665c94a322da2d7 100644 (file)
--- a/branch.h
+++ b/branch.h
@@ -15,12 +15,17 @@
  *
  *   - reflog creates a reflog for the branch
  *
+ *   - clobber_head_ok allows the currently checked out (hence existing)
+ *     branch to be overwritten; without 'force', it has no effect.
+ *
+ *   - quiet suppresses tracking information
+ *
  *   - track causes the new branch to be configured to merge the remote branch
  *     that start_name is a tracking branch for (if any).
  */
 void create_branch(const char *name, const char *start_name,
                   int force, int reflog,
-                  int clobber_head, int quiet, enum branch_track track);
+                  int clobber_head_ok, int quiet, enum branch_track track);
 
 /*
  * Validates that the requested branch may be created, returning the