Skip to content

Commit 183aa11

Browse files
gnpricegnprice
committed
doc/setup: Say to set core.autocrlf on Windows; add troubleshooting
See the chat threads linked from the text: https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/flutter.20json_annotation.20unexpected.20behavior/near/1824410 https://chat.zulip.org/#narrow/stream/516-mobile-dev-help/topic/generated.20plugin.20files.20changed/near/1944826
1 parent 12f39ea commit 183aa11

File tree

2 files changed

+101
-0
lines changed

2 files changed

+101
-0
lines changed

‎README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,11 @@ Parts of our test suite require an additional dependency:
106106

107107
5. Install SQLite, for example by running `sudo apt install libsqlite3-dev`.
108108

109+
Developing on Windows requires
110+
an [additional step](docs/setup.md#autocrlf):
111+
112+
6. Run `git config core.autocrlf input`.
113+
109114
For more details and help with unusual configurations,
110115
see our [full setup guide](docs/setup.md).
111116

‎docs/setup.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,33 @@ This file covers specific topics in more detail.
88
[readme-setup]: https://github.com/zulip/zulip-flutter#setting-up
99

1010

11+
<div id="autocrlf" />
12+
13+
## Windows
14+
15+
If you've checked out the repo on Windows, then by default
16+
Git will convert the `\n` character at the end of each line
17+
to the `\r\n` sequence that is traditional on Windows.
18+
These are also called LF and CRLF line endings.
19+
20+
You'll need to disable this Git behavior. To do that, run
21+
the command
22+
`git config core.autocrlf input`
23+
from inside your checkout.
24+
25+
If you want to disable this behavior for all your Git checkouts
26+
of other projects, the command
27+
`git config --global core.autocrlf input`
28+
will do that.
29+
30+
With the default behavior, you may see Git report certain files
31+
as modified when nothing should have changed them. For details,
32+
or to fix such modifications once they're present,
33+
see the troubleshooting section
34+
["Unexpected modified files on Windows"](#windows-modified-files)
35+
below.
36+
37+
1138
## Android without Android Studio
1239

1340
The standard [Flutter installation guide](https://docs.flutter.dev/get-started/install)
@@ -57,3 +84,72 @@ To set up the development environment on Linux without Android Studio:
5784
or send a PR.)
5885

5986
[`#mobile-dev-help`]: https://chat.zulip.org/#narrow/stream/516-mobile-dev-help
87+
88+
89+
## Troubleshooting
90+
91+
92+
<div id="windows-modified-files" />
93+
94+
### Unexpected modified files on Windows
95+
96+
On Windows, you might find Git reporting certain files are modified
97+
when you haven't made any changes that should affect them. For
98+
example:
99+
```
100+
$ git status
101+
…
102+
modified: linux/flutter/generated_plugin_registrant.cc
103+
modified: linux/flutter/generated_plugin_registrant.h
104+
modified: linux/flutter/generated_plugins.cmake
105+
modified: macos/Flutter/GeneratedPluginRegistrant.swift
106+
modified: windows/flutter/generated_plugin_registrant.cc
107+
modified: windows/flutter/generated_plugin_registrant.h
108+
modified: windows/flutter/generated_plugins.cmake
109+
```
110+
111+
or:
112+
```
113+
$ git status
114+
…
115+
modified: lib/api/model/events.g.dart
116+
modified: lib/api/model/initial_snapshot.g.dart
117+
modified: lib/api/model/model.g.dart
118+
…
119+
modified: lib/model/internal_link.g.dart
120+
```
121+
122+
When seeing this issue, `git diff` will report lines like:
123+
```
124+
warning: in the working copy of 'linux/flutter/generated_plugin_registrant.cc', LF will be replaced by CRLF the next time Git touches it
125+
```
126+
127+
To fix the issue, run the command `git config core.autocrlf input`.
128+
129+
Then use `git restore` or `git reset` to restore the affected files
130+
to the version that Git expects.
131+
For example you can run `git reset --hard` to restore all files
132+
in the checkout to the version from the current HEAD commit.
133+
134+
The background of the issue is described [above](#autocrlf).
135+
Specifically, the affected files are generated files,
136+
and the tools from the Flutter and Dart ecosystems that
137+
generate the files are generating them with LF line endings (`\n`)
138+
regardless of platform. When Git is translating line endings
139+
to CRLF (`\r\n`), which it does by default, this means the
140+
freshly generated files don't match what Git expects.
141+
142+
Even though CRLF line endings are traditional for Windows,
143+
most Windows tools today work just as well with LF line endings.
144+
So the fix is to use the same LF line endings that we use
145+
on Linux and macOS.
146+
147+
A similar effect can be gotten with `git config core.eol lf`.
148+
The reason we recommend a different fix above is that
149+
the `core.eol` setting is overridden if you happen to have
150+
`core.autocrlf` set to `true` in your global Git config.
151+
152+
For the original reports and debugging of this issue, see
153+
chat threads
154+
[here](https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/flutter.20json_annotation.20unexpected.20behavior/near/1824410)
155+
and [here](https://chat.zulip.org/#narrow/stream/516-mobile-dev-help/topic/generated.20plugin.20files.20changed/near/1944826).

0 commit comments

Comments
 (0)