github.com/jonsyu1/godel@v0.0.0-20171017211503-64567a0cf169/docs/Format.md (about)

     1  Summary
     2  -------
     3  `./godelw format` formats all of the Go files in a project by running `gofmt` and `ptimports` on them.
     4  
     5  Tutorial start state
     6  --------------------
     7  
     8  * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory
     9  * Project contains `godel` and `godelw`
    10  * Project contains `main.go`
    11  * Project contains `.gitignore` that ignores IDEA files
    12  
    13  ([Link](https://github.com/nmiyake/echgo/tree/0c815bfd02711336f5ec0124377c95829667928a))
    14  
    15  Format code
    16  -----------
    17  
    18  Update the program code to put the echo functionality into a separate package and call it from the main project:
    19  
    20  ```
    21  ➜ mkdir -p echo
    22  ➜ echo 'package echo
    23  func Echo(in string) string {
    24  	fmt.Println(strings.Join(os.Args[1:], " "))
    25  }' > echo/echo.go
    26  ➜ echo 'package main
    27  
    28  import (
    29  	"fmt"
    30  	"os"
    31  	"strings"
    32  	"github.com/nmiyake/echgo/echo"
    33  )
    34  
    35  func main() {
    36  	fmt.Println(echo.Echo(strings.Join(os.Args[1:], " ")))
    37  }' > main.go
    38  ```
    39  
    40  Stage these files as a git commit:
    41  
    42  ```
    43  ➜ git add echo main.go
    44  ➜ git status
    45  On branch master
    46  Changes to be committed:
    47    (use "git reset HEAD <file>..." to unstage)
    48  
    49  	new file:   echo/echo.go
    50  	modified:   main.go
    51  
    52  ```
    53  
    54  Run `./godelw format` to format all of the files in the project:
    55  
    56  ```
    57  ➜ ./godelw format
    58  ```
    59  
    60  This command formats all of the files using `gofmt` and `ptimports`. Verify that this command modified the files:
    61  
    62  ```
    63  ➜ git status
    64  On branch master
    65  Changes to be committed:
    66    (use "git reset HEAD <file>..." to unstage)
    67  
    68  	new file:   echo/echo.go
    69  	modified:   main.go
    70  
    71  Changes not staged for commit:
    72    (use "git add <file>..." to update what will be committed)
    73    (use "git checkout -- <file>..." to discard changes in working directory)
    74  
    75  	modified:   echo/echo.go
    76  	modified:   main.go
    77  
    78  ➜ git diff | cat
    79  diff --git a/echo/echo.go b/echo/echo.go
    80  index f7d4dbe..3e055c2 100644
    81  --- a/echo/echo.go
    82  +++ b/echo/echo.go
    83  @@ -1,4 +1,5 @@
    84   package echo
    85  +
    86   func Echo(in string) string {
    87   	fmt.Println(strings.Join(os.Args[1:], " "))
    88   }
    89  diff --git a/main.go b/main.go
    90  index 1d9820b..9087898 100644
    91  --- a/main.go
    92  +++ b/main.go
    93  @@ -4,6 +4,7 @@ import (
    94   	"fmt"
    95   	"os"
    96   	"strings"
    97  +
    98   	"github.com/nmiyake/echgo/echo"
    99   )
   100  
   101  ```
   102  
   103  In `main.go`, note how the `github.com/nmiyake/echgo/echo` import has been separated from the other imports.
   104  `ptimports` groups imports into distinct sections consisting of the standard library imports, external imports and
   105  imports that are part of the same package.
   106  
   107  Commit the formatted files:
   108  
   109  ```
   110  ➜ git add main.go echo
   111  ➜ git commit -m "Create echo package"
   112  [master 24f63f7] Create echo package
   113   2 files changed, 8 insertions(+), 1 deletion(-)
   114   create mode 100644 echo/echo.go
   115  ➜ git status
   116  On branch master
   117  nothing to commit, working directory clean
   118  ```
   119  
   120  Tutorial end state
   121  ------------------
   122  
   123  * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory
   124  * Project contains `godel` and `godelw`
   125  * Project contains `main.go`
   126  * Project contains `.gitignore` that ignores IDEA files
   127  * Project contains `echo/echo.go`
   128  
   129  ([Link](https://github.com/nmiyake/echgo/tree/24f63f727542c7189c82f04f7e2a4aa38c090137))
   130  
   131  Tutorial next step
   132  ------------------
   133  
   134  [Run static checks on code](https://github.com/palantir/godel/wiki/Check)
   135  
   136  More
   137  ----
   138  
   139  ### Differences between `./godelw format` and `gofmt -w ./...`
   140  
   141  `./godelw format` has the following advantages over running `gofmt -w ./...`
   142  
   143  * Only formats files that are part of the project (does not format files in excluded directories)
   144  * Runs `ptimports` in addition to `gofmt`
   145  
   146  `ptimports` groups Go imports into 3 groups: the Go standard library, packages that are not part of the current project
   147  and packages that are part of the current project.
   148  
   149  The output of `./godelw format` is compatible with `gofmt` (that is, it is guaranteed that applying `gofmt` to a file
   150  formatted by `./godelw format` will be a no-op).
   151  
   152  ### `--list` flag
   153  
   154  Running `./godelw format` with the `--list` (or `-l`) flag will output the files that would be changed if
   155  `./godelw format` were run without actually applying the changes.